Mem0 skills 目录工程实践:Reference 与 Pipeline 技能的双轨架构、尺寸预算与 Frontmatter 规范

Mem0 仓库的 skills/ 目录对外发布一组面向 AI 编码助手的技能定义,其内部有一份面向维护者的工程规范文档。本文以 skills/CLAUDE.md 为核心,完整拆解这套技能系统的两类划分(Reference 技能与 Pipeline 技能)、标准目录布局、SKILL.md 的 500 行尺寸预算、Frontmatter 路由规范与四条维护约定,并结合仓库内真实的技能实现逐项印证,帮助读者掌握"如何为一个 SDK 设计可被 Agent 路由、加载和执行的技能包"。

一、skills/ 目录的定位:每个文件都是公共 API

skills/CLAUDE.md(内容与 skills/AGENTS.md 相同,分别面向不同的编码助手)开篇即给出整个目录的基调:

"Claude Code skill definitions published from this repo. Agents fetch them by raw URL, so treat every file here as a public API."

也就是说,这些技能文件会被各类支持 skills 标准的助手(仓库 skills/README.md 中列出了 Claude Code、Codex、Cursor、OpenCode、OpenClaw 等)按原始文件地址拉取并注入上下文。由此推出两条工程结论:

• 目录内任何一个文件的路径、命名、字段结构变更,都等同于修改公共接口,必须谨慎;
• 文件之间交叉引用一律使用相对路径,保证技能被"vendored(复制)进别的仓库"后依然可用——这是文末 Conventions 的第四条,也是 skills/mem0/SKILL.md 中"Skill Graph"导航区使用 ../mem0-cli/SKILL.md 这类相对链接的原因。

从源码结构看,当前目录共包含 6 个技能包,目录形态与规范文档描述完全一致:

目录	包含文件
skills/mem0/	SKILL.md、README.md、LICENSE、references/(7 个主题文件)、client/(3 个运行时参考)、scripts/mem0_doc_search.py
skills/mem0-cli/	SKILL.md、references/(command-reference、configuration、workflows)
skills/mem0-integrate/	SKILL.md、references/pipeline.md、references/subagent-prompts.md
skills/mem0-test-integration/	仅 SKILL.md(验证逻辑全部内联)
skills/mem0-oss-to-platform/	SKILL.md、references/(api-mapping、gotchas、plan-template)
skills/mem0-vercel-ai-sdk/	SKILL.md、references/(memory-utilities、provider-api、usage-patterns)

二、两类技能:Reference 技能与 Pipeline 技能

规范文档将技能明确划分为两种"物种",二者的运行模型完全不同,这是理解整个 skills 目录的主线。

2.1 Reference 技能:承载 SDK 知识,常驻可用

Reference 技能"携带 SDK 知识、始终可用",本质是把正确的 API 用法、版本约束与排错经验注入助手上下文,让它写出正确的 Mem0 代码。仓库内共有 3 个:

技能	覆盖范围
mem0/	Python + TypeScript 双 SDK、Platform(托管)与 OSS(自托管)两条线、框架集成(LangChain、CrewAI、OpenAI Agents SDK 等)
mem0-cli/	mem0-cli(pip)与 @mem0/cli(npm)两套终端工作流
mem0-vercel-ai-sdk/	@mem0/vercel-ai-provider 包,即 Vercel AI SDK 场景下的 createMem0 用法

以 skills/mem0/SKILL.md 为例,可以看到 Reference 技能的典型组织方式:Frontmatter 声明触发条件后,正文按"安装认证 → 初始化客户端 → 核心操作(add/search/get_all/update/delete)→ 常见集成模式(retrieve → generate → store)→ 边界情况 → 版本兼容"推进,并附两张"按需加载"的索引表,把深水区内容指向 client/python.md(487 行)、references/use-cases.md(720 行)等参考文件,而不是全部内联。

2.2 Pipeline 技能:按需触发,带有副作用

Pipeline 技能被显式调用后执行端到端工作流,会真实地创建分支、写测试、跑代码,因此规范对它们的约束远严于 Reference 技能:

技能	行为
mem0-integrate/	通过 TDD 流水线把 Mem0 接入现有仓库,产出特性分支 + .mem0-integration/ 工件
mem0-test-integration/	在同一分支上验证 integrator 的产物;对目标仓库只读
mem0-oss-to-platform/	把项目从 OSS 迁移到托管 Platform SDK;先出计划,批准后执行

skills/CLAUDE.md 特别强调 mem0-integrate 与 mem0-test-integration 是**松散耦合(loosely coupled)**的:二者只通过 .mem0-integration/ 目录下的文件共享状态,绝不通过对话上下文共享。这一设计在两个技能的实现中得到印证:

• skills/mem0-integrate/SKILL.md 的 Artifacts 表定义了 7 个工件(repo-summary.md、goal.md、plan.md、trace.jsonl、diff.patch、heal-trace.md、product.json),并明确"首次运行时把 .mem0-integration/ 加入 .gitignore,不向该目录与源码树之外写任何东西";
• skills/mem0-test-integration/SKILL.md 的入口逻辑则是"读取 .mem0-integration/plan.md 中的 Delegated skill: 字段"——验证方完全依赖 integrator 落盘的文件做判断,这正是"只共享文件、不共享会话"的落地。

此外,migration 类技能 mem0-oss-to-platform 也体现了 Pipeline 技能"计划先行、批准后执行"的纪律:其 SKILL.md 规定 Phase 1–4 只产出 MEM0_MIGRATION_PLAN.md 计划并停下等待审批,Phase 5 才动代码。

三、文件布局:skills/<name>/ 的标准结构

规范文档给出每个技能包的标准布局:

skills/<name>/
├── SKILL.md          入口,技能触发时总是被完整加载
├── README.md         面向人类,GitHub 上渲染
├── LICENSE           Apache-2.0
├── references/       按需加载,一个主题一个文件
├── client/           可选,按运行时分列的调用模式
└── scripts/          可选的可执行脚本

对照实际目录可见,这套布局被严格执行且按需裁剪:mem0/ 是全功能形态(含 client/ 与 scripts/,其中 scripts/mem0_doc_search.py 供助手在运行时检索官方文档,支持 --query/--page/--index 三种方式);mem0-test-integration/ 则精简到只有 SKILL.md——因为其全部验证逻辑都需要常驻生效,没有"按需加载"的空间。

四、尺寸预算:为什么 SKILL.md 必须压在 500 行以内

这是规范文档中最具工程洞察的章节。SKILL.md 在技能每次触发时都被完整加载进上下文,它是"最贵的文件",因此规范设定硬预算:500 行以内。超出决策核心的内容一律下沉到 references/,后者只在助手真正需要该主题时才被读取。

规范给出了"什么留在 SKILL.md"的判断准则:

• Frontmatter(含触发与不触发条件);
• 每次运行都必须遵守的内容:不可协商的原则、前置条件、门控(gates);
• 一行一步的流水线概览;
• 调用方式、模式、退出码。

其余一切——完整步骤机制、文档模板、逐字的子代理提示词——都进 references/,并由概览链接过去。

4.1 现行尺寸清单(已核对)

文档附有一份"从长到短"的尺寸表。用 wc -l 对当前仓库重新核对,十个文件行数与文档完全一致:

mem0/references/use-cases.md              720   reference, on demand
mem0-cli/references/command-reference.md  694   reference, on demand
mem0/client/python.md                     487   reference, on demand
mem0-integrate/references/pipeline.md     375   reference, on demand
mem0-test-integration/SKILL.md            368   entry point, under budget
mem0-integrate/SKILL.md                   220   entry point
mem0/SKILL.md                             193   entry point
mem0-vercel-ai-sdk/SKILL.md               192   entry point
mem0-cli/SKILL.md                         169   entry point
mem0-oss-to-platform/SKILL.md             120   entry point

从源码结构看,清单揭示出清晰的成本模型:所有 SKILL.md 入口文件都远低于 500 行上限(最大 368 行),而参考文件可以任意长——use-cases.md 达 720 行,但"一次从不打开它的运行,这 700 行的成本为零"。

4.2 实例:mem0-integrate 的拆分(620 行 → 220 行)

文档专门记录了唯一一次被迫拆分:

• 拆分前:mem0-integrate/SKILL.md 620 行,超预算;
• 拆分后:220 行,十步流水线机制移入 references/pipeline.md(375 行),两段逐字的子代理系统提示词移入 references/subagent-prompts.md;
• 入口文件只保留"每次运行必须遵守"的内容:规范来源(canonical sources)、七条集成原则、委托表(delegation table)、前置条件、一行一步的流水线概览、工件、模式、调用方式与退出码。

拆分后的 skills/mem0-integrate/SKILL.md 验证了这一点:Pipeline 章节只剩一张"十步 + 门控"的路由表,并写明"完整机制、文档模板与门控规则见 references/pipeline.md;开始执行某一步时再读那个文件;下面的摘要只用于路由"。

五、Frontmatter 规范:技能路由的地基

规范文档给出的 Frontmatter 模板如下:

---
name: <与目录名一致>
description: >
  说明它能做什么,然后 TRIGGER when: ... 再 DO NOT TRIGGER when: ...
  触发条件是路由的依据。要具体,并点名应该改用的兄弟技能。
license: Apache-2.0
metadata:
  author: mem0ai
  version: "0.1.0"
  category: ai-memory
  tags: "comma, separated"
  mem0_tested_versions: "mem0ai (PyPI) >=2.0.0,<3.0.0; mem0ai (npm) >=3.0.0,<4.0.0"
---

对照仓库内六个技能的真实 Frontmatter,可以提炼出几条可验证的实现细节:

• name 与目录名严格一致:mem0、mem0-cli、mem0-integrate 等全部满足;
• 触发/不触发条件成对书写,且互相指名。例如 skills/mem0/SKILL.md 的 description 声明"当用户提到 mem0、MemoryClient、长期记忆、个性化时 TRIGGER……当用户问 CLI 命令时用 mem0-cli,问 Vercel AI SDK 时用 mem0-vercel-ai-sdk DO NOT TRIGGER",并自述"这是歧义查询下的 DEFAULT mem0 技能"。这种"点名交接"直接服务于 CLAUDE.md Conventions 的第二条(委托而非复述);
• 版本钉住字段。带副作用的流水线技能统一声明 mem0_tested_versions: "mem0ai (PyPI) >=2.0.0,<3.0.0; mem0ai (npm) >=3.0.0,<4.0.0"(见 skills/mem0-integrate/SKILL.md 与 skills/mem0-test-integration/SKILL.md);Reference 技能则改用 compatibility 字段描述运行环境要求,例如 skills/mem0-cli/SKILL.md 声明 "Node.js 18+ 或 Python 3.10+,需要 MEM0_API_KEY"。这与仓库本体状态吻合:当前 pyproject.toml 中 Python SDK 版本为 2.0.19(requires-python = ">=3.10,<4.0"),落在 PyPI 测试区间内;
• 规范的动机。文档解释了为何要 mem0_tested_versions:"每当 SDK 主版本变动就更新它。把调用形态钉死在已不存在的版本上的技能,会生成运行时失败代码——这比技能拒绝触发更糟。"换言之,版本区间是"技能宁可不开火也不开错火"的熔断机制。

六、四条维护约定(Conventions)

规范文档最后给出四条约定,每一条都能在仓库中找到对应的实现证据:

1. 引用规范来源,而不是依赖模型的"氛围知识"。技能必须按 URL 引用官方来源(如官方文档的 llms.txt 索引、openapi.json、各技能的 raw 地址),不得依赖模型对 Mem0 API 的模糊记忆。证据:skills/mem0-integrate/SKILL.md 设有一个 "Canonical sources (fetch before deciding anything)" 章节,要求在动手前 WebFetch 文档索引、完整文档、OpenAPI 规格,并在 plan.md 中引用;"ground truth — do not rely on ambient knowledge of the Mem0 API"。
2. 领域被另一个技能覆盖时,按 raw URL 委托,而不是复述它的模式。证据:mem0-integrate 的 "Skill delegation rules" 章节(skills/mem0-integrate/SKILL.md)给出委托表——检测到 @ai-sdk/* + ai 依赖就委托 skills/mem0-vercel-ai-sdk,CLI-only 仓库委托 skills/mem0-cli,其余 Python/TS 仓库默认委托 skills/mem0——并要求把被委托技能的 raw URL 记入 plan.md 的 Delegated skill: 字段,供后续步骤的测试编写者实现子代理共同读取。
3. Pipeline 技能用表格声明退出码,并且"说到做到"。证据:skills/mem0-integrate/SKILL.md 定义了 0–6 共七个退出码,语义精确到"目标文档被拒 3 次 → exit 3""子代理评审 3 轮未收敛 → exit 4""自愈循环检测到非侵入性违规或既有测试失败 → exit 6"。这些码与十步流水线的门控一一对应,可被 CI 脚本机械消费。
4. 文件间交叉引用使用相对路径,保证技能被 vendored 进其他仓库后依然工作。证据:mem0/SKILL.md 的 Skill Graph 区使用 ../mem0-cli/SKILL.md 相对链接;mem0-integrate/SKILL.md 引用机制文件用 references/pipeline.md 相对路径。

七、面向使用者的视角:这些技能如何被安装与选择

skills/README.md 给出了使用侧的对应视图,与 CLAUDE.md 的维护侧规范互为表里:

• 安装:通过 skills 标准工具,以 npx skills add <仓库地址> --skill <技能名> 的形式按技能逐个安装,例如 --skill mem0、--skill mem0-integrate;
• 选型口诀:写 Mem0 代码用 mem0;终端 CLI 用 mem0-cli;基于 @ai-sdk/* 开发用 mem0-vercel-ai-sdk;想让助手把 Mem0 接入现有仓库,先 /mem0-integrate 再 /mem0-test-integration;从 OSS 迁到托管平台用 mem0-oss-to-platform。

其中集成 + 验证的组合工作流在 README 中被概括为:

/mem0-integrate          →  mem0-integrate/<slug> 分支 + .mem0-integration/ 工件
/mem0-test-integration   →  记分卡(编译 + 运行时验证 + 真实 API 冒烟)

这与 CLAUDE.md 描述的松散耦合模型闭环:integrator 落盘工件,test-integration 读取工件,两者之间不存在隐式会话依赖。

八、小结:这套规范的可借鉴之处

通读 skills/CLAUDE.md 并对照六个技能包的实际实现,可以归纳出 Mem0 技能工程的四条主线,对任何"把 SDK 知识打包给 AI 助手"的场景都可直接复用:

1. 双轨划分:无副作用的知识型技能(Reference)与有副作用的工作流技能(Pipeline)分开设计,后者必须声明前置条件、门控与退出码;
2. 入口文件即成本:SKILL.md 受 500 行硬预算约束,只放"每次运行必须遵守"的内容,细节按需下沉到 references/;
3. 路由靠 Frontmatter:触发/不触发条件具体到命令名、包名,并点名交接的兄弟技能;版本区间(mem0_tested_versions)随 SDK 主版本联动更新;
4. 把每个文件当公共 API:引用官方来源而非模型记忆、按 URL 委托而非复述、退出码写成契约、交叉引用只用相对路径。

结合 skills/ 目录下的真实技能包(入口文件 120–368 行、参考文件 375–720 行、十步流水线与七个退出码的完整落地),这套规范已从文档层面推进到可验证的工程事实,是观察 Mem0"Memory Layer for AI Agents"战略向 Agent 生态渗透的一个具体切口。