CLAUDE.md 不是记忆：团队 Agent 记忆为何失效

为什么「我们已经有 Agent 记忆了」是个错觉

很多团队会说：「我们已经有 agent memory 了。」Claude Code 有 memory 层，Cursor 有 rules，Codex 读 AGENTS.md，大多数团队维护一个由 agent 自行更新的 CLAUDE.md。底层机制其实一样：被加载进上下文的 markdown 文件。

这是一个合理的起点，但把它当记忆用并不成立——甚至对单个开发者也是如此，到了团队层面更是裂缝尽显。

Agent memory（智能体记忆） 在业界并没有统一定义，但通常指 agent 能够跨会话持久保留、按需检索并复用过去信息的能力。它至少包含三个层次：存储（信息写在哪里）、召回（在需要时如何找到相关信息）、遗忘/修剪（如何淘汰过期内容）。当前主流工具（Claude Code、Cursor、Codex）提供的所谓 memory，本质上都属于「存储」层——把 markdown 文件在会话开始时全量塞进上下文窗口（context window）。这既不涉及语义搜索，也没有相关性排序，更没有自动淘汰机制。因此把它们称作「记忆」容易让人误以为已经解决了问题，实际上只是解决了「持久化」，而召回和修剪仍然完全依赖人工。理解这一区分，是判断后文各类团队故障的前提。

单人场景下就已经崩了

先不谈团队，只看你一个人和 agent 几个月的相处：

• 文件膨胀，但每次会话都会全量加载。 每一行都消耗上下文，不管它跟今天的任务有没有关系。噪音变多，留给关键代码的空间变少，你真正需要的那一行被埋掉了。
• 没有搜索和召回，只有一个大 blob。 真正的记忆允许你问「我以前见过这个吗？」而 markdown 文件要么从头读到尾，要么完全不读。
• 过去的排查和死胡同消失了。 你的 agent 上个月花了一小时排除了连接池的嫌疑，这件事很少被写进文件，下次它还会重新排除一遍。
• 切换工具会撕裂记忆。 早上用 Claude Code，下午用 Cursor，临时修个 bug 用 Codex——三个工具、三个记忆孤岛，而且是一个人。它们彼此不知道对方学到了什么。
• 过期条目会静默误导。 文件里写着「使用 v2 client」，但 v2 client 在六月就被移除了。agent 信任文件，因为这正是文件的用途。

把这些乘以团队人数，问题会被进一步放大。

上下文窗口（context window） 是 LLM 单次推理能处理的最大 token 数量，包括系统提示、记忆文件、对话历史和当前任务代码。它是一块固定预算，任何一部分占用过多，其他部分就被挤压。记忆文件每行都在消耗这块预算，而且是被无条件加载——不管今天任务是否相关。当文件膨胀到上千行，模型在长上下文中对中段信息的注意力会显著下降（业界常称为「lost in the middle」现象），导致真正关键的那一行反而被忽略。这也是为什么「全量加载的 markdown」在机制上无法替代「按需召回的记忆」：前者是固定成本，后者才随相关性伸缩。

场景一：队友早已解决的 bug

周二下午，Ana 用 Claude Code 花了两小时追一个不稳定的 checkout 测试。根因是测试 fixture 里的时区默认值，且只在 UTC 22:00 之后才触发。她的 agent 在本地记忆里记了一笔，她在自己的分支上修复了 fixture。

周三早上，Ben 在 billing job 里遇到一个看起来不同的失败。同样的根因。他的 Cursor 会话完全不知道 Ana 的 agent 昨天学到了什么。它从零开始，读同样的文件，形成同样错误的假设，90 分钟后才找到答案。

那句原本能救下他的话，是人类队友经常说的：「等等，Ana 昨天好像看过类似的东西，让我看看是不是同一个根因。」

按开发者隔离的记忆说不出这句话。知识就在那里，只是长在了错误的脑袋里。

场景二：吃掉上下文窗口的文件

为了修复场景一，团队把记忆文件提交到仓库。现在所有人的 agent 都往同一个 CLAUDE.md 里写。三个月后：

• 它有 1400 行
• 一半在描述已经不存在的代码
• 两个段落互相矛盾（「始终使用 v2 client」 vs「v2 client 已废弃，请使用 SDK」）
• 每次会话都要烧掉一块上下文来加载它，而 agent 仍然错过关键的那一行

记忆文件只会增长。Agent 非常擅长追加，却极不擅长删除，因为删除需要对「什么仍然为真」做判断。没人负责修剪，于是没人修剪。

场景三：Agent 大脑里的合并冲突

四个开发者，每人跑一个「乐于助人」地更新 AGENTS.md 的 agent。每个 PR 都会碰到同一个文件。你会得到没人愿意认真解决的冲突，于是大家两边都接受，矛盾不断堆积。或者只接受自己那边，别人辛苦得来的教训悄悄消失。

代码有 review。记忆文件大多没有，因为它们感觉像笔记，不像代码。但它们塑造着 agent 写下的每一行。

记忆文件的合并冲突 之所以比代码冲突更难处理，是因为它缺少代码那样的「可执行验证」。代码冲突解决错了，测试会失败；记忆文件冲突解决错了，没有任何自动化信号告诉你哪一条是对的。更麻烦的是，记忆条目往往是自然语言的经验总结，两条看似矛盾的建议可能各自在特定条件下成立，但文件里丢失了条件。团队常用的「两边都接受」策略会制造出一个自相矛盾的指令集，让 agent 在运行时随机选择，行为变得不可预测。要缓解这一点，需要把记忆条目结构化（带上日期、适用条件、可废止标记），并像代码一样要求 review 和测试——例如用「一个新 agent 能否据此做出正确决策」作为回归测试。

场景四：只有规则，没有理由

看一个典型的记忆文件，你会看到大量规则、极少推理：

- Don't use Redis for the job queue
- Keep retries at 3

为什么不用 Redis？是成本、运维负担、一次事故，还是客户要求？这个理由现在还成立吗？只看到规则的 agent 要么盲目遵守，要么更糟——当它在上下文里觉得不对劲时「改进」掉这条规则。新队友也无法挑战它，因为推理已经丢了。

规则告诉 agent what。决策需要 why，而 why 正是 .md 文件最容易丢失的东西。

场景五：有人轮岗走了

Chen 转到另一个项目。他本地的 agent 记忆——八个月的「这个服务在状态码上撒谎」「staging DB 与 QA 共用，不要 truncate」——随他一起走了。它从未进过仓库，只是在他人笔记本的 ~/.claude 里。

在人类团队里我们称之为 bus factor 问题。有了 agent 也是同样的问题，只是更安静，因为在 agent 自信地重复 Chen 的 agent 早已学会避免的错误之前，没人会注意到。

如果还要用文件，至少做到这些

如果目前你手上的就是 .md 文件，下面是让它少疼一点的做法，单人团队都适用，本周就能开始。

1. CLAUDE.md / AGENTS.md 只放规则

短、稳定、命令式。构建命令、约定、硬性的「绝不做 X」。目标是人类两分钟能读完。如果超过约 200 行，它就在承担太多职责了。

2. 把决策连同理由记录到单独的文件

用 docs/decisions/ 文件夹，每个决策一个小而带日期的文件：

# 2026-09-14: No Redis for the job queue
Context: we run on a single managed Postgres, no ops person.
Decision: use Postgres SKIP LOCKED queue.
Why: one less service to run; volume is ~2k jobs/day.
Revisit if: volume > 50k/day or we hire ops.

然后从规则文件链接过去：「Job queue: Postgres, see docs/decisions/2026-09-14」。你的 agent 可以廉价地拿到规则，在需要时读到理由。「Revisit if」这一行正是阻止未来 agent 盲目遵守或盲目撤销它的关键。

3. 写下排查过程，而不只是修复

当一次 agent 会话找到了非显而易见的根因，让它写 5 行笔记：症状、根因、如何确认、修复、位置。把这些放到共享且可搜索的地方（docs/investigations/ 文件夹就够用）。然后在 CLAUDE.md 加一条规则：

Before debugging, search docs/investigations for similar symptoms.

这一行就能带来相当可观的「队友昨天好像看过这个」的效果。

4. 让 agent 对记忆文件的修改走 review

把规则文件的变更当作代码对待：小 diff、一个 reviewer、PR 里写明理由。如果 agent 提议修改记忆，让它提议，而不是直接提交。

5. 定期修剪

每月一次，由某个人（或一个有人类把关的 agent）过一遍规则文件，对每一行问：这仍然为真吗？删掉我们会想念它吗？激进地删除。过期的记忆比没有记忆更糟，因为 agent 信任它。

6. 为下一个人写记忆，而不是为自己

一个好的测试：一个新队友的 agent 在第一天，会因为这条笔记做出更好的决策吗？如果这条笔记只有在你自己的上下文里才说得通，它就该待在你脑子里，而不是共享记忆里。

真正的缺口

按开发者隔离的 .md 记忆解决了「我的 agent 忘了我告诉它的东西」。这是一个真实的问题，现在的工具处理得不错。

团队接下来碰到的是另一个问题：我的 agent 不知道队友的 agent 学到了什么。 不同的工具、不同的笔记本、不同的会话，同一个代码库。上面的建议能让文件少疼一点，但它们仍然是文件：没有召回、没有搜索、每个工具一个大 blob。真正的记忆应该让任何 agent——你的或队友的——都能问「我们以前见过这个吗？」并得到答案。

你的团队是怎么处理的？还在用文件，还是已经换成了别的东西？我很想听听什么方法真的有效。

原文作者正在构建一个面向 agent 的共享团队记忆开源方案：palacememory.com（GitHub）。

跨开发者共享记忆 与「个人记忆文件同步到 Git」是两回事。后者只是让所有人看到同一份 blob，仍然没有检索能力；前者要求一个可查询的记忆层：能按语义或关键词搜索、能返回相关片段而非全文、能标注来源和时效、能支持多个 agent 并发写入而不冲突。这类系统通常需要向量检索、结构化元数据、写入冲突消解和权限控制。它解决的核心问题正是文章反复提到的「我们以前见过这个吗」——一次跨人、跨工具、跨会话的召回请求。这也是当前各类 .md 方案与真正团队记忆之间最本质的差距：不是存储位置，而是召回接口。