Mem0 Skills 全解析：用官方 Agent Skill 为 Claude Code、Cursor、Codex 与 OpenClaw 注入 AI 记忆能力

Mem0（本项目即其开源仓库）以结构化 Skill 定义的形式，为 Claude Code、Codex、Cursor、OpenCode、OpenClaw 以及任何遵循 Anthropic 提出的 skills 标准的 AI 编码助手提供开箱即用的记忆能力接入方案。本文将围绕 skills/README.md 这一官方目录清单，拆解其「参考型（Reference）」与「流水线型（Pipeline）」两类 Skill 的定位、安装方式、目录结构与底层约定，并结合 skills/AGENTS.md 及各 Skill 的 SKILL.md 源码级实现，帮助你为日常开发选择一个最合适的记忆接入入口——无论是让助手写出正确的 SDK 代码，还是让它替你端到端地把 Mem0 接进现有仓库。

Mem0 Skills 是什么

AI 编码助手（coding assistant）虽然拥有强大的代码生成能力，但对具体 SDK 的最新 API 形态、调用约束往往依赖"记忆中的知识"，容易产生过时或错误的调用。Mem0 的解决方案是：把经过验证的 SDK 知识和工作流沉淀为可发布的 Skill 文件，助手安装后即可在触发条件命中时加载到上下文，从而写出正确的 Mem0 代码，或在用户显式调用时执行一整套真实的工作流（建分支、写测试、跑代码）。

从仓库结构看，skills/ 目录本身是"从本仓库发布出去"的产物。正如 skills/AGENTS.md 所述，Agent 通过 raw URL 抓取这些文件，因此目录内每个文件都应被视为公共 API 来维护。所有 Skill 分为两大类：

两大类 Skill 总览

参考型 Skill（Reference Skills）—— 常驻上下文

安装一次，加载进上下文，让助手日常编写 Mem0 代码时始终遵循正确调用形态。适用于常规开发。

Skill	覆盖范围	安装命令
mem0	Python + TypeScript SDK（Platform 与 OSS）、框架集成	npx skills add https://github.com/mem0ai/mem0 --skill mem0
mem0-cli	终端工作流（mem0 CLI，Node 与 Python 双实现）	npx skills add https://github.com/mem0ai/mem0 --skill mem0-cli
mem0-vercel-ai-sdk	@mem0/vercel-ai-provider 与 createMem0	npx skills add https://github.com/mem0ai/mem0 --skill mem0-vercel-ai-sdk

流水线型 Skill（Pipeline Skills）—— 按需执行

以斜杠命令（slash command）形式调用，用于执行某个端到端工作流。它们会做真实的工作：创建分支、编写测试、运行代码，会产生副作用。

Skill	触发方式	安装命令
mem0-integrate	/mem0-integrate —— 通过 TDD 把 Mem0 接入现有仓库	npx skills add https://github.com/mem0ai/mem0 --skill mem0-integrate
mem0-test-integration	/mem0-test-integration —— 验证 /mem0-integrate 的产出	npx skills add https://github.com/mem0ai/mem0 --skill mem0-test-integration
mem0-oss-to-platform	/mem0-oss-to-platform —— 把项目从 Mem0 OSS 迁移到托管 Platform SDK	npx skills add https://github.com/mem0ai/mem0 --skill mem0-oss-to-platform

其中 mem0-integrate 与 mem0-test-integration 被设计为在同一工作区上按顺序执行的一对：

/mem0-integrate          →  mem0-integrate/<slug> 分支 + .mem0-integration/ 产物
/mem0-test-integration   →  评分卡（编译 + 运行期验证 + 真实 API 冒烟测试）

参考型 Skill 逐个解析

mem0：默认的 SDK 参考 Skill

mem0 是"语义模糊查询"时的默认 Skill（frontmatter 中明确标注 This is the DEFAULT mem0 skill for ambiguous queries）。它的触发条件涵盖：用户提到 mem0、MemoryClient、memory layer、remember user preferences、persistent context、personalization，或需要为聊天机器人、Agent、AI 应用增加长期记忆。覆盖 Python SDK（mem0ai）、TypeScript SDK（mem0ai）及 LangChain、CrewAI、OpenAI Agents SDK、Pipecat、LlamaIndex、AutoGen、LangGraph 等框架集成，同时覆盖开源自托管版 Memory 类。

从 skills/mem0/README.md 可以看清它的内部布局，这正是"参考型 Skill 应如何组织内容"的范本：

skills/mem0/
├── SKILL.md                    # Skill 定义与指令（常驻上下文）
├── README.md                   # 面向人类的说明（GitHub 渲染）
├── LICENSE                     # Apache-2.0
├── client/                     # 按运行时拆分的调用模式
│   ├── python.md               # Python SDK（MemoryClient + Memory OSS）
│   ├── node.md                 # TypeScript SDK（MemoryClient + Memory OSS）
│   └── differences.md          # Python 与 TypeScript 差异对比
├── scripts/
│   └── mem0_doc_search.py      # 按需检索在线文档
└── references/                 # 按主题拆分、按需加载的参考文档
    ├── quickstart.md           # 完整快速上手（Python、TS、cURL）
    ├── sdk-guide.md            # 全部 SDK 方法（Python + TypeScript）
    ├── api-reference.md        # REST 端点、过滤器、memory 对象
    ├── architecture.md         # 处理流水线、生命周期、作用域、性能
    ├── features.md             # 检索、图谱、分类、MCP、Webhook、多模态
    ├── integration-patterns.md # LangChain、CrewAI、OpenAI Agents 等
    └── use-cases.md            # 7 个真实世界模式（Python + TS 代码）

SKILL.md 中给出了一条极其凝练的集成主线 retrieve → generate → store（检索 → 生成 → 存储），并附有完整的最小可用示例，例如核心的通用集成模式：

from mem0 import MemoryClient
from openai import OpenAI

mem0 = MemoryClient()
openai = OpenAI()

def chat(user_input: str, user_id: str) -> str:
    # 1. 检索相关记忆
    memories = mem0.search(user_input, filters={"user_id": user_id})
    context = "\n".join([m["memory"] for m in memories.get("results", [])])
    # 2. 携带记忆上下文生成回复
    response = openai.chat.completions.create(
        model="gpt-5-mini",
        messages=[
            {"role": "system", "content": f"User context:\n{context}"},
            {"role": "user", "content": user_input},
        ]
    )
    reply = response.choices[0].message.content
    # 3. 把本次交互写回记忆
    mem0.add(
        [{"role": "user", "content": user_input}, {"role": "assistant", "content": reply}],
        user_id=user_id
    )
    return reply

SKILL.md 还刻意收录了一批常见边界情况的处置结论，例如：add() 之后记忆是异步处理的，搜索前需等待 2～3 秒；user_id 精确大小写匹配且要用 filters={"user_id": ...} 语法；user_id 与 agent_id 组合的 AND 过滤可能返回空，因为实体分开存储、应改用 OR 或分别查询；v3 版本默认值为 top_k=20、threshold=0.1、rerank=False。这些细节说明参考型 Skill 的目标是消灭调用方的试错成本。

此外它自带一个无需 API Key 的在线文档检索脚本（对应仓库中的 skills/mem0/scripts/mem0_doc_search.py）：

python ${CLAUDE_SKILL_DIR}/scripts/mem0_doc_search.py --query "topic"
python ${CLAUDE_SKILL_DIR}/scripts/mem0_doc_search.py --page "/platform/features/graph-memory"
python ${CLAUDE_SKILL_DIR}/scripts/mem0_doc_search.py --index

mem0-cli：终端工作流 Skill

mem0-cli 覆盖的是 Mem0 的命令行界面。当用户提到 mem0 cli、@mem0/cli、pip install mem0-cli、npm install -g @mem0/cli，或描述 mem0 add、mem0 search、mem0 list、mem0 init、mem0 config 等终端操作与 --user-id、--json、--agent 这类标志位时触发。

值得强调的仓库实现事实是 Node 与 Python 双实现的一致性：在 cli/ 目录下，Node 实现位于 cli/node/src/，Python 实现位于 cli/python/src/mem0_cli/，二者均由同一份规格 cli/cli-spec.json 驱动。它们共享完全相同的命令名、参数与标志位、输出格式（text/json/table/quiet）、实体 ID 解析逻辑、图三态、过滤器构建以及错误信息与退出码，因此"选哪个运行时装，行为都一样"。若需要以 JSON 消费 CLI 输出，--agent 是 --json 的别名，进度动画写入 stderr、stdout 始终保持干净的 JSON，适合 LLM 消费。

mem0-vercel-ai-sdk：Vercel AI SDK 记忆增强 Provider

mem0-vercel-ai-sdk 面向使用 Vercel AI SDK v5（ai 包 + LanguageModelV2/ProviderV2 接口）的 TypeScript 项目。其核心是 @mem0/vercel-ai-provider 包，提供两种使用形态：

• Wrapped Model（createMem0）：返回一个包装任意受支持 LLM 的 Provider，LLM 调用时自动完成记忆的检索与回写；
• Standalone Utilities（retrieveMemories / getMemories / searchMemories / addMemories）：由调用方手动控制记忆 retrieve/store 循环。

Wrapped Model 的底层流程在 SKILL.md 中有明确标注，可帮助你理解"自动记忆"的代价边界：

User prompt
  --> searchInternalMemories (POST /v3/memories/search/)
  --> memories injected as system message at start of prompt
  --> underlying LLM generates response (doGenerate or doStream)
  --> processMemories fires addMemories as fire-and-forget (no await)
  --> response returned to caller

注意 addMemories 是以 fire-and-forget（不 await）方式异步落库的，因此存储不阻塞 LLM 响应；也正因如此，参考型 Skill 强调每个 Skill 只覆盖自己的领地——使用 Vercel AI SDK 的记忆增强时不要绕道去写裸 MemoryClient 调用，直接用本 Skill 的 createMem0 包装器即可（见其 DO NOT TRIGGER 条件与相关 Skill 指引）。

流水线型 Skill：真实工作流的两对组合

与"只教知识"的参考型不同，流水线型 Skill 被设计为"真正替你干活"。它们需要与用户仓库交互、产生副作用，因此设计上更强调纪律。

mem0-integrate：用 TDD 管道把 Mem0 接入现有仓库

mem0-integrate 的目标产出是"维护者无可争议就能合入的 PR"，因此把**非侵入（non-invasiveness）**作为七条不可协商原则的核心。其关键约束包括：

1. 只做加法、不替换：仓库已有记忆系统时，Mem0 与它并存，绝不取而代之；
2. 默认 opt-in：所有新代码必须以特性开关（如环境变量 MEM0_ENABLED=1、配置键或策略选择器）门控，开关未设置时行为与原来逐字节一致；
3. 零破坏：不删除导出、不改公开函数签名、不改既有测试；
4. 最小依赖面：只新增 mem0ai 及其委托 Skill 所需依赖；
5. 提交可拆分：代码、测试、配置/文档分别提交，便于 cherry-pick；
6. 零假设胜出（null hypothesis wins）：若找不到加法式、可门控的接入点，以退出码 1 收尾并给出理由——坏的 PR 不如没有 PR；
7. 只在后端接入：API Key、记忆作用域、用户身份解析在前端不安全。

该 Skill 的流水线共 10 步，完整机制与文档模板放在 skills/mem0-integrate/references/pipeline.md 中，SKILL.md 只保留每步一行的路由概览。10 步依次为：语言检测 → 仓库理解（产出 repo-summary.md 并需用户确认）→ 产品选择（Platform vs OSS，带推荐、不空白询问）→ API Key 检查 → 目标文档 goal.md（硬门禁，需显式批准，拒绝 3 次退出码 3）→ 集成计划 plan.md（硬门禁，退出码 5）→ 先写失败测试 → 新上下文子代理实现（提示词见 skills/mem0-integrate/references/subagent-prompts.md，3 轮评审不收敛退出码 4）→ 提交并移交 → 自愈循环。

它在写任何代码前还会先判断目标技术栈是否已被某个已发布 Skill 覆盖，若有则委托（delegate）而不重新实现：检测到 @ai-sdk/* + ai 就委托给 mem0-vercel-ai-sdk；纯 CLI 项目委托给 mem0-cli；MCP 客户端 / 编辑器配置则走仓库中的 integrations/mem0-plugin/。

mem0-test-integration：验证集成而非修复集成

mem0-test-integration 与上者松耦合（loose coupling）：二者仅通过 .mem0-integration/ 目录下的文件共享状态，绝不通过对话上下文传递信息。验证器在当前分支运行安装依赖、跑完整原生测试套件，再做一次真实 API 的端到端冒烟，最终产出评分卡。

其测试分两遍执行，与非侵入契约严格对应：

• Pass A —— 特性开关关闭：所有既有测试必须全绿，任何失败都是硬失败（非侵入违规，退出码 7），自愈循环被明确禁止触碰；
• Pass B —— 特性开关打开：全量测试（含新增 test_mem0_*）须通过。

冒烟测试始终使用 mem0-test-integration- 前缀的一次性随机 user_id，测试结束执行 delete_all 清理，确保绝不污染真实数据。E2E 阶段则按 plan.md 中的 E2E recipe: 启动应用、触发一次写入、再触发一次读取，用 read_assert（支持子串、regex=、jsonpath=）判定"用户早前说过的话是否真的会在新会话里回来"。该 Skill 自陈局限：它只捕获编译与运行期 bug，不判断"存进去的数据是否正是用户想要的、检索时机与 user_id 作用域是否正确"——逻辑正确性仍需人工评审。

mem0-oss-to-platform：OSS 到托管 Platform 的迁移流水线

mem0-oss-to-platform 面向"已在用 OSS/自托管 Memory 类、想换到托管 MemoryClient"的迁移场景。其核心心智模型（mental model）认为：OSS 意味着开发者自己运行整套记忆栈——向量库（Qdrant/pgvector/Chroma/…）、embedder、做事实抽取的 LLM、本地历史库，全部在传给 Memory 的 config 里接线；而 Platform 意味着 mem0 替你运行这套栈，你只持有 API Key。因此迁移本质上是减法：

1. Memory / Memory.from_config({...}) → MemoryClient()（从环境变量读 API Key）；
2. 删除本地的 vector_store / llm / embedder / graph_store / history_db_path 配置；
3. 逐个把调用点修正为托管调用约定（实体 ID 进 filters、分页等）；
4. 把一切"并非干净 1:1 对应"的地方标记出来交人类决策。

整个流程分 Phase 0～5：先做前置检查与足迹发现（用 Grep/Glob 扫描所有 import、配置块、调用点、依赖与 env，逐一记录 file:line），再用 inspect.signature 或读取安装包源码核对真实签名（不凭记忆猜版本差异），随后对照 skills/mem0-oss-to-platform/references/api-mapping.md 与 skills/mem0-oss-to-platform/references/gotchas.md 标记缺口，按 skills/mem0-oss-to-platform/references/plan-template.md 把计划写入仓库根目录的 MEM0_MIGRATION_PLAN.md 并停下来等待批准，获批后才逐文件执行并做验证。

如何选择正确的 Skill

原文档给出的决策指南可以浓缩为一张速查表：

• 在新项目或现有项目里编写 Mem0 代码？ → 使用 mem0
• 使用终端 CLI？ → 使用 mem0-cli
• 使用 @ai-sdk/* 构建？ → 使用 mem0-vercel-ai-sdk
• 想让助手替你把 Mem0 接进现有仓库？ → 依次使用 mem0-integrate、mem0-test-integration
• 已在用 Mem0 OSS、想迁移到托管 Platform？ → 使用 mem0-oss-to-platform

这套选择逻辑在六个 SKILL.md 的 frontmatter DO NOT TRIGGER 条件里也有镜像约束（例如 mem0 的 DO NOT TRIGGER 明确指向 CLI 与 Vercel 两个兄弟 Skill），保证多个 Skill 同时安装时也能正确路由、互不越界。

目录结构与发布约定（以仓库源码为准）

skills/AGENTS.md 给出了所有 Skill 统一的文件布局模板：

skills/<name>/
├── SKILL.md          # 入口文件，Skill 触发时始终整文件加载
├── README.md         # 面向人类，GitHub 渲染用
├── LICENSE           # Apache-2.0
├── references/       # 按需加载，一个主题一个文件
├── client/           # 可选，按运行时的调用模式
└── scripts/          # 可选，可执行脚本

其中最关键的一条工程约束是体积预算：SKILL.md 每次触发都会被完整加载，因此是最昂贵的文件，必须控制在 500 行以内；其余内容一律下沉到 references/，由 Agent 需要时才读取。frontmatter 中除了 name、description（含 TRIGGER / DO NOT TRIGGER 条件）与 license，还通过 metadata.mem0_tested_versions 钉住经过测试的 SDK 版本区间（例如 Python SDK >=2.0.0,<3.0.0、npm SDK >=3.0.0,<4.0.0），一旦 SDK 大版本升级就必须同步 bump——钉住一个已不存在的版本形态、生成的代码在运行期失败，比一个拒绝触发的 Skill 更糟。发布约定还包括：按 raw URL 引用规范来源（如 docs.mem0.ai/llms.txt、openapi.json），Skill 不得依赖模型对 Mem0 API 的"环境记忆"；Skill 之间的领地重叠通过 raw URL 委托而非转述；流水线型 Skill 必须用退出码表声明并兑现退出码；文件间交叉引用一律使用相对路径，以便 Skill 被 vendored 进其他仓库时依然可用。

小结

Mem0 的 Skills 体系用一个统一目录（skills/）同时解决了两种开发诉求：参考型 Skill（mem0、mem0-cli、mem0-vercel-ai-sdk）把经过验证的 SDK 知识常驻在助手上下文里，让日常代码生成"一次写对"；流水线型 Skill（mem0-integrate + mem0-test-integration 结对、mem0-oss-to-platform）则把"接入、验证、迁移"这类高风险端到端任务变成有门禁、有产物、有退出码的可复现流水线。若想深入理解其背后实现的记忆语义与调用契约，可继续查阅仓库内的 Python 客户端实现 mem0/client/main.py、TypeScript SDK mem0-ts/src/client/ 以及 CLI 双实现共用的 cli/cli-spec.json。所有 Skill 均以 Apache-2.0 许可发布。