Mem0 integrations 目录工程解析：九类 Agent 集成包的构建矩阵、pnpm 工具链与 CI/CD 接入规范

本文以 integrations/AGENTS.md 为主体，完整讲解 Mem0 单仓内 integrations/ 目录的组织原则：每个集成包如何做到"自带 package.json、锁文件、构建与测试、无共享工具链"，各包（Vercel AI SDK、OpenClaw、Claude Code 插件、n8n、Zapier、Strands 等）的构建/测试命令差异，以及新增一个集成时必须落地的 7 步 CI/CD 接入流程（发布标签路由、CI Gate 注册、marketplace 五处注册）。读完你能独立看懂并操作该目录下的任意集成包，并知道把新集成接入仓库发布体系的完整链路。

一、设计原则：自包含包，没有共享工具链

integrations/ 是 Mem0 的 Agent 与编辑器集成目录。integrations/AGENTS.md 开篇即给出硬性约束：

每个子目录都是自包含的：自己的 package.json、锁文件、构建和测试。不存在共享工具链。做任何操作前先查表。

这意味着你不能假设"在某个上层目录 pnpm install 一次就能驱动全部集成"，也不能把一个包的脚本命令套用到另一个包。文档给出的九行构建矩阵是整个目录的权威索引：

目录	包名	构建	Lint	测试
vercel-ai-sdk/	@mem0/vercel-ai-provider	tsup (CJS+ESM)	ESLint + Prettier	jest + vitest (edge/node)
openclaw/	@mem0/openclaw-mem0	tsup (ESM)	无	vitest
mem0-plugin/	Claude Code / Cursor / Codex 插件	无	无	pytest
mem0-plugin/.opencode-plugin/	@mem0/opencode-plugin	Bun	无	tsc 类型检查
pi-agent-plugin/	@mem0/pi-agent-plugin	tsup	无	vitest
deepseek-plugin/	@mem0/deepseek-plugin	tsup (ESM)	无	vitest
n8n-nodes-mem0/	@mem0/n8n-nodes-mem0	tsc	ESLint (n8n-nodes-base)	无
zapier-mem0/	@mem0/zapier	tsc	无	离线单元测试 + zapier validate
mem0-strands/	mem0-strands（PyPI）	hatch	Ruff + mypy	pytest

当前仓库目录结构与该矩阵完全一致（integrations/ 下另有 AGENTS.md、CLAUDE.md 两份 Agent 指引），即 deepseek-plugin/、mem0-plugin/（含嵌套的 .opencode-plugin/）、mem0-strands/、n8n-nodes-mem0/、openclaw/、pi-agent-plugin/、vercel-ai-sdk/、zapier-mem0/。

这个矩阵还隐含了一条发布拓扑信息：zapier-mem0/ 不在 npm 发布路由器中（它是手动部署到 Zapier 的，见第五节），n8n-nodes-mem0/ 测试列为 "none" 而 CI 里另有社区节点校验，其余 npm 包都有对应的 -cd.yml 发布流水线。

二、工具链约定：pnpm 一统，Bun 与 Python 为例外

矩阵之外，文档用一句话划定了工具链红线：

除 .opencode-plugin/（Bun）和 mem0-strands/（Python：pip / hatch）外，处处 pnpm。永远不用 npm，永远不用 yarn。

这一点可以从仓库文件得到印证：

• integrations/vercel-ai-sdk/package.json、integrations/openclaw/package.json 等包旁都随附了 pnpm-lock.yaml 和 pnpm-workspace.yaml，而 integrations/mem0-strands/python/pyproject.toml 声明 requires = ["hatchling"]、requires-python = ">=3.10"，构建脚本由 hatch 管理（dev 依赖列表里含 hatch）；
• integrations/mem0-plugin/.opencode-plugin/ 是 mem0-plugin/ 下唯一走 Bun 的嵌套包，因此 CI 中它的路径过滤器被单独排除在 mem0-plugin 之外（见第四节 ci-gate.yml 中的 !integrations/mem0-plugin/.opencode-plugin/** 反选规则）。

文档给出的标准操作序列以 vercel-ai-sdk 和 openclaw 为例：

cd integrations/vercel-ai-sdk
pnpm install
pnpm run build           # tsup
pnpm run lint            # eslint
pnpm run type-check      # tsc --noEmit
pnpm run prettier-check
pnpm run test            # jest
pnpm run test:edge       # vitest, edge runtime
pnpm run test:node       # vitest, node runtime

cd integrations/openclaw
pnpm install
pnpm run build           # tsup
pnpm run test            # vitest

这些脚本名并非示例性文字，而是与 integrations/vercel-ai-sdk/package.json 中 scripts 段逐字对应：build: "tsup"、lint: "eslint \"./**/*.ts*\""、type-check: "tsc --noEmit"、prettier-check、test: "jest"、test:edge / test:node 分别指向 vitest.edge.config.js 与 vitest.node.config.js 两份配置。也就是说同一包内同时维护了 Jest（主测试）与 Vitest 双运行时（edge/node）测试，这是该目录中唯一"测试列包含两套运行器"的包，对应矩阵中 jest + vitest (edge/node) 的标注。

文档最后强调了一条面向 AI 协作者的规则：每次 TypeScript 变更后都要跑类型检查，命令名以各包自己定义的为准——pnpm run typecheck 或 tsc --noEmit（vercel-ai-sdk 用的是带连字符的 type-check）。这条规则直接源于"无共享工具链"原则：脚本名不可跨包假设。

三、逐个解析：九种集成各自的形态与能力边界

文档"Each one is what"章节说明了每个包到底是什么。以下按文档顺序结合仓库实现逐一展开。

3.1 vercel-ai-sdk：createMem0 包装层

文档定性：vercel-ai-sdk/ 通过 createMem0 provider 封装 Vercel AI SDK，AI-SDK 仓库的集成必须走这个包装层，而不是直接用 MemoryClient。

从源码结构看，src/ 目录的拆分印证了这一职责边界：integrations/vercel-ai-sdk/src/mem0-provider.ts（provider 主体）、mem0-facade.ts（对上层暴露的门面）、mem0-generic-language-model.ts（泛型语言模型抽象）、mem0-provider-selector.ts、mem0-types.ts、stream-utils.ts 与 provider-response-provider.ts。package.json 的 dependencies 里同时列出了 @ai-sdk/openai、@ai-sdk/anthropic、@ai-sdk/google、@ai-sdk/groq、@ai-sdk/cohere，与其 tests/ 目录下按厂商组织的 mem0-provider-tests/（openai、anthropic、google、groq、cohere 五个测试文件）一一对应——包装层同时兼容多个 AI SDK provider，这正是"AI-SDK 生态走统一入口"的落地方式。

3.2 mem0-plugin：MCP 连接 + 生命周期钩子

文档定性：mem0-plugin/ 把 Claude Code、Cursor、Codex 连接到 mcp.mem0.ai MCP 服务器，并安装生命周期钩子实现自动记忆捕获；对外暴露 9 个 MCP 工具：add_memory、search_memories、get_memories、get_memory、update_memory、delete_memory、delete_all_memories、delete_entities、list_entities。

仓库内可以对照其真实形态：

• integrations/mem0-plugin/mcp_config.json 声明了 MCP 服务器连接：serverUrl: "https://mcp.mem0.ai/mcp/"，请求头携带 Authorization: Token ${MEM0_API_KEY}——即九个工具最终都通过这个托管 MCP 端点访问 Mem0 平台；
• hooks/ 目录下的 hooks.json、cursor-hooks.json、codex-hooks.json 分别是三个宿主编辑器的钩子清单，对应文档"安装生命周期钩子"的说法；
• scripts/ 目录（42 个 .py/.sh 脚本）承载钩子的具体行为，如 auto_capture.py、capture_session_summary.py、on_session_start.sh、on_pre_compact.py 等，tests/ 下 18 个 pytest 用例（如 test_auto_capture.py、test_session_stats.py）对它们做回归验证——对应矩阵中"无构建、无 lint、pytest"的极简工具链。

该插件是目录内唯一的纯 Python 插件，且同时通过五个 marketplace.json 对外发布（见第四节第 5 步）。

3.3 openclaw / pi-agent-plugin / deepseek-plugin：同构的编辑器与 Agent 插件

文档定性：三者是"同一形状"（same shape）的编辑器/Agent 插件；其中 deepseek-plugin/ 注册为 DeepSeek Harness（Cordis）的原生插件，把 Mem0 的 search/add 工具挂进去。仓库侧可佐证：

• integrations/deepseek-plugin/cordis.example.yml 即其 Cordis Harness 示例配置，src/ 含 index.ts 与 formatting.ts、scoping.ts、output.ts、telemetry.ts，tests/ 下五个 vitest 用例与之一一对应；
• integrations/openclaw/package.json 的 description 写着 "Mem0 memory backend for OpenClaw — platform or self-hosted open-source"，说明该插件同时支持托管平台与自托管 OSS 两种后端，tools/ 目录实现了 memory-add / search / get / list / update / delete 与事件查询等工具模块；
• integrations/pi-agent-plugin/src/index.ts 是其入口，src/ 按 capture/、config/、dream/、memory/ 组织，tests/ 八个 vitest 用例覆盖工具、捕获与遥测逻辑。

3.4 n8n-nodes-mem0：社区节点形态

文档定性：n8n-nodes-mem0/ 是 n8n 社区节点，能力为 add、search、get、update、delete。目录形态也完全符合 n8n 社区节点规范：nodes/Mem0/Mem0.node.ts（节点实现）、nodes/Mem0/Mem0.node.json（节点描述）、credentials/Mem0Api.credentials.ts（凭据定义）、index.js 入口与 gulpfile.js 资源打包，测试仅有 test/Mem0.node.test.ts 一个 Jest 用例，故矩阵中 Test 列标 "none"（无独立测试命令，lint 走 n8n-nodes-base 的 ESLint 约定）。

3.5 zapier-mem0：部署到 Zapier，不走 npm

文档定性：zapier-mem0/ 是 Zapier Platform CLI 应用，能力为 add、search、get、delete；它部署到 Zapier 而非 npm，因此不在 release router 中。文档给出的部署命令是：

gh workflow run zapier-mem0-cd.yml --ref main

且需要 ZAPIER_DEPLOY_KEY 仓库 secret。仓库中 zapier-mem0-cd.yml 的头部注释与其 workflow_dispatch 触发器、ZAPIER_DEPLOY_KEY: ${{ secrets.ZAPIER_DEPLOY_KEY }} 的注入点与文档描述逐字吻合。应用本体在 src/ 下按 Zapier CLI 约定分 creates/（add_memory.ts、delete_memory.ts）与 searches/（search_memories.ts、get_memories.ts），入口 src/index.ts 与顶层 index.js。

3.6 mem0-strands：PyPI 上的原生 MemoryStore

文档定性：mem0-strands/ 是 Strands 的原生 MemoryStore（Python，PyPI 发布名 mem0-strands），可插入 Strands 的 MemoryManager 实现自动召回与服务器端抽取，后端可指向托管 Mem0 平台或自托管 Mem0 OSS；代码包位于 mem0-strands/python/。pyproject.toml 佐证了包名、Python ≥3.10 门槛与 hatch 构建后端；实现位于 python/src/mem0_strands/（client.py、store.py 等），tests/ 含 test_client.py、test_store.py 等 pytest 用例，与矩阵"pytest + Ruff + mypy"一致。

四、Monorepo 级机制：标签路由、CI Gate 与 marketplace 注册

文档"Adding an integration"一节把新增集成的 CI/CD 落地拆成 7 步。理解这 7 步，需要先看懂仓库现有的两个中枢工作流。

4.1 release.yml：单一发布路由器与标签前缀

release.yml 是全仓唯一发布入口。其注释解释了设计动机：各包的 CD 工作流不再自己监听 release 事件，而是由路由器检查 release 标签、只派发匹配的那条流水线——"每次发布产生一次被路由的运行，而不是一次真实运行加七次跳过"。

路由核心是一段 bash case 分支，当前仓库实际注册的前缀为：

case "$TAG" in
  ts-v*)        workflow="ts-sdk-cd.yml" ;;
  cli-node-v*)  workflow="cli-node-cd.yml" ;;
  cli-v*)       workflow="cli-python-cd.yml" ;;
  vercel-ai-v*) workflow="vercel-ai-cd.yml" ;;
  openclaw-v*)  workflow="openclaw-cd.yml" ;;
  opencode-v*)  workflow="opencode-plugin-cd.yml" ;;
  pi-agent-v*)  workflow="pi-agent-plugin-cd.yml" ;;
  deepseek-plugin-v*)  workflow="deepseek-plugin-cd.yml" ;;
  n8n-nodes-mem0-v*) workflow="n8n-nodes-mem0-cd.yml" ;;
  mem0-strands-v*)   workflow="mem0-strands-cd.yml" ;;
  v*)           workflow="cd.yml" ;;   # Python SDK
  *)  exit 1 ;;                        # 未匹配则报错并终止
esac

注意文档强调的"裸 v* 分支必须保持在最后"：case 按顺序匹配，若把 v* 放前面，vercel-ai-v*、openclaw-v* 这类同样以 v 开头的标签会被误路由到 Python SDK 流水线。路由器匹配成功后通过 gh workflow run ... --ref refs/tags/$TAG -f tag=$TAG 派发到该标签所在的 commit 上，保证构建与 provenance 签名精确对应打标签的代码。这也解释了为什么 Zapier 包不在路由器中——它没有 v* 标签发布路径，只有 workflow_dispatch 手动触发。

4.2 ci-gate.yml：路径过滤 + 单一必需检查

ci-gate.yml 的头部注释解释了它存在的必要性：路径过滤的 CI 工作流无法在分支保护里设为必需检查（PR 没碰它的路径时它永远不汇报，必需检查会一直挂在 "Expected" 状态），所以用一个对每个 PR 都运行的 Gate 来聚合。其结构为：

1. changes job：用 dorny/paths-filter@v3 检测变更包。integrations/ 下每个包都有独立过滤器，例如 openclaw: ['integrations/openclaw/**', ...]、mem0_plugin: ['integrations/mem0-plugin/**', '!integrations/mem0-plugin/.opencode-plugin/**', ...]——那条 ! 反选规则正是为了把嵌套的 Bun 包 .opencode-plugin/ 交给独立的 opencode_plugin 过滤器；
2. 每个包一个 call job，形如 uses: ./.github/workflows/openclaw-checks.yml + secrets: inherit，仅在对应过滤器命中时执行；
3. 最终 gate job 在 needs 中列出全部调用 job（if: always()），用 jq 聚合各流水线结果：全部通过或跳过即成功，任一 failure/cancelled 即失败。注释明确分支保护只需要求一条状态检查："CI Gate"。

文档第 4 步所说的"在 ci-gate.yml 注册 CI 工作流"，落到代码就是三处改动：changes job 的 filters 加一条路径规则、加一个 uses: 包工作流的 call job、把该 call job 加入 gate job 的 needs 列表。

4.3 新增集成的 7 步清单（原文完整继承）

文档给出的接入流程原文如下，逐条说明：

1. 创建 integrations/<name>/ 并在其中构建，自包含。 不得依赖仓库其他包的产物或脚本。
2. 若发布到 registry，在 package.json 中设置 repository.directory: "integrations/<name>"，使 npm provenance 链接指向正确的子目录。仓库现例：vercel-ai-sdk/package.json 中 repository.directory 即为 integrations/vercel-ai-sdk。
3. 添加 .github/workflows/<name>-checks.yml 与 <name>-cd.yml：paths: 触发器、working-directory、cache-dependency-path 三处都使用 integrations/<name>；在 release.yml 的 case 块中注册发布标签前缀，裸 v* 分支保持在最后。文档同时警告：工作流文件名是承载语义的（load bearing）——npm OIDC trusted publishing 绑定的是"仓库 + 工作流文件名"，重命名工作流文件会直接弄断发布链路。
4. 在 ci-gate.yml 注册 CI 工作流：changes job 下的路径过滤器、一个 call job、gate job needs 列表中的一个条目（机制见 4.2 节）。
5. 若是 Claude Code 或编辑器市场插件，必须在五个 marketplace.json 中注册其路径：根目录 marketplace.json、.claude-plugin/marketplace.json、.cursor-plugin/marketplace.json、.codex-plugin/marketplace.json、.agents/plugins/marketplace.json。现例：根目录与 .claude-plugin/ 下的清单都指向 ./integrations/mem0-plugin，.claude-plugin/ 版本还携带 version 字段（如 0.2.15）。
6. 在 docs/integrations/ 下写文档，并把页面加入 docs/docs.json 与 docs/llms.txt。
7. 在 integrations/AGENTS.md 的表格与 [../.github/AGENTS.md] 的 CI/CD 表格中各加一行。 原文中该链接写作 ../.github/AGENTS.md，以仓库根目录为起点应写作 github/AGENTS.md——即 .github/AGENTS.md。

五、验证与排错速查

结合前文，操作 integrations/ 时可验证的事实与常见陷阱：

• 工具链：先查 integrations/AGENTS.md 的矩阵确定该包的构建/lint/测试命令；除 .opencode-plugin/（Bun）与 mem0-strands/（pip/hatch）外用 pnpm，永不使用 npm/yarn。
• TypeScript 变更：改完即跑类型检查，命令名以该包 package.json 的 scripts 为准（如 vercel-ai-sdk 是 type-check 而非 typecheck），或退而执行 tsc --noEmit。
• 发布标签：新包发布前确认 release.yml 的 case 块已注册前缀且位于 v* 之前；未匹配的标签会直接 exit 1 并在日志提示查看 AGENTS.md 的前缀表。
• 工作流文件：<name>-checks.yml / <name>-cd.yml 的命名不可改动（OIDC trusted publishing 按"仓库 + 文件名"绑定）。
• CI 状态：PR 上只看 "CI Gate" 一条必需检查；若新包没被 Gate 触发，检查 ci-gate.yml 的过滤器、call job 与 needs 三处是否齐备。
• Zapier 发布：gh workflow run zapier-mem0-cd.yml --ref main，前置条件是仓库配置了 ZAPIER_DEPLOY_KEY secret（见 zapier-mem0-cd.yml）。
• 插件市场：新增编辑器插件后，核对五个 marketplace 清单（根、.claude-plugin/、.cursor-plugin/、.codex-plugin/、.agents/plugins/）都已登记路径。

六、关键文件索引

文件	作用
integrations/AGENTS.md	本文主体：构建矩阵、命令约定、7 步接入流程
integrations/vercel-ai-sdk/src/mem0-provider.ts	createMem0 provider 入口
integrations/mem0-plugin/mcp_config.json	MCP 服务器连接（mcp.mem0.ai）
integrations/mem0-plugin/hooks/hooks.json	生命周期钩子清单（Cursor/Codex 各有对应文件）
integrations/deepseek-plugin/cordis.example.yml	DeepSeek Harness（Cordis）示例配置
integrations/n8n-nodes-mem0/nodes/Mem0/Mem0.node.ts	n8n 社区节点实现
integrations/zapier-mem0/src/index.ts	Zapier CLI 应用入口
integrations/mem0-strands/python/pyproject.toml	PyPI 包定义（hatch 构建，Python ≥3.10）
.github/workflows/release.yml	发布标签路由器（case 前缀分派）
.github/workflows/ci-gate.yml	CI Gate：路径过滤 + 聚合必需检查
marketplace.json / .claude-plugin/marketplace.json	插件市场注册（共五处，见第四节第 5 步）
.github/AGENTS.md	仓库级 CI/CD 表格（与 integrations 表互相引用）