mem0-oss-to-platform

将 mem0 OSS 迁移到 mem0 Platform（托管版）

此技能将项目的记忆层从自托管的 mem0 OSS SDK迁移到托管的 mem0 Platform SDK，适用于任何项目形态——Agent、RAG 流水线、API 服务、聊天机器人或后台工作进程。你需要找出 mem0 的实际使用位置，编写一份供开发者审核的计划，然后在获得批准后执行。

心智模型（请先阅读——这决定了迁移的方式）

OSS mem0 意味着开发者自行运行整套记忆技术栈：向量存储（Qdrant/pgvector/Chroma/…）、嵌入模型、用于事实提取的大模型，以及本地历史记录数据库。所有这些都通过配置对象接入 Memory。

Platform 则意味着由 mem0 为开发者运行这套技术栈。开发者只需持有一个 API key。因此，迁移主要是删减：本地基础设施配置收拢为单个 MemoryClient(api_key=...)。方法调用仍然熟悉（add/search/get_all/…），但部分参数约定会更严格，返回值也会是服务端响应。

因此，每次迁移的核心步骤都是：

1. 将 Memory / Memory.from_config({...}) 替换为 MemoryClient()（从环境变量读取 API key）。
2. 删除本地 vector_store / llm / embedder / reranker / history_db_path 配置（以及任何残留的 graph_store）。
3. 将每个调用位置调整为托管版调用约定（实体 ID 放入 filters、分页等）。
4. 标记所有无法直接一对一迁移的内容，以便开发者决定如何处理（参见 references/gotchas.md）。

**范围纪律：**仅修改与 mem0 相关的代码、配置、依赖项和环境变量。保留项目现有的行为、结构和风格。不要重命名内容、不要“整理”附近的代码，也不要更改应用逻辑。开发者要求的是替换后端，而不是重构项目。

工作流

按顺序完成以下阶段。阶段 1–4 用于制定计划；只有获得批准后才执行阶段 5。

阶段 0 — 前置条件检查

托管版 SDK 需要 mem0 API key（MEM0_API_KEY，可在 https://app.mem0.ai 获取）。确认开发者已拥有该密钥。编写计划时不需要密钥值，但要在计划中说明：执行和验证前必须设置该密钥（放入 .env / 密钥管理器，绝不要硬编码）。

阶段 1 — 查找 mem0 的使用范围

不要假设项目布局。找出 mem0 出现的所有位置。先检测语言和已安装的版本，再全面搜索用法。具体来说，搜索以下内容：

• 导入 / 实例化： from mem0 import Memory、AsyncMemory、Memory.from_config、Memory(、import ... from "mem0ai"、from "mem0ai/oss"、new Memory(。
• 配置块： vector_store/vectorStore、embedder、llm、reranker、graph_store/graphStore、history_db_path/historyDbPath、historyStore、custom_instructions/customInstructions、custom_fact_extraction_prompt/customPrompt、custom_update_memory_prompt、enable_graph 等键。
• 每个调用位置： .add(、.search(、.get_all(/.getAll(、.delete_all(/.deleteAll(、.get(、.update(、.delete(、.reset(、.history(。
• 依赖项和环境变量： 检查 requirements.txt/pyproject.toml/package.json 中的 mem0ai 以及仅供 mem0 使用的本地基础设施依赖项（例如 qdrant-client、chromadb）；检查 .env/配置中的 OPENAI_API_KEY 等本地嵌入模型/大模型所用变量；检查仅用于支持 mem0 的 docker-compose 服务（例如 Qdrant 容器）。

广泛使用 Grep/Glob；漏掉任何一个调用位置都可能导致运行时故障。记录每项发现的 file:line；计划清单将据此编制。

阶段 2 — 对照已安装的 SDK 验证 API（不要猜测）

版本会变化，OSS 和托管类的签名也有细微差异。在进行映射前，请确认已安装软件包的真实签名，不要依赖记忆：

• Python： 对每个要调用的方法运行 python -c "import inspect; from mem0 import MemoryClient; print(inspect.signature(MemoryClient.search))"，并在有任何不明确之处（例如某个方法是否拒绝顶层实体参数）时，阅读 site-packages/mem0/client/main.py 下已安装的源码。还要检查项目当前使用的 OSS 版本。
• TypeScript： 阅读 node_modules/mem0ai/ 下已安装的类型定义和 dist，确认选项名称（limit 还是 topK，userId 还是嵌套的 filters: { user_id }），以及默认导出与 mem0ai/oss 导出。

这一步验证是最重要的习惯——它能确保计划在不同 mem0 版本中始终正确。然后查阅 references/api-mapping.md，了解每个方法从 OSS 到托管版的转换方式（Python 和 TypeScript）。文档指南位于 https://docs.mem0.ai/migration/oss-to-platform（请根据已安装的 SDK 验证其中的代码示例）；OSS 升级变更见 https://docs.mem0.ai/migration/oss-v2-to-v3。

阶段 3 — 映射每个调用点并标记差异

对于阶段 1 中的每个调用点和配置块，使用映射确定对应的托管版实现。大多数调用都能顺利映射。有些则不行——这些情况比机械式编辑更重要。 阅读 references/gotchas.md，并标记所有需要人工决策的事项：可自托管/数据驻留设置、本地模型选择改为在服务端运行、图记忆用法、自定义提示词、现在会产生网络往返的热路径调用，以及现有本地存储的记忆不会自动迁移（除非开发者提出要求，否则数据迁移不在范围内：请注明，不要擅自尝试；如果开发者提出要求，请参阅 references/gotchas.md #1，其中介绍了托管 Qdrant 迁移脚本）。

阶段 4 — 编写计划并停止

按照 references/plan-template.md 中的结构，在仓库根目录的 MEM0_MIGRATION_PLAN.md 中编写完整计划。计划必须足够具体，能够据此执行，并如实说明差异。 然后停止并提交审核。 不要在同一轮中开始编辑代码——整个流程的目的就是让开发者先阅读并批准计划。

阶段 5 — 获批后执行（引导式）

开发者批准后（他们可能会先要求修改——请纳入这些修改），执行计划：

• 逐个文件进行编辑，严格限定在 mem0 范围内。
• 更新依赖项和环境配置（MEM0_API_KEY；仅当本地基础设施依赖/服务只供 mem0 使用且你确信可以移除时，才移除它们）。
• 验证，按照确认任何后端替换的方式进行：
  • 确认可以导入、通过类型检查并进行字节码编译。
  • 使用真实的 MEM0_API_KEY 对托管 API 进行冒烟测试，测试 add → search/get_all → delete_all，并确认应用自身的入口点仍可运行。托管版的 add 是异步的，因此在预期 search/get_all 中出现事实前，请稍等片刻。
  • 确认不再创建本地 OSS 存储（例如 ~/.mem0/history.db、本地 Qdrant 路径）。客户端本身仍会创建 ~/.mem0/config.json，因此不要仅凭 .mem0/ 目录判断。
• 报告变更内容、验证情况，以及开发者仍需处理的已标记问题（例如使用 project.update 重新应用自定义指令、迁移旧数据）。

参考文件

• references/api-mapping.md — Python 和 TypeScript 中精确的 OSS→托管版方法/参数/返回值映射，以及依赖项和环境变量变更。在阶段 2–3 阅读。
• references/gotchas.md — 不能直接一一对应、需要人工决策的事项。在阶段 3 阅读，确保计划中的“注意事项”部分完整。
• references/plan-template.md — MEM0_MIGRATION_PLAN.md 的确切结构。在阶段 4 使用。