谈谈多Agent协作下的 AI 记忆和知识治理

本文题目是有些太理论化了，说个场景大家就知道要讲什么了。

场景：用 Claude Code、opencode、Codex、WorkBuddy、CodeBuddy、Trae、Cursor 等多个 AI coding agent 开发同一个项目。

问题：怎么保证它们记得住同一件事、知识不分裂、且不会因为"记错了"而变傻。

是不是也遇到过？下面是理论加实操，建议伙伴们收藏阅读。

我是加贝哥，十八年IT老兵，「猿in」主理人， 「开源AI知识库」作者，前G厂程序员/架构/产研经理，AI进化派，一线OPC创业者。

我的 「OPC成长知识库」，主要分享自媒体/IP学习总结，实践心得，以及一人公司（OPC）内容库运营相关经验，伙伴儿们可以 免费 关注订阅。

0. 一句话结论

不要指望任何一家 agent 的"记忆功能"。把知识写成仓库里的纯文本，让每个 agent 在每次会话开始时读到它 ------ 这是目前唯一跨工具成立的做法。

而第二步才是关键：这份文本要写成"索引"，不要写成"手册"。 2026 年几项实证研究一致表明，指令文件写得越全，agent 反而越差（成功率不变或下降，成本上升 20% 左右）。记忆的价值不在于"记住多少"，而在于"每条都在该出现的时候出现"。

下面来说说为什么和我们要怎么做。

1. 先把问题拆对：所谓"记不住"是三种不同的病

大家把三件事混成一个词，所以找不到解法。

类型	本质	症状	现有机制
工作记忆	上下文窗口	聊到第 80 轮开始自相矛盾、重复已否决的方案、忘记你 20 轮前改过的文件	compaction（有损压缩）、subagent 上下文隔离
跨会话记忆	会话之间没有状态	新开一个会话，agent 对你的项目一无所知	常驻指令文件、agent 自写的 memory 目录
语义知识库	知识不可检索	团队半年前为什么选了 A 方案、某个第三方 API 的坑、领域术语	docs/ADR、MCP memory server、外部知识库

关键判断：在多 agent 场景下，90% 的痛点不是"模型记忆能力差"，而是"知识从未被写下来"。

你说"Claude 忘了我上周定的架构决策"------它确实忘了，因为你没写。它上周的上下文在会话结束时就被丢弃了，这是设计如此，不是 bug。所有工具的"记忆"本质都是在会话启动时重新注入文本，不是真的记住。

想明白这一点，方案就很朴素了：**问题不是"怎么让 AI 记住"，而是"怎么让团队把该记的东西落成文件，并保证每个 agent 都能读到"。**这其实是文档工程，不是 AI 工程。

2. 各家现在怎么做（2026.10 现状）

工具	常驻指令文件	Agent 自写记忆	按需加载机制	读取 AGENTS.md
Claude Code	`CLAUDE.md`（根/子目录/用户/组织级）	✅ auto memory，`~/.claude/projects/<repo>/memory/MEMORY.md`，每次加载前 200 行或 25KB	`.claude/rules/`（path glob）、skills、subagents	✅ 可读，也可 `@AGENTS.md` 导入
opencode	`AGENTS.md`（全局 `~/.config/opencode/AGENTS.md` + 目录向上逐级 + 嵌套按需发现）	❌ 无记忆子系统	嵌套 AGENTS.md 在访问该目录时注入	✅ 原生（兼容 `CLAUDE.md`）
Codex CLI	`AGENTS.md`（+ `AGENTS.override.md`）	视版本而定，早期无，新版本有 memories 目录，能力不稳定	无 path 级规则，合并后统一注入	✅ 原生，32 KiB 合并上限
Gemini CLI	`GEMINI.md`（`~/.gemini/GEMINI.md` + 递归扫描拼接）	✅ `save_memory` 工具写入 `~/.gemini/GEMINI.md`	无 path 规则，`/memory show` 可查实际加载内容	✅ 可配置
CodeBuddy（腾讯）	`CODEBUDDY.md`（用户/项目/本地三级）+ `.codebuddy/rules/`	✅ Memory 机制，对话中自然表达偏好即记录	rules 支持 always / agentic / manual 三种加载策略	视配置
Trae	规则与记忆面板	✅ 全局 `user_profile.md` + 项目 `project_memory.md`，仅存本地	---	视配置
Cursor	`.cursor/rules/*.mdc`	视版本	frontmatter 的 `globs` / `alwaysApply`	✅ 逐步原生支持

从这张表能读出的三件事

第一，唯一真正跨工具的东西是 AGENTS.md 这一层。 它在 2025 年 12 月被捐给 Linux Foundation 下的 Agentic AI Foundation，目前 6 万多个开源仓库在用，Codex、Cursor、Copilot、Gemini CLI、opencode、Aider、Windsurf、Jules、Devin 都原生读。Claude Code 走 CLAUDE.md 但可以导入 AGENTS.md。这是你唯一值得重仓投入的格式。

第二，别被"记忆"这个词骗了。 opencode 的源码分析说得最直白：它没有记忆子系统。你感受到的"它记住了项目规则"，是每次请求前把 Markdown 注入 system prompt 的结果；你感受到的"它能回顾昨天的会话"，是 SQLite 里存着历史消息，但新会话并不会去检索它。"运行时存了"和"模型现在能推理到"是两回事。 这不是 opencode 的问题，绝大多数工具都是这个结构。

第三，agent 自写的记忆是可迁移性最差的一层。 Claude 的 auto memory 存在 ~/.claude/projects/ 下，机器本地、不跨端、别的工具读不到。Trae 明说记忆不跨电脑。Codex 和 Gemini 的写入机制格式各异。把关键知识托付给这一层，等于把资产锁在某一家工具里。 换工具那天，你三个月的"培养"归零。

这里有个流传很广的说法："如果你不拥有自己的 harness，你就不拥有自己的记忆。" 我的看法更实际一些：你只需要拥有那份 Markdown。 harness 随便换，只要知识在仓库里，任何工具打开都能接上。

3. 反直觉的部分：写得越多，效果越差

这是 2026 年最重要的一组发现，也是网上绝大多数"AGENTS.md 模板"在误导人的地方。

ETH Zurich 的研究（Gloaguen et al., ICLR 2026 Workshop）

138 个真实 GitHub issue、12 个仓库、4 个 agent（Claude 3.5 Sonnet、Codex GPT-5.2、GPT-5.1 mini、Qwen Code），三种条件对比：

条件	任务成功率	推理成本
没有 context 文件	基线	基线
LLM 自动生成的 AGENTS.md	−3%	+20% 以上
人写的 AGENTS.md	+4%（统计上不显著）	最高 +19%

还有个细节很扎心：Sonnet-4.5 自动生成的 context 文件，100% 都包含"代码库概览"，而这恰恰是 agent 自己读代码就能知道的东西。研究者直接指出，模型厂商普遍推荐的"架构概览"章节，实测"没有帮助"。

为什么？trace 分析给出了答案：agent 忠实地执行了 文件里的每条指令 ------ 跑了更多测试、读了更多文件、做了更多 grep、多做了代码质量检查。活儿干得更多，但补丁没变得更好。这叫合规天花板：agent 把每条指令都当同等重要，于是产出更多动作，而不是更高的准确率。

另外两项研究的补充

Lulla et al.（2026） ：10 仓库 124 个 PR，有 AGENTS.md 时中位耗时 −28.6%、输出 token −16.6%。但它没测正确率。所以"变快了"和"变对了"是两件事，别混着引用。
dos Santos et al.（2026） ：审计 100 个热门开源仓库的 AGENTS.md/CLAUDE.md，定义了六种"配置气味"。91% 的文件至少有一种。 最高发的是 Lint Leakage（62%） ------把 ESLint/Prettier 已经定义的规则用自然语言抄了一遍；其次是 Context Bloat（42%） ------塞满代码里已有的信息；第三是 Skill Leakage（35%）。

那什么真的有用？

研究里唯一"可靠改变行为"的是：仓库特有的工具调用。文件里提到某个项目自定义脚本时，agent 平均每个任务调用它 2.5 次；不提时不到 0.05 次。50 倍差距。

所以写作原则可以收得很紧：

该写	不该写
精确的构建/测试/lint 命令，带非显然的 flag	架构概览、代码库结构描述
只有本仓库才有的约定和例外	语言通用的最佳实践（交给 linter）
明确的禁止项（"改完 migration 不要手动补 SQL"）	"写整洁的代码"这类星座运势
指向文档的指针（路径 + 一句话说明）	把文档内容复述进指令文件
每个任务都适用的硬约束	只在特定任务才需要的流程（该进 skill）

一句话：写成目录，不要写成百科全书的正文。

4. 落地方案：四层架构

Plaintext 复制代码

┌─────────────────────────────────────────────────────────┐
│ L3  检索层    MCP memory server / 团队知识库             │
│      什么时候：需要跨会话、跨项目检索的历史决策与领域知识  │
│      特征：按需查询，不常驻，可带时效与出处               │
└─────────────────────────────────────────────────────────┘
                          ▲ 只在需要时下沉
┌─────────────────────────────────────────────────────────┐
│ L2  按需层    docs/ · skills · path-scoped rules         │
│      什么时候：特定目录、特定任务才相关                   │
│      特征：命中才加载，不占常驻 token                     │
└─────────────────────────────────────────────────────────┘
                          ▲ 通过指针引用
┌─────────────────────────────────────────────────────────┐
│ L1  常驻层    AGENTS.md（≤100 行，单一信源）              │
│      什么时候：每个会话、每个 agent 都必须知道             │
│      特征：命令、禁则、指针、完成定义                     │
└─────────────────────────────────────────────────────────┘
                          ▲ 必须与代码一致
┌─────────────────────────────────────────────────────────┐
│ L0  事实层    代码 · 类型 · schema · 测试 · ADR           │
│      什么时候：永远                                       │
│      特征：唯一真相。其他三层都只是它的索引或缓存          │
└─────────────────────────────────────────────────────────┘

判断一条信息该放哪层：三个问题

agent 自己读代码/配置文件能不能推断出来？ 能 → 别写，哪层都别放。（这是砍掉 60% 内容的那个问题）
是不是每个任务都需要？ 是 → L1；只在碰某类文件时需要 → L2。
它会不会过期？ 会 → L2 或 L3，并带上日期和出处；L1 只放几乎不变的东西。

L0 是最容易被忽略的一层

真正的知识库不在 Markdown 里，在代码里：清晰的类型签名、schema、测试、以及记录"为什么"的 ADR。

一个 transformUserProfile(profile: UserProfile): APIResponse 的签名，比十行"请使用强类型"的说明有用。类型系统是唯一不会过期的文档。 与其写"错误处理要统一"，不如把 AppError 的构造函数做对，然后在 AGENTS.md 里写一行指针：错误统一 throw new AppError(code, status, msg)，见 src/errors.ts。

我在下面模板里刻意留了 docs/adr/ 的位置 ------ 决策记录是 agent 唯一无法从代码反推的东西，也是新人（和 AI）最需要的东西。

5. 多 agent 共享：一份源码，多份投影

L1 只有一份，但每个工具要的文件名不同。三种做法：

方案 A：符号链接（最干净，但有平台坑）

Bash 复制代码

ln -s AGENTS.md CLAUDE.md
ln -s AGENTS.md GEMINI.md

改 AGENTS.md，三处自动同步，零重复。

✅ 绝对单一信源，git diff 干净，改一次全生效
❌ Windows 上普通用户创建符号链接需要开发者模式或管理员权限。如果你是 Windows（你确实是），团队成员大概率会卡在这一步。
❌ Claude Code 的 CLAUDE.md 有时需要写它独有的东西（比如 Commands 段），纯软链就没法加

方案 B：生成器（跨平台最稳）

像 AgentSync 这类工具，思路是把指令集中在 .agents/AGENTS.md，apply 一次生成/链接到 30+ 工具的对应位置，还管 skills 和 MCP 配置的同步。

Bash 复制代码

npx @dallay/agentsync init
npx @dallay/agentsync apply
npx @dallay/agentsync status   # 随时验证有没有漂移

✅ 跨平台、可验证、能覆盖 skills/commands/MCP
❌ 多一个 npm 依赖，配置文件本身成为需要维护的东西

方案 C：薄壳 + 导入（我最推荐，零依赖）

主文件就是 AGENTS.md，其他工具的文件只有两三行，做"导入"：

Markdown 复制代码

@AGENTS.md

## Claude 专属
- 需要并行探索时优先用 subagent，别在主上下文里翻 50 个文件。

Markdown 复制代码

@AGENTS.md

✅ 零工具、零权限问题、Windows 直接可用
✅ 允许每个工具加"专属覆盖"，这恰恰是 symlink 做不到的
✅ 导入是引用不是复制，所以不会漂移 ------ 前提是壳文件里绝不复制正文
❌ Codex CLI 不支持 @import（但 Codex 原生读 AGENTS.md，根本不需要壳）

决策建议：

你的情况	选
团队全 macOS/Linux	A（symlink）
有人用 Windows	C（薄壳 + @import）
还管 skills / MCP 配置的同步	B（AgentSync）
只有 Codex + opencode + Claude	C，两个软链都不要

再加一条硬纪律：壳文件里只允许出现 @AGENTS.md 和该工具独有的三五行。任何"为了保险再抄一份"的行为，都是未来的分叉源。 实践中 4--6 周就会出现"为什么 Cursor 这么做、Codex 那么做"，而根因通常是三周前某次随手复制。

6. 写入协议：让记忆不腐烂

多 agent 的失败不是"写得少"，是"写得乱"。同一个仓库有 5 个 agent 往里写，你会在一个上午之内遇到重复、过期、互相矛盾三种问题。

给所有 agent 一套相同的写入纪律（放在 L1 常驻层，所有工具都读到，这是它能生效的前提）：

五条规则

先查后写 ：动手前先读 AGENTS.md 和相关 docs/，避免重新发明已存在的函数、重开已否决的方案。
分类写入 ：一条记录必须能归入 决策 / 事实 / 坑 / 待办 之一。不要写流水账。跑一次长长的 debug 过程的细节，不值得记。
更新而非追加 ：方案变了，改掉旧结论并写上日期，不要只在下面补一段"后来改成 B 了"。只追加不替换的记忆库，真相会被历史埋掉。
必带出处与时效 ：每条形如 [2026-10] 用 S3 直传，不用独立队列服务 ------ 见 docs/adr/0007。没有出处的记忆不可信，没有日期的记忆会毒害未来。
禁止存秘密：token、密码、内部地址一律不入库。共享记忆不是密钥库。

六个已经验证过的失败模式

失败模式	现象	对策
命令漂移（最高发，每周都发生）	有人把 pnpm 换成 bun、挪了脚本，文件还指着旧命令。agent 自信地跑错命令，然后开始 debug 错误的问题	永不复制命令，只链接到 package.json 的 script 名；CI 里加漂移检查
文件腐化	不是突然坏，是缓慢退化。两三周不更新，agent 就开始基于过时假设工作	改构建/测试/约定必须在同一个 PR 里更新 AGENTS.md，PR 模板加勾选项
旧记忆反噬	"我们用 Jest" 熬过了迁移到 Vitest 之后还在推荐 Jest。约 30% 的记忆条目在两周不清理后会过期	定期审计；每条带日期；有 supercede 机制
规则分叉	Cursor 改了规则忘了同步，4--6 周后行为不一致	壳文件保持极薄；同一规则出现两次就是重构信号
加载了但没生效	你以为它读了，其实路径不对/被截断/超过 32 KiB 上限	用工具自带的检查命令验证真的加载了：Claude Code `/memory`、Gemini CLI `/memory show`
记忆风暴	agent 把每个动作都记下来，检索结果被琐事稀释，越记越差	定义有意义的条目类型；要求一句话摘要；宁缺勿滥

第六条的补充：记忆的权威永远低于代码。 记忆是用来指向证据的，不是用来替代证据的。如果一条记忆和当前代码冲突，正确行为是去看代码，然后修掉那条记忆。

7. 治理：靠 CI，不靠自觉

人的自觉在多 agent 场景下必然失效 ------ 因为写文件的不止是人。

三层防线

第一层：PR 时拦截（成本最低，收益最高）

在 CI 里跑一个几十行的检查脚本：

AGENTS.md 里每个 → path 指向的文件是否存在（断链检查）
文件里提到的 pnpm xxx 命令是否在 package.json 的 scripts 里真实存在
是否存在明显的重复（同一行出现在多个工具文件里）
行数是否超阈值（比如 120 行）就报警

这个脚本抓到的过期引用会比你想的多。下面 scripts/ 目录里我放了一个可直接用的版本。

第二层：定期审计（对抗腐化）

每月一次"记忆审计"会话，就干三件事：

逐条问"这条现在还成立吗？"
删掉已经被代码/文档覆盖的（重复就是纯成本）
给没法验证的条目补出处，补不上就删

第三层：遥测（确认真的生效）

不定时用各工具的检查命令确认实际注入内容，而不是相信文件应该被读了：

/memory（Claude Code）、/memory show（Gemini CLI）、agentsync status（AgentSync）。

顺带说一句关于上下文污染的 ：长期会话里的 compaction 是有损的，而且是累积侵蚀 ------ 压缩五轮之后，"绝对不能动 auth 模块"这条约束可能已经隔了三层转述。所以硬约束不要只靠自然语言：该用 hook 的用 hook（Claude Code 的 PreToolUse 可以确定性拦截），该用 CI 的用 CI。指令文件是上下文，不是配置，它没有强制力。

8. 30 天落地路线

阶段	动作	产出
第 1 周：先砍	不要新建文件。先把现有 CLAUDE.md/规则翻出来，逐行问"agent 能不能自己推断出来"，能推断的全删。目标是砍掉一半以上	一份精简后的主文件
第 2 周：立骨架	写 `AGENTS.md`（≤100 行，只放命令/禁则/指针/完成定义）；给每个工具建薄壳；把被砍掉的细节挪进 `docs/` 并加指针	单一信源 + N 个薄壳
第 3 周：上检查	CI 加断链检查和命令漂移检查；PR 模板加"是否更新 AGENTS.md"	自动化防线
第 4 周：定协议	把写入五规则写进 AGENTS.md；如果确实需要跨会话检索，再评估 MCP memory（多数团队这一步可以不做）	团队共识 + 可选 L3

什么时候才该上 L3（MCP memory / 向量检索）？

判断标准很硬：当"重新发现某个事实"的成本已经明显高于维护一个记忆服务的成本时。 具体信号是：工作经常在独立会话/不同工具/不同角色之间交接，且反复重新发现同样的东西。如果仓库和文档已经能回答所有问题，再加一层存储只会增加维护负担 ------ 那些"AI 记忆平台"的营销页不会告诉你这一点。

真要上，按这个顺序挑：要人手可读可 diff → Basic Memory （Markdown + SQLite，Obsidian 友好，AGPL）；要跨框架共享 → mcp-memory-service ；要"事实会随时间变化"的时序语义 → Zep/Graphiti；只想先跑通概念 → 官方 reference memory server。

9. 可直接抄的最小模板

核心是把 AGENTS.md 压到 100 行以内，且只写三样东西：不能推断的命令、不能违反的禁则、指向真相的指针。

Markdown 复制代码

# AGENTS.md

## 这是什么
一句话 + 一句话说明"绝对不能弄坏什么"。

## 命令
- 装依赖 / 开发 / 测试 / typecheck / lint / build（只写非显然的）
- 项目自有工具：`./scripts/xxx`（研究证明这类指令最有效）

## 硬禁则
- 不要动 <目录/文件>，原因：<一句话>
- 不要私自加依赖
- 不要直推 main

## 指针（不要在这里复述内容）
- 架构决策 → `docs/adr/`（每条一个文件，记"为什么"）
- 接口约定 → `docs/api.md`
- 踩过的坑 → `docs/pitfalls.md`（每条带日期）

## 完成定义
`pnpm typecheck && pnpm test && pnpm lint` 全绿，PR 里列出实际运行的检查。

## 记忆纪律
先查后写；分类写入；更新而非追加；必带日期与出处；不存秘密。

就这些。没有架构概览，没有目录树，没有代码风格章节 （风格交给 linter，架构交给 docs/，目录树 agent 自己会看）。

附录多模型协作知识模板：

AGENTS.md

CLAUDE.md

GEMINI.md

需要模板的伙伴可以私信或留言！

感谢阅读！觉得有价值的伙伴，可以关注博主，阅读更新。