企业官网建设流程全解析

mem0-integrate 技能详解：以目标驱动、测试先行的流水线将 Mem0 集成进现有仓库

【免费下载链接】embedchainThe Memory Layer for AI Agents - Drop-in memory infrastructure for AI agents and apps. Context that persists. Built for production.项目地址: https://gitcode.com/GitHub_Trending/em/embedchain

Mem0 在 skills 体系中提供两类技能：常驻上下文、指导日常 SDK 编码的参考技能，以及按需以斜杠命令触发、真正执行端到端工作流的流水线技能。mem0-integrate即后者：它让 AI 编码助手以"目标驱动、测试先行（TDD）、增量无侵入"的方式，把 Mem0 记忆层完整接入一个已有代码库，并产出独立的功能分支与配套产物，交给同属一个工作区的验证技能 mem0-test-integration 做真实端到端验证。读完本文，你将掌握该技能的安装方式、触发与适用边界、七大不可妥协的集成原则、十步执行流水线与每步的硬性门禁、产物与退出码约定，以及它在"如何让仓库行为在关闭开关时与 main 逐字节一致"这一核心设计上的底层原理。

技能定位：这是"动手干活的流水线"，不是"随查随用的参考"

mem0-integrate是一个pipeline skill（流水线技能），而非 reference skill（参考技能），这一点在它的 README 开篇即被强调。它通过/mem0-integrate被调用，让助手实际完成把 Mem0 集成进目标仓库的工作——自动检测仓库语言与技术栈、询问用户选择托管版 Mem0 Platform 还是自托管 Mem0 开源版、先写会失败的测试再动手实现，并将集成做成果增量式、可由特性开关（feature flag）控制的形式，保证开关关闭时原有行为逐字节不变。最终产物是一个本地功能分支（mem0-integrate/...）和skills/mem0-integrate/SKILL.md中约定的.mem0-integration/产物目录（包含goal.md、plan.md、product.json等），供配套验证技能消费。

与 mem0-integrate 紧密配合的是同属流水线类的 mem0-test-integration：前者负责"写出集成并提交到功能分支"，后者负责"在同一工作区、同一条分支上运行验证并产出记分卡"。二者通过.mem0-integration/共享工作区与分支，属于松散耦合——验证技能从不修改任何源文件，且两者都隶属于 skills/README.md 中描述的 Mem0 Skill Graph（参考技能链与流水线技能链的完整图谱见该目录）。

在仓库内还有一份定义完备的 SKILL.md，它补充了技能元数据（author、version0.1.0、category、license Apache-2.0），并明确记录了本技能测试过的 SDK 版本范围：Python 包mem0ai需在>=2.0.0,<3.0.0，npm 包mem0ai需在>=3.0.0,<4.0.0。

何时使用与何时不该使用

该技能面向的场景是"给已有仓库加记忆层"，README 与 SKILL.md 给出了可直接照搬的触发短语：

• "Integrate Mem0 into this repo"
• "Add Mem0 to my project"
• "Wire Mem0 into<repo>"
• "How do I add memory to an existing project?"

同时必须明确不要用该技能覆盖以下场景，它们分别有专属技能：

依赖委派规则：先查已有技能，不重复造轮子

SKILL.md 要求写任何代码前先判断目标技术栈是否已被某个已发布技能覆盖；若被覆盖，必须委派——把该技能的调用点（call-site）模式原样复制进plan.md与测试中，而不是自己改写：

委派的技能原始 URL 需记录在plan.md的Delegated skill:字段下，步骤 7 的测试作者与步骤 8 的实现子代理都会读取该字段。

安装与前置条件

四种安装方式

1. CLI 安装（Claude Code、Codex、OpenCode、OpenClaw 等支持 skills 标准的任何工具）：

npx skills add https://github.com/mem0ai/mem0 --skill mem0-integrate

如需在同一条分支上验证，还要一并安装配套验证技能：

npx skills add https://github.com/mem0ai/mem0 --skill mem0-test-integration

2. Claude.ai 网页端：将skills/mem0-integrate文件夹下载为 ZIP，进入Settings > Capabilities > Skills，点击Upload skill并选择该 ZIP。

3. Claude API（Skills API）：

curl -X POST https://api.anthropic.com/v1/skills \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "mem0-integrate", "source": "https://github.com/mem0ai/mem0/tree/main/skills/mem0-integrate"}'

4. 仓库内阅读版：技能定义、元数据与完整约束即位于 SKILL.md，详细步骤机制见 references/pipeline.md，步骤 8 与步骤 10 所需的逐字子代理系统提示见 references/subagent-prompts.md。

前置条件（不满足即拒绝启动）

启动前以下条件必须全部成立，否则技能会以书面理由干净退出（详见下文"退出码"中的 1）：

1. 当前工作目录位于一个 git 仓库中且索引干净（无未提交改动）——保护用户工作，所有编辑落在功能分支而非未完成改动之上；
2. 仓库有可检测的语言（package.json/pyproject.toml/requirements.txt），无语言信号则干净退出并附理由；
3. 仓库存在后端——判定依据为存在backend/、server/或api/目录；是含 FastAPI/Flask/Django/Starlette 的 Python 包；是含 Express/Fastify/Koa/NestJS/Next-API 路由的 Node 包；或使用 LangGraph、LangChain、LlamaIndex、Agno 等代理循环框架。纯前端仓库（纯 React/Vue/Svelte SPA、静态站、移动端）直接以代码 1 + 理由退出：Mem0 不在客户端安装；
4. 用户已经决定Mem0 适合该仓库——本技能不做"四处翻代码论证契合度"的事，需要用户带着具体目标来（步骤 2 的仓库通读只是定位集成表面的机制性工作，不构成契合度论证）。

前置条件中的 API 密钥要求：Mem0 Platform 需要MEM0_API_KEY，Mem0 开源版默认 LLM 需要OPENAI_API_KEY（来源：README 的 Prerequisites 一节与 SKILL.md 步骤 4 的键位表格）。

核心设计：让维护者"无从反驳"的七条集成原则

SKILL.md 将技能的真正目标定义为产出一份维护者无需争论就能合并的 PR，因此把一切侵入式做法排除在外，形成七条不可妥协的原则：

1. 增量而非替换（Additive, not replacing）。若目标仓库已有记忆系统、会话存储、用户上下文层或任何叫Memory/memory_*的东西，Mem0 与它并列共存而非取而代之，既有系统保持原样继续工作。
2. 默认不启用（Opt-in by default）。所有新增 Mem0 代码都藏在特性开关后面（形如环境变量MEM0_ENABLED=1、配置键或策略选择器）。开关未设置时，仓库行为与原始版本逐字节一致。
3. 零破坏（No breakage）。不删除导出、不改名公共函数、不变更方法签名、不改既有测试、不改变既有测试的行为。全部既有测试无论开关开闭都必须原样通过。
4. 最小依赖面（Minimal dependency surface）。只加mem0ai（及委派技能要求的依赖），不引入仓库尚未使用的向量库、图数据库或 Provider SDK。
5. 提交可分片（Separable commits）。代码、测试、配置/文档分属不同提交，便于评审者逐个 cherry-pick。
6. 空假设胜出（The null hypothesis wins）。若步骤 6（计划）结束后仍找不到"增量、可开关"的落点，以代码 1 退出并附理由——一个糟糕的 PR 不如没有 PR。
7. 只做后端（Backend only）。API 密钥、记忆作用域、用户身份解析放在客户端不安全，集成只存在于服务端代码；前后端兼有则调用点在后端文件中，纯前端仓库在前置条件阶段即被拒绝。

这七条原则在四道门禁强制执行：前置条件（拒绝纯前端仓库与增量落点不存在的仓库）、步骤 2 仓库理解（确认存在后端并列出候选表面）、步骤 6 计划评审（拒绝会改动既有导出或指定客户端调用点的方案）、步骤 10 自愈循环（对违反原则的问题拒绝"修复"——而是把它暴露给用户）。

十步流水线与逐部门禁

SKILL.md 以表格形式给出全流程路由概览，完整机制、文档模板与门禁规则位于 references/pipeline.md，执行某一步前应读取该文件。下面按执行步骤展开：

第 1 步：语言检测

按信号判定技术栈：package.json+ TS 配置为 Node/TypeScript；package.json（无 TS 配置）为 Node/JavaScript；pyproject.toml或requirements.txt为 Python。monorepo 若同时存在多套，先询问操作哪个子目录再递归。

第 2 步：仓库理解——后端在哪里

这是机制性工作：先想清楚README.md（含README_*.md变体首页）、CONTRIBUTING.md/AGENTS.md/CLAUDE.md、package.json/pyproject.toml的脚本与入口、顶层两级目录布局（不递归），以及docker-compose.yml、Dockerfile、Makefile、langgraph.json、next.config.*、nuxt.config.*等关键配置文件，再产出.mem0-integration/repo-summary.md。该文档模板要求回答：仓库做什么（描述行为而非罗列依赖）、架构速览（后端/前端/代理循环/既有记忆系统）、排序后的候选集成表面（格式为<文件>:<行范围>+ 函数 + 一句话理由）、以及"此处不合适"清单（如"前端聊天组件：客户端侧，被仅后端规则排除"）。

将摘要渲染给用户并询问"这个理解对吗？步骤 3 应该推进哪个候选表面（1、2、3…）？"。门禁规则：找不到任何后端表面退出 1；每个候选表面都要求替换既有记忆/会话系统则按增量原则退出 1（用户可手工指向非冲突位置后重跑）；用户更正摘要后需重新确认，最多 3 轮，超限退出 1。用户选定的表面索引被烘焙进product.json的preferred_site字段。

第 3 步：产品选择——Platform 还是 OSS

先读取https://docs.mem0.ai/llms.txt中## Identify the User's Setup块的 Platform-first 路由规则，再套用启发式。可以提问但绝不空手提问：

• 已存在 3 个以上托管服务 SDK（@clerk/*、stripe、@supabase/*、openai、@upstash/*、posthog-*）→ 推荐Platform；
• 存在 2 个以上本地基础设施信号（含 postgres/redis/qdrant/neo4j 的docker-compose.yml、ollama 配置、自托管认证）→ 推荐OSS；
• 无强信号时默认推荐Platform：集成成本更低，且日后迁移受支持。

技能文档给出一段可直接套用的推荐话术示例："I seestripe,@clerk/nextjs, and@supabase/supabase-js, managed services throughout. I recommendMem0 Platform(4-line integration). Override and use open source?"选择结果锁定进第 5 步的 goal 文档，此后不再重决。

第 4 步：API 密钥检查（环境变量优先，其次询问）

环境变量中已有则继续。MEM0_API_KEY缺失且轨道为Platform时，默认走 Agent Mode：先pip install mem0-cli或npm install -g @mem0/cli，然后运行mem0 init --agent --agent-caller <你的名字> --json（<你的名字>替换为 claude-code、cursor、codex 等代理身份）；若忘了带--agent-caller，init 后补跑mem0 identify <你的名字>。该初始化命令与代理身份自声明机制在本仓库 CLI 实现中真实存在（见 cli/python/src/mem0_cli/commands/init_cmd.py 中的--agent/--agent-caller处理与代理身份嗅探逻辑）。缓存密钥到.env需用户同意，并告知用户稍后可执行mem0 init --email <邮箱>认领同一把密钥，不打断代理。CI 模式（MEM0_INTEGRATE_CI=1）下缺键直接退出代码 2 并报出缺失键名。

密钥安全规则：绝不在trace.jsonl中回显密钥值；仅在用户明确同意后写入.env，若.env不在.gitignore中还需追加。OSS 用户若想用非 OpenAI 的 LLM，被引导至components/llms/*文档并以所选 Provider 的密钥重跑本步。

第 5 步：目标文档（硬门禁）

在进入第 6 步前，写出.mem0-integration/goal.md并要求用户批准。其模板共六个字段：

• What gets stored：一句话。用户话语？抽取出的偏好？特定领域事实（如"饮食禁忌"）？
• When it gets retrieved：一句话。每轮用户对话时？特定工具调用前？会话开始时？
• Why：一句话，描述用户可见的行为变化——写"助手能跨会话记住之前的订单"，而不是"我们加了记忆"。
• Product：Platform | OSS（第 3 步锁定，不可变更）。
• Delegated skill：委派表中选中的已发布技能原始 URL，或"none, custom integration againstskills/mem0"。
• Out of scope：任何明确排除的事项（"无图记忆""不多模态""不从既有存储迁移"）。

规则：用户必须显式批准；若用户编辑了该文档，需重新加载再确认；goal.md是测试套件据以编写的契约，第 6 步开始后永不重写；最多 3 轮拒绝，第 4 次以代码 3 + 拒绝记录退出——集成目标不够明确到可以推进。

第 6 步：集成计划（硬门禁）

goal.md解决"是什么、为什么"，本步解决"在哪里、怎么改"，且在任何代码写出前需显式签收。执行范围化的仓库阅读而非全面扫描：

• grep 与目标匹配的 LLM 调用点（openai.chat.、anthropic.messages.、model.generateContent、ChatOpenAI、createLLM）；
• grep 用户身份来源（req.user、session.user、auth()、ctx.userId、cookies）；
• 检查package.json/pyproject.toml/requirements.txt的冲突，例如存在不同版本的mem0ai。

然后写出.mem0-integration/plan.md。它的字段定义了实现契约的核心结构：

• Write pattern / Read pattern：各一句话，例如写入"每次助手回复后调用client.add([user_msg, assistant_msg], user_id=<来源>)"，读取"构建 LLM 提示词前调用client.search(query=最新用户消息, user_id=<来源>, limit=5)并把结果以系统消息注入"；
• User identifier source：代码路径（如req.auth.userId、session.user.email）；无则询问用户；
• Session scoping：user_id、agent_id（静态 slug 或 null）、run_id（来源或 null）；
• Write call site / Read call site：<文件>:<行范围>内的<函数>；
• Dependencies to add：按 frontmatter 钉死的版本；
• Preserved behavior：编辑后必须继续工作的既有行为清单；
• Coexistence：与集成并列的每个既有系统逐条列出，指明文件/类，示例："既有agents/memory/storage.py的MemoryStorage类保持不动并保留其 LangGraph SummarizationEvent 流程；Mem0 作为并行的长期事实存储加在一个新文件里，仅在MEM0_ENABLED=1时被调用"；
• Feature flag：确切机制与默认值（必填），如env MEM0_ENABLED=1默认未设置/关闭，或config.mem0.enabled默认 false。开关处于默认态时仓库必须与 main 行为完全一致；
• Sources consulted：至少 2 个来自 SKILL.md"Canonical sources"的 URL，其中至少一个docs.mem0.aiURL 和一个委派技能 URL，并注明具体章节；
• E2E recipe：给验证技能驱动应用端到端运行的方法，含start、ready_probe、compose_services、write_call、write_async_wait_ms、read_call、read_assert等字段（详见配套验证技能）；纯库（无可运行入口）可省略本段，E2E 步骤将带警告跳过；
• Rejected alternatives：1~2 条考虑过但未选用的模式及理由。

规则：批准前须向用户展示每个调用点周围 10 行上下文；若写入或读取任一找不到合理调用点，以代码 5 退出并请用户手工点名文件（这是"此处不合适"的信号，不要猜）；计划最多 3 轮拒绝；用户手改plan.md后需重新加载确认。plan.md（而非goal.md）才是第 8 步子代理实现的契约。

第 7 步：测试先行（TDD）

主代理依据goal.md、在仓库的原生测试框架中写出会失败的测试：Python 默认pytest，TypeScript 检测到vitest用vitest，否则jest（JavaScript 同）。测试断言形状必须匹配规范签名：Platform 方法签名依据https://docs.mem0.ai/openapi.json中/v1/memories/与/v1/memories/search/的请求体 schema；OSS 方法签名依据plan.md点名的委派技能（从其原始 URL 拉取）或默认的mem0技能。不要手搓请求形状，委派技能若有示例块则原样照搬。最少两个测试文件，路径取自plan.md调用点：test_mem0_write.<ext>断言在写入调用点调用了add()且载荷形状（Platform 的 messages 数组 vs OSS 的字符串）与user_id来源正确；test_mem0_read.<ext>断言search()在读取调用点之前运行且结果被接入 LLM 提示或响应路径。

测试必须在未设置MEM0_API_KEY时可被 import——这是把第 8 步推向"懒构造MemoryClient()/Memory()"的设计压力：模块级急切初始化会在缺失密钥时碰触 API 并在收集中破坏既有测试。运行测试，它们必须失败；若实现前就通过，说明测试写错了，重写。

第 8 步：实现（全新上下文子代理）

生成一个子代理，输入为仓库、goal.md、plan.md、两个测试文件、委派技能直链、按mem0_tested_versions钉死的 SDK 源码、https://docs.mem0.ai/llms.txt与（Platform 时）https://docs.mem0.ai/openapi.json；不给予主代理的推理轨迹或草稿。系统提示必须逐字使用 references/subagent-prompts.md 中的实现提示词——这是全新上下文子代理拿到的唯一契约，改写会丢掉评审环节必须兜住的约束。

该提示词的七条约束全部在评审时强制：只改plan.md调用点点名的文件或严格新增文件；不删除/重命名任何既有符号、不改任何公共签名；不修改任何既有测试；每一行新增 Mem0 代码都藏在特性开关后；只用 Platform | OSS 对应 SDK 面；保留plan.md的 Preserved behavior 与 Coexistence 全部内容；懒构造客户端。关于最后一条，仓库源码给出了直接证据：Python 平台端 mem0/client/main.py 的MemoryClient.__init__会从os.getenv("MEM0_API_KEY")取键，取不到即抛ValueError("Mem0 API Key not provided...")，随后建立 httpx 客户端并经self._validate_api_key()发起网络校验（mem0/client/main.py第 116–147 行区域），因此在模块导入期实例化必然命中网络与密钥校验——这正对应提示词第 7 条"MemoryClient()在__init__中校验 API key（会发起网络调用），绝不可在 import 时实例化，应在请求/处理器路径内首次使用时构造"。OSS 端 mem0/memory/main.py 的Memory(config: MemoryConfig = MemoryConfig())同样建议函数内单例（functools.lru_cache、模块级_client = None+ getter 或 DI 作用域），因为它可能急切初始化 embedding 与 LLM Provider。急切初始化会在缺失或无效密钥时于收集中破坏既有测试套件——即原则 3 的无侵入违反。

子代理返回 diff 后，主代理对照plan.md（机械契约）与goal.md（意图）评审：批准则应用并提交；拒绝则给出具体可执行的反馈（不是"再试一次"）；最多 3 轮评审，超限以代码 4 退出并附最后 diff 与评审反馈。

第 9 步：提交与交接

创建分支mem0-integrate/<短目标slug>，按四个可分片提交落盘以便评审者 cherry-pick：

1. mem0: add gated dependency——仅pyproject.toml/package.json变更；
2. mem0: add integration module——新增文件；
3. mem0: wire into <call site>——调用点编辑，仍受开关控制；
4. mem0: add tests——新增测试文件。

带--no-heal时打印Run /mem0-test-integration to verify.并退出，否则进入第 10 步。

第 10 步：自愈循环（默认开启，--no-heal关闭）

以子进程运行/mem0-test-integration --ci。若scorecard.json报告overall: pass，完成并退出 0。否则进入有界循环：

1. 分类失败项并路由：install/static_checks修依赖或导入；unit_tests修接线或断言；smoke_test修 API 键或 SDK 调用形状；e2e_test修 recipe、开关接线或集成点；既有测试失败（验证技能退出码 7、scorecard 中non_invasive: false）则立即停止——这是无侵入违反，不得尝试修复，以代码 6 + 理由退出；
2. 派生补救子代理（全新上下文），输入plan.md、goal.md、scorecard.md、scorecard.json、最近提交的 diff 与对应类别日志（test-stdout.log/smoke-stdout.log/e2e-app.log/e2e-calls.log），系统提示逐字使用subagent-prompts.md的补救提示词；
3. 应用 diff并在同一条分支上以mem0-heal: <类别> attempt <N>提交，不 amend 先前提交（评审者需要自愈轨迹）；
4. 重跑/mem0-test-integration --ci：overall: pass则退出 0；同类仍失败则计数加一继续循环；换成了另一类失败说明发生回归，用git revert HEAD --no-edit回滚自愈提交，记录进.mem0-integration/heal-trace.md，退出 6；
5. 有界迭代：默认每类失败最多 3 次尝试，--heal-max N可覆盖（硬上限 10）。耗尽后以代码 6 退出并附完整尝试轨迹；
6. 循环后总结写入.mem0-integration/heal-trace.md：哪类失败、几次尝试、每个 diff 意图、最终状态，成功时附初始与最终 scorecard 的差异。

调用参数与两种模式

/mem0-integrate # 交互式，heal 开启 /mem0-integrate --no-heal # 提交后停止；人工验证 /mem0-integrate --heal-max 5 # 每类失败的自愈次数上限（默认 3） /mem0-integrate --product platform # 跳过产品提问 /mem0-integrate --product oss /mem0-integrate --ci # 非交互（供测试框架用）

产物与退出码约定

.mem0-integration/产物目录

所有产物都在仓库根目录的.mem0-integration/下，首次运行时该目录被加入.gitignore；除该目录与仓库源树外不写任何东西。

退出码语义

配套的松散耦合验证技能

在 README 的 Workflow 段中，两技能配合使用：

/mem0-integrate → 创建 mem0-integrate/<slug> 分支， 写出 .mem0-integration/ 产物， 按会失败的测试实现功能 /mem0-test-integration → 运行仓库原生测试套件， 执行一次真实端到端冒烟流程， 产出记分卡

验证技能 mem0-test-integration 的关键设计是无侵入契约驱动的双通验证：Pass A（开关关闭）要求全部既有测试 100% 通过，任何失败都会让记分卡标记non_invasive: false并置overall: fail，且带一个自愈循环拒绝触碰的独立理由码（退出码 7）；Pass B（开关打开）才跑新增测试、冒烟与 E2E。冒烟测试总是使用前缀为mem0-test-integration-的一次性随机user_id（例如 Platform Python 端c.add([{"role": "user", "content": "I prefer aisle seats"}], user_id=uid)后c.search("seat preference", user_id=uid)断言命中、c.delete_all(user_id=uid)清理），避免污染真实数据。E2E 测试则真正启动应用、按plan.md的 recipe 驱动写路径与读路径，用read_assert判定"用户之前说过的内容确实在之后回来了"。该技能从不修改源文件，其明确宣称的能力边界是"只抓编译与运行期 bug"——存储的数据是否真的是用户想存的、search是否在正确时机运行、user_id是否匹配真实会话作用域等逻辑正确性问题留给人工评审（scorecard 中设有显式 "NOT checked" 章节）。

与验证技能的分工和边界

mem0-integrate明示以下内容超出其范围（见 SKILL.md 的 "Explicitly out of scope"）：

• 替仓库四处找契合点——人类在调用前就应决定 Mem0 在哪里有帮助；
• 替换任何既有记忆/会话/状态系统——永远增量 + 特性开关；
• 修改既有测试，即使是想在自愈中"修复"它们——开关关闭后失败的测试是无侵入违反，不是待补的 bug；
• 静默决定 Platform vs OSS——总是先给推荐再询问；
• 切换分支、推送或开 PR——只在本地提交并停止（或进入同样是本地的自愈循环）；
• 存储间数据迁移——有需要就引导用户查阅migration/oss-to-platform文档；
• 超出 OSS 默认 LLM 的 Provider 选择——需要自定义 LLM/embedder/向量库时引导至components/*文档并以新密钥重跑步骤 4。

与之配套，/mem0-test-integration的核心目标是验证集成编译与运行正确、且对原仓库无侵入，其产物scorecard.md/scorecard.json记录每项检查的通过状态、摩擦指标（如依赖安装重试次数、既有测试失败数）与 SDK 警告；该技能同样只读、不提交 scorecard 文件。两者在生产节奏上的最佳实践是：集成 → 验证 → 人工评审逻辑。即便自动化全部通过，"何时取回、取回什么、作用域是否正确"这类语义问题仍需要基于goal.md与真实用户会话逐项确认——这正是整套技能把"逻辑正确性留给人工评审"作为显式边界的原因。

技能本身以 Apache-2.0 许可发布；需要深入自定义流程细节的读者可直接阅读仓库内的 SKILL.md、references/pipeline.md 与 references/subagent-prompts.md。

【免费下载链接】embedchainThe Memory Layer for AI Agents - Drop-in memory infrastructure for AI agents and apps. Context that persists. Built for production.项目地址: https://gitcode.com/GitHub_Trending/em/embedchain