Mem0 Plugin 集成指南：为 Claude Code、Cursor、Codex 等 AI 编码助手注入跨会话持久记忆

Mem0 Plugin 是 mem0 仓库中面向 AI 编码工作流的官方插件包，通过「远程 MCP Server + 生命周期 Hooks + Mem0 SDK Skill」三件套，让 Claude Code、Claude Cowork、Cursor、Codex、OpenCode 与 Antigravity 这六类客户端共享同一套持久化记忆基础设施：跨会话存储、语义检索、自动捕获与分类管理记忆。本文完整覆盖插件的 API 密钥配置、六大平台安装路径、17 个 /mem0: 技能命令、生命周期 Hook 的源码机制，以及编码场景定制分类（coding-tuned categories）的幂等实现原理，读完后你可以独立完成任意一个平台的接入、验证与排障。

插件架构总览：三大组件与清单文件

在动手安装之前，先理解插件的组件构成。插件根目录 integrations/mem0-plugin/ 下的核心清单文件定义了整个插件的能力边界：

• plugin.json —— 插件元数据清单，声明插件 ID 为 mem0、当前版本 0.1.7、Apache-2.0 许可证，并描述其为「跨会话、用户级语义记忆」，关键词包含 mcp、semantic-search；
• mcp_config.json —— 统一的 MCP 连接配置，指向远程服务 https://mcp.mem0.ai/mcp/，认证头为 Authorization: Token ${MEM0_API_KEY}。${MEM0_API_KEY} 在会话启动时从环境变量插值，而非安装时固化，这是后文「更新后只需重启即可重连」的根源；
• hooks.json —— Claude Code / Cowork / Antigravity 使用的生命周期 Hook 定义（详见后文源码剖析）；
• requirements.txt —— Python 侧唯一依赖是 mem0ai SDK，由 ensure_deps.sh Hook 在安装到插件数据目录的独立 venv 中自动完成；
• marketplace.json —— 仓库根目录的插件市场清单，声明 mem0-plugins 市场并将 ./integrations/mem0-plugin 注册为本地插件源，Codex 的「侧载」安装方式正是依赖它。

各平台能力矩阵（继承自 README）：

组件	Claude Code / Cowork	Cursor (MCP)	Codex (Sideload)	Codex (Direct MCP)	OpenCode (Full)	OpenCode (MCP)	Antigravity
MCP Server	Yes	Yes	Yes	Yes	Yes	Yes	Yes
Lifecycle Hooks	Yes	No	Opt-in	No	Yes	No	Yes
Mem0 SDK Skill	Yes	No	Yes	No	Yes	No	Yes

三大组件的职责边界：

• MCP Server —— 连接 Mem0 远程 MCP 服务（mcp.mem0.ai），提供 add/search/update/delete 记忆的远程工具，无本地依赖；
• Lifecycle Hooks —— 在会话关键节点自动捕获记忆。Claude Code、OpenCode、Antigravity 安装完整插件时原生接线；Codex 需要一次性安装器（scripts/install_codex_hooks.py）opt-in；
• Mem0 SDK Skill —— 指导 AI 将 Mem0 SDK（Python 与 TypeScript）集成到应用代码中，文档位于 integrations/mem0-plugin/skills/mem0/。

第 1 步：配置 API 密钥（先于安装，强制前置）

必须在本步骤完成后再安装插件。

人工流程：

1. 注册 mem0 平台账号（app.mem0.ai）；

2. 进入 Dashboard 的 API Keys 页面，点击 Create API Key 并复制密钥（以 m0- 开头）；

3. 用以下两种方式之一设置密钥：

   CLI —— 写入 shell profile：

   # For zsh (default on macOS)
   echo 'export MEM0_API_KEY="m0-your-api-key"' >> ~/.zshrc
   source ~/.zshrc
   
   # For bash
   echo 'export MEM0_API_KEY="m0-your-api-key"' >> ~/.bashrc
   source ~/.bashrc
   

   Desktop app（Cowork） —— 使用本地环境变量编辑器：点击提示框旁的环境下拉框 → 悬停 Local → 点击齿轮图标 → 添加 MEM0_API_KEY。值在本机加密存储。

   注意： Desktop 应用不会继承 shell profile 中的自定义环境变量——它只读取 PATH。Desktop 端必须使用本地环境编辑器。

4. 验证：

   echo $MEM0_API_KEY
   # Should print: m0-your-api-key
   

Agent 快速通道（无人值守场景）。 如果是一个 AI agent 在自主配置 Mem0（没有人工 dashboard 注册可用），文档给出了专门的入口：

mem0 init --agent --json

该命令在 5 秒内签发一个 evaluation API key——无邮箱、无 OTP、无浏览器。密钥写入配置并导出为当前 shell 的 MEM0_API_KEY，可立即用于 Mem0 平台或 MCP server。人类所有者之后可运行 mem0 init --email <their-email> 认领所有权：记忆随之转移，同一把 API key 继续有效，agent 不中断。

第 2 步：按平台安装插件

以下所有方式都要求先完成第 1 步的 MEM0_API_KEY 配置。

Claude Code (CLI) / Claude Cowork (Desktop)

两者共享同一插件系统。CLI 中执行：

/plugin marketplace add mem0ai/mem0
/plugin install mem0@mem0-plugins

Cowork 桌面端： 打开 Cowork 标签页 → 侧栏点击 Customize → Browse plugins → 安装 Mem0。

此方式安装的是完整插件：MCP server、生命周期 hooks（自动记忆捕获）与 Mem0 SDK skill 全部就位。

Codex

Option A — Direct MCP（最快，仅 MCP）：

Codex 从 ~/.codex/config.toml 以 TOML 格式读取 MCP server，添加：

[mcp_servers.mem0]
url = "https://mcp.mem0.ai/mcp"
bearer_token_env_var = "MEM0_API_KEY"

在 shell 中导出 MEM0_API_KEY 后重启 Codex。由于 codex mcp add 只支持 stdio 服务器，Mem0 这类 HTTP server 必须直接写 config.toml（或通过 Codex 应用内 Plugins → Connect to a custom MCP → Streamable HTTP UI 完成）。

Option B — 侧载完整插件（完整体验：MCP + skills + opt-in hooks）：

克隆 mem0 仓库并注册随仓库捆绑的 marketplace：

git clone https://gitcode.com/GitHub_Trending/em/embedchain ~/codex-plugins/mem0-source
codex plugin marketplace add ~/codex-plugins/mem0-source

这会让 Codex 指向仓库的 marketplace.json，其中引用 integrations/mem0-plugin/ 作为本地插件源。重启 Codex、运行 /plugins，从 Mem0 Plugins 市场安装 Mem0 即可。

不要与 Option A 叠加。 插件 manifest 会通过 integrations/mem0-plugin/.codex-mcp.json 自动注册 mem0 为 MCP server——再手动添加 [mcp_servers.mem0] 会导致重复注册。

可选：启用生命周期 Hooks。 Codex 不会从插件 manifest 自动接线 hooks，只读取 ~/.codex/hooks.json（或 <repo>/.codex/hooks.json）。运行一次捆绑安装器完成合并：

python3 ~/codex-plugins/mem0-source/integrations/mem0-plugin/scripts/install_codex_hooks.py

它会把 6 类事件处理器合并进 ~/.codex/hooks.json，使用指向克隆目录的绝对路径：

事件	职责
SessionStart	加载既有记忆作为 bootstrap 上下文
UserPromptSubmit	向提示词注入相关记忆
PreToolUse（3 个处理器）	阻止 MEMORY.md 写入；强制 mem0 工具调用携带 user_id/app_id；扫描被读文件的相关记忆上下文
PostToolUse（2 个处理器）	跟踪统计；扫描 bash 错误以关联相关记忆
Stop	在回合结束时提醒 agent 持久化所学
PreCompact	在上下文被压缩前存储摘要

重复运行安装器是幂等的（替换而非追加 Mem0 条目），并保留你的其他 hooks。卸载：python3 .../install_codex_hooks.py --uninstall。若移动或删除了克隆目录，需从新位置重新运行——hooks 文件里存的是绝对路径。

Codex hooks 还要求 ~/.codex/config.toml 中的功能开关：

[features]
codex_hooks = true

安装器在开关未设置时会打印提醒。修改配置后重启 Codex。

插件管理命令：

codex plugin marketplace upgrade               # 拉取最新插件版本
codex plugin marketplace remove mem0-plugins   # 注销 marketplace

Cursor

若你的 Cursor MCP 设置里已有 mem0 条目，安装前先删除，避免工具重复。

Option A — 一键 deeplink（仅安装 MCP server）：README 提供了一个 cursor:// 深链，点击即在 Cursor 中写入含 Authorization: Token ${env:MEM0_API_KEY} 头的 MCP 配置。

Option B — 手动配置（仅 MCP server）：在 .cursor/mcp.json 中添加：

{
  "mcpServers": {
    "mem0": {
      "url": "https://mcp.mem0.ai/mcp/",
      "headers": {
        "Authorization": "Token ${env:MEM0_API_KEY}"
      }
    }
  }
}

OpenCode

opencode plugin @mem0/opencode-plugin

加 --global 可对全部项目生效。插件通过其 config hook 自动注册原生记忆工具、hooks 与 skills——无需配置 MCP server。安装后重启 OpenCode。

Antigravity (Google)

Option A — degit（推荐）：

# Install the plugin (MCP server, hooks, scripts)
npx degit mem0ai/mem0/integrations/mem0-plugin ~/.gemini/config/plugins/mem0

一次性安装 MCP server、生命周期 hooks 与共享脚本。插件元数据由 plugin.json 描述（contextFileName 指向 AGENTS.md）。

安装后：运行 /mem0:onboard 并验证

安装后开启新会话并运行：

/mem0:onboard

该向导完成四件事：

1. 校验 API key 与 MCP 连接；
2. 检测并导入项目文件（CLAUDE.md、AGENTS.md、.cursorrules）；
3. 安装编码优化的记忆分类（见后文）；
4. 展示你的身份标识（user ID、project 作用域、branch）。

Onboarding 是幂等的，随时可重跑；在新项目的第一个会话（0 条记忆）中，Claude 会被提示自动运行它。

连通性验证三步：

1. /mem0:health —— 检查连接性；
2. /mem0:stats —— 查看记忆计数；
3. /mem0:remember "we use TypeScript" 存储一条记忆，再用 /mem0:tour 确认已入库。

会话启动 Hook 在 MEM0_API_KEY 缺失时会向会话注入明确的 Setup Required 横幅（可参考 on_session_start.sh 中输出的身份三元组 user | project | branch | auth），因此任何连接问题在会话第一行就会暴露。

可用技能：17 个 /mem0: 命令

插件包含 17 个 skills（技能目录位于 integrations/mem0-plugin/skills/，每个技能一个 SKILL.md），其中通过 /mem0: 命令直接暴露的核心集合如下：

命令	说明
/mem0:remember	原文存储记忆——决策、偏好、约定
/mem0:tour	按分类浏览全部记忆
/mem0:peek	快速搜索，紧凑单行结果
/mem0:stats	会话与项目记忆统计
/mem0:dream	记忆整合——合并重复、消解矛盾
/mem0:pin	保护关键记忆免于修剪
/mem0:forget	按搜索或 ID 删除记忆
/mem0:health	诊断连接、API key 与读写能力
/mem0:export	导出记忆为可移植 Markdown
/mem0:import	从导出文件或 MEMORY.md 导入记忆
/mem0:list-projects	列出所有存有记忆的项目
/mem0:switch-project	覆盖自动检测的项目作用域
/mem0:memory-reviewer	审计记忆质量——重复、矛盾、过期
/mem0:context-loader	为当前任务预加载相关记忆

生命周期 Hooks 源码剖析

以 hooks.json 为例看完整插件的 Hook 接线方式。每个 Hook 命令都以 ${extensionPath} 定位脚本，并统一附带 || true（或短超时）确保 Hook 失败不阻塞会话：

• SessionStart（matcher *）：先跑 ensure_deps.sh（60s 超时，确保 venv 与 mem0ai SDK 就绪），再跑 on_session_start.sh 加载既有记忆为 bootstrap 上下文；
• UserPromptSubmit：on_user_prompt.sh，8s 超时，注入相关记忆；
• PreToolUse 三组匹配器：
  • Write|Edit|MultiEdit → block_memory_write.sh（阻止 agent 绕过 mem0 直接写 MEMORY.md）；
  • mcp__mem0__.*|mcp__plugin_mem0_mem0__.* → enforce_metadata_defaults.sh（3s 超时，强制 mem0 工具调用携带 user_id/app_id）；
  • Read → on_file_read.sh（5s 超时，为读取的文件附带相关记忆上下文）；
• Stop：on_stop.sh（30s 超时），会话结束时捕获会话摘要；
• PostToolUse 两组：mem0 MCP 调用后统计跟踪（on_post_tool_use.sh）、Bash 输出错误扫描（on_bash_output.sh，5s 超时）。

Codex 版本模板 hooks/codex-hooks.json 在此基础上多出 PreCompact 事件（on_pre_compact.sh，压缩前落盘摘要），且每条命令前缀 MEM0_PLATFORM=codex 以便脚本按平台分支行为。

安装器 install_codex_hooks.py 的实现要点值得细看：

1. 模板占位符重写：load_template() 将 codex-hooks.json 中的 ${PLUGIN_ROOT} 替换为插件绝对安装路径（L46-L49）；
2. 所有权识别：以命令字符串中的目录名 mem0-plugin 作为 owner marker 判定条目归属（L41-L66），因此跨安装路径升级也不会残留重复；
3. 幂等合并：strip_owned_entries 先移除旧 Mem0 条目，再 merge_template 追加新条目，其他用户 hooks 原样保留（L69-L83）；
4. 开关自检：逐行解析 config.toml（去注释后精确匹配 codex_hooks=true），未开启则打印功能开关提示（L91-L110）；
5. Windows 防护：原生 Windows 下 .sh 无默认解释器会触发 Open With 对话框，安装器直接拒绝并提示改用 WSL/Git Bash 或仅走 MCP 通道（L130-L140）。

Coding-tuned Categories：编码场景分类体系的幂等实现

mem0 会为每条记忆自动打上一个或多个 categories 标签。默认分类是消费场景取向的（food、hobbies、music……），对代码工作几乎没有意义。插件在会话启动时后台自动安装编码取向的分类法——无弹窗、无手动步骤。新记忆随后自动对照 17 个开发类类别打标：architecture_decisions、anti_patterns、task_learnings、tooling_setup、bug_fixes、coding_conventions、user_preferences、dependency_decisions、performance_findings、security_constraints、testing_patterns、data_model、api_contracts、deployment_runbook、team_norms、domain_glossary、experiment_results。

这 17 个类别的完整定义（含每个类别的语义描述）在 setup_coding_categories.py 的 CODING_CATEGORIES 常量中，例如 bug_fixes 要求记忆包含「根因分析 + 所施加的修复 + 诊断路径，以便日后识别类似问题」。

手动预览或强制刷新：

# Dry-run -- prints current vs proposed, no changes:
python integrations/mem0-plugin/scripts/setup_coding_categories.py

# Write explicitly:
python integrations/mem0-plugin/scripts/setup_coding_categories.py --apply

前提：mem0ai Python SDK（pip install mem0ai）与已设置的 MEM0_API_KEY。注意 project.update(custom_categories=[...]) 总是整体替换列表，而非增量合并。

后台自动执行由 auto_setup_categories.py 承担，挂在 SessionStart（startup）Hook 上，其工程设计值得借鉴：

• 状态门控：状态文件 ~/.mem0/categories_setup.json 记录「API key 指纹 → 分类法指纹」映射（L60-L121）。由于分类作用域是 API key 对应的 mem0 project（而非本地仓库），每个账号只需执行一次；分类法本身变更（指纹变化）时才会重新应用。API key 只存 SHA-256 前 16 位指纹，不落盘明文；
• 并发锁：O_CREAT | O_EXCL 文件锁防止并发会话竞争，超过 120 秒的陈旧锁自动清理（L158-L175）；
• 永不阻塞会话：任何异常仅写 stderr 日志并 exit 0；SDK 未就绪（venv 安装中）时静默跳过，留待下个会话重试（L200-L235）；
• 复用 SDK 路径：先 project.get(fields=["custom_categories"]) 比对，_categories_match 判定一致则返回 already-configured 跳过写入，否则 project.update(custom_categories=...) 全量替换（L134-L152）。

MCP Tools：安装后可用的远程工具

工具	说明
add_memory	为某 user/agent 保存文本或对话历史
search_memories	跨记忆语义搜索，支持过滤器
get_memories	带过滤与分页的记忆列表
get_memory	按 ID 取回单条记忆
update_memory	按 ID 覆写记忆文本
delete_memory	按 ID 删除单条记忆
delete_all_memories	批量删除作用域内全部记忆
delete_entities	删除 user/agent/app/run 实体及其记忆
list_entities	列出 Mem0 中存储的 users/agents/apps/runs

更新插件与故障排查

当插件更新（从市场拉取新版本或全新本地安装）后，旧会话中的 MCP server 连接会持有一个过期句柄并停止响应——必须重启客户端重连：

• Claude Code： 提示符中运行 /restart，或关闭重开 CLI；
• Cursor： 退出并重开；
• Codex： 重启编辑器会话；
• OpenCode / Antigravity： 重启会话。

MEM0_API_KEY 无需重新输入——认证头在新会话启动时从环境重新读取。这正是 mcp_config.json 采用 ${MEM0_API_KEY} 会话期插值而非安装期固化的收益：只要环境变量持久存在（shell profile 或 ~/.claude/settings.json 的 env 块），重启即自动重连。

若重启后仍失败，检查两点：新 shell 中 echo $MEM0_API_KEY 是否可达；密钥是否以 m0- 开头（来自 Dashboard API Keys 页面，而非 legacy token）。

许可证

插件采用 Apache-2.0 许可（见 plugin.json 的 license 字段与插件目录内 LICENSE）。

小结： 本文按 README 的原始脉络完整走了「API key → 六平台安装 → onboard 验证 → 技能命令」的操作闭环，并用仓库源码补充了 Hook 接线的匹配器/超时设计、Codex 安装器的幂等合并与所有权识别机制、编码分类后台应用的指纹缓存与文件锁实现。所有关键实现均可在 integrations/mem0-plugin/ 目录下对照源码验证，对应测试位于 integrations/mem0-plugin/tests/（如 test_auto_setup_categories.py、test_coding_categories.py）。