mem0-integrate

mem0-integrate

通过以目标为导向、测试优先的流程，将 Mem0 接入现有代码库。 与 mem0-test-integration 配合使用以进行验证。

规范资料来源（作出任何决定前先获取）

在第 3 步之前，技能 MUST 使用 WebFetch 获取这些 URL，并在 plan.md 中引用它们。这些是权威资料来源——不要依赖已有的 Mem0 API 知识。

面向 Agent 的文档

• 带范围标签的文档索引：https://docs.mem0.ai/llms.txt
• 完整文档（单文件，深入介绍）：https://docs.mem0.ai/llms-full.txt
• OpenAPI 规范（Platform REST，可供机器读取）：https://docs.mem0.ai/openapi.json
• 托管的 MCP 服务：https://mcp.mem0.ai/mcp（需要 Platform API 密钥）
• 集成索引：https://docs.mem0.ai/integrations

已发布的 Mem0 技能——委托使用；不要重新实现

优先使用这些技能，而不是自行编写调用模式。每项技能都是独立的 SKILL.md，包含触发条件、示例和固定版本的代码。

• SDK（Python + TS、Platform + OSS）：https://raw.githubusercontent.com/mem0ai/mem0/main/skills/mem0/SKILL.md
• CLI：https://raw.githubusercontent.com/mem0ai/mem0/main/skills/mem0-cli/SKILL.md
• Vercel AI SDK：https://raw.githubusercontent.com/mem0ai/mem0/main/skills/mem0-vercel-ai-sdk/SKILL.md
• 可移植的编辑器/MCP 插件：https://github.com/mem0ai/mem0/tree/main/integrations/mem0-agent-plugin

SDK 源码（文档表述不明确时阅读）

公开代码库。如果 main 分支的版本已超出此技能前置元数据中 mem0_tested_versions 指定的范围，请对照该范围进行核验。

• 仓库根目录：https://github.com/mem0ai/mem0
• Python SDK：https://github.com/mem0ai/mem0/tree/main/mem0
• TypeScript SDK：https://github.com/mem0ai/mem0/tree/main/mem0-ts

快速入门（用于引导不熟悉的技术栈）

• Platform：https://docs.mem0.ai/platform/quickstart
• OSS Python：https://docs.mem0.ai/open-source/python-quickstart
• OSS Node：https://docs.mem0.ai/open-source/node-quickstart
• Platform 与 OSS 对比：https://docs.mem0.ai/platform/platform-vs-oss

集成原则（不可妥协）

这项技能的真正目标是产出一份维护者无需争论即可接受的 PR。因此，任何侵入式改动都不在考虑范围内。

1. 只做增量，不做替换。 如果目标仓库已有记忆系统、会话存储、用户上下文层，或任何名为 Memory / memory_* 的内容，Mem0 都应与其并存，而不是取而代之。现有系统保持原样运行。
2. 默认选择加入。 使用功能标志（例如 MEM0_ENABLED=1 这样的环境变量、配置项或策略选择器）控制所有新增的 Mem0 代码。未设置标志时，行为必须与仓库原有行为逐字节一致。
3. 不得造成破坏。 不删除导出项、不重命名公共函数、不更改方法签名、不修改现有测试，也不改变现有测试的行为。所有预先存在的测试都必须在标志开启和关闭时原样通过。
4. 尽量缩小依赖范围。 只添加 mem0ai（以及委派技能所需的任何依赖），不添加其他内容。不引入新的向量存储、图数据库，也不添加仓库当前未使用的提供方 SDK。
5. 提交可独立拆分。 代码、测试和配置/文档分别提交，以便评审者可以挑选提交。
6. 以零假设为准。 如果第 6 步（计划）后仍找不到可增量添加且受门控的集成方式，则以代码 1 退出并说明理由。糟糕的 PR 比没有 PR 更糟。
7. 仅限后端。 Mem0 集成必须位于服务端代码中。API 密钥、记忆范围和用户身份解析在客户端都不安全。如果仓库同时有后端和前端，调用位置必须在后端文件中。仅有前端的仓库将在前置条件检查时被拒绝。

通过四个关卡强制执行：前置条件（拒绝仅有前端的仓库，以及无法增量集成的仓库）、第 2 步理解阶段（确认存在后端并指出候选接入位置）、第 6 步计划审查（拒绝会修改现有导出项或指定客户端调用位置的计划），以及第 10 步自修复循环（拒绝“修复”违反原则的内容，而是将其指出）。

技能委派规则

编写任何代码之前，先检查是否已有已发布的技能覆盖目标技术栈。如果有，则委派该技能——将其调用位置模式复制到 plan.md 和测试中；不要改述。

在目标仓库中检测到	委派给	原因
package.json 中有 @ai-sdk/* 和 ai	skills/mem0-vercel-ai-sdk	集成方式是通过 createMem0 提供方包装器，而不是直接使用 MemoryClient。
仅有 CLI 的仓库（Typer、Commander、Click、Cobra），没有 LLM 调用位置	skills/mem0-cli	调用位置是命令处理程序，而不是模型包装器。请先考虑 mem0 是否适用。
目标是 MCP 客户端 / 编辑器配置（Claude Code、Cursor、Codex settings）	integrations/mem0-agent-plugin	本地 stdio MCP 服务（含一个搜索工具）加技能，不包含钩子或自动采集；如需托管端点，请使用 https://mcp.mem0.ai/mcp。通常不需要 SDK 代码。
其他任何带有 LLM 调用位置的 Python 或 TS 仓库	skills/mem0	默认 SDK 集成路径。

在 plan.md 的 “Delegated skill:” 字段下记录被委派技能的原始 URL。第 7 步的测试编写者和第 8 步的实现子 Agent 都会读取此字段。

前置条件

除非以下条件全部满足，否则拒绝启动：

• 当前工作目录位于 Git 仓库内，且索引干净 （没有未提交的更改）。这可以保护用户的工作——每项编辑都会提交到 功能分支，而不会叠加在进行中的更改之上。
• 仓库具有可检测的语言（package.json / pyproject.toml / requirements.txt）。如果没有语言信息，则干净退出并说明理由。
• 仓库具有后端。通过以下方式检测：存在 backend/、server/ 或 api/ 目录；使用 FastAPI/Flask/Django/Starlette 的 Python 包；使用 Express/ Fastify/Koa/NestJS/Next-API-routes 的 Node 包；或 Agent 循环框架 （LangGraph、LangChain、LlamaIndex、Agno）。仅前端仓库 （纯 React/Vue/Svelte SPA、静态站点、仅移动端）→ 以代码 1 退出并说明理由。Mem0 不会安装在客户端。
• 用户已决定 Mem0 适合此仓库。此技能不会调查代码库来论证适用性——请带着明确目标来。第 2 步 确实会读取仓库，以了解其功能并定位后端集成点；这是操作流程，而非适用性论证。

如果任何前置条件不满足，则退出并说明理由。不要试图 “无论如何都让它运行”。

流程

共十个步骤。完整操作流程、文档模板和关卡规则见 references/pipeline.md。开始执行某个步骤时，请阅读该文件；以下摘要仅用于指引。

#	步骤	关卡
1	语言检测。 package.json / pyproject.toml / requirements.txt。对于 Monorepo，询问要使用哪个子目录。
2	理解仓库。 按预算读取 README、贡献者文档、入口点和最顶层两级目录。生成 repo-summary.md，列出按优先级排序的后端集成点。	用户确认摘要并选择一个集成点。没有后端集成点则以代码 1 退出。
3	产品选择。 Platform 或 OSS，根据依赖信号推荐，绝不留空让用户选择。	写入 goal.md 并锁定，不再重新决定。
4	API 密钥检查。 MEM0_API_KEY（Platform）或 OPENAI_API_KEY（OSS）。Platform 缺少密钥时，默认切换到 Agent Mode，运行 mem0 init --agent。	CI 模式下缺少密钥则以代码 2 退出。
5	目标文档。 goal.md：存储什么、何时检索、原因、产品、委托的技能、不在范围内的内容。	硬性关卡。 必须获得明确批准。拒绝 3 次后，以代码 3 退出。
6	集成计划。 对调用点和身份来源进行范围限定的 grep。plan.md：写入/读取模式、作用域、调用点、依赖项、保留的行为、共存方式、功能标志、来源、E2E 测试方案。	硬性关卡。 没有合理的增量调用点或被拒绝 3 次后，以代码 5 退出。
7	先写测试。 使用仓库原生测试框架编写失败的写入和读取测试，断言形式取自规范签名。即使未设置 MEM0_API_KEY，测试也必须可导入。	测试必须失败。如果通过了，说明测试有误。
8	实现。 使用全新上下文的子 Agent，提示词见 references/subagent-prompts.md，返回的差异需根据 plan.md 和 goal.md 进行审查。	经过 3 轮审查后，以代码 4 退出。
9	提交并交接。 分支 mem0-integrate/<slug>，拆分为四个独立提交：依赖项、模块、接线、测试。	--no-heal 会在此处停止。
10	自动修复循环。 运行 /mem0-test-integration --ci，对故障分类，启动范围受限的修复子 Agent，并在出现回归时还原更改。	遇到预先存在的测试故障时，停止，以代码 6 退出。绝不要尝试“修复”它。

文件（均位于 .mem0-integration/ 下）

文件	用途	保留策略
repo-summary.md	仓库理解和候选后端接口（步骤 2）。	跨运行保留。
goal.md	已批准的意图。步骤 6 后绝不重写。	跨运行保留。
plan.md	已批准的实现机制（位置、方式、调用点、保留的行为）。	跨运行保留。
trace.jsonl	本次运行中的每次工具调用、决策和子 Agent 往来记录。	每次运行覆盖。
diff.patch	已提交集成内容，作为便于审查的补丁。	每次运行覆盖。
heal-trace.md	自愈循环每次尝试的记录（步骤 10）。	每次运行覆盖。
product.json	{"product": "platform"|"oss", "language": "...", "mem0_version": "...", "write_site": "file:line", "read_site": "file:line", "feature_flag": "MEM0_ENABLED", "preferred_site": "<surface index from step 2>"}，由验证技能使用。	每次运行覆盖。

首次运行时，会将 .mem0-integration/ 添加到 .gitignore。不会在此目录和仓库源代码树之外写入任何内容。

模式

模式	触发条件	行为
交互模式（默认）	存在 TTY，且未设置 MEM0_INTEGRATE_CI	询问密钥、确认目标文档并展示建议。
CI 模式	MEM0_INTEGRATE_CI=1	要求在环境变量中提供密钥，要求使用 --product；若存在 goal.md，则自动批准其中的目标文档，否则快速失败。

调用方式

/mem0-integrate                            # 交互模式，启用自愈
/mem0-integrate --no-heal                  # 提交后停止；手动验证
/mem0-integrate --heal-max 5               # 限制每个类别的自愈尝试次数（默认 3）
/mem0-integrate --product platform         # 跳过产品选择询问
/mem0-integrate --product oss
/mem0-integrate --ci                       # 非交互模式（用于测试框架）

退出代码

代码	含义
0	成功。功能分支已提交；验证技能已准备就绪。
1	前置条件不满足（仓库有未提交更改、无法检测语言等）。
2	CI 模式下缺少环境变量密钥。
3	目标文档被拒绝 3 次或以上——集成需求定义不明确。
4	子 Agent 审查循环经过 3 轮仍未收敛。
5	集成计划被拒绝 3 次或以上，或未找到合理的增量式调用点。
6	自愈循环未能收敛、检测到非侵入性违规，或已有测试失败。

明确不在范围内

• 调查仓库以寻找适配点。由人类在调用此技能前决定 Mem0 是否有帮助，以及适用位置。
• 替换任何现有的记忆／会话／状态系统。始终采用增量方式并使用功能标志；参见“集成原则”。
• 修改已有测试，即使是为了在自愈过程中“修复”它们。若取消设置功能标志后，集成完成的代码仍导致测试失败，则属于非侵入性违规，而不是需要修补的缺陷。
• 默默决定使用 Platform 还是 OSS。始终询问并给出建议。
• 切换分支、推送或创建 PR。只在本地提交后停止（或进入自愈循环，仍仅限本地）。
• 在存储之间迁移数据。若用户提出此类需求，请指引其查看 migration/oss-to-platform 文档。
• 为 OSS 选择默认 LLM 以外的提供方。如果需要自定义 LLM／嵌入器／向量存储，请指引其查看 components/* 文档，并使用新密钥重新运行步骤 4。