智能体不需要记忆:AGENTS.md 文档优先

同一周，两个信号在开发者时间线上撞在一起：GitHub Trending 上 claude-mem 冲到 9.6 万星，一个把编码 Agent 每步都记下来的持久记忆插件；另一边 Hacker News 有篇帖子《Agents Don't Need Memory. They Need Documentation》爬到 368 分，主张记忆系统从根上就是错的。一个拼命给 Agent 装记忆，一个说记忆根本是伪需求、该写文档——你到底该信谁？这篇文章不站队喊口号，而是把这场架构之争拆开，给你一个能落地的判断框架。值得较真，是因为记忆正是当下 Agent 生态的投资热点：Anthropic 给旗下 Agent 全线内置记忆，围绕"嵌入检索"的创业公司接连融资，而 Liao 的反对直指这套范式最根本的缺陷——向量搜索只适合"事件类事实"的检索，处理不了 Agent 在代码库里真正需要的"操作类知识"。

记忆插件到底错在哪

开发者 Kevin Liao 那篇引爆 HN 的 essay，论点很具体：市面上的记忆插件走的是同一条架构——把会话记录切片、嵌进向量数据库、每轮把最相似的几条注入 prompt。他管这叫"在一堆 RAG 碎片上抽奖"。更深的区分在于：RAG 式记忆适合"发生了什么"这类 episodic 事实，但 Agent 在代码库里真正需要的，是"这套系统怎么运作"的操作类知识——后者靠召回是召回不出来的，只能靠人去沉淀。真正的失败模式有四条。第一，相似度只回答"哪条离得近"，不回答"哪条是对的、当下的"；一次重构之后，旧架构的片段照样被自信地召回。第二，过去被当成真理——记忆系统把旧上下文当现状喂给 Agent，于是它用昨天的架构答今天的活。第三，Agent 不知道自己不知道，检索工具只在它意识到该查时才触发，这个缺口谁都补不上。第四，整库不可审计：Agent 重复犯错时，你追不出是哪条记忆导致的。

文档优先是怎么做的

Liao 给的替代方案是"文档优先"（documentation-first）：与其建向量记忆库，不如让 Agent 维护一份结构化的 Markdown"大脑"，分成 Instructions（该怎么做）、Specs（规范）、Research（调研）、Indexes（索引）。关键是把记忆维护从后台的猜测行为，变成 Agent 工作循环里的显式步骤——工作前先读这些文件，工作后显式更新相关文档，再把改动提交进 Git。这样做的好处是文档可被审阅、可版本化、可 diff、可团队共享，而且永远不会像记忆那样"悄悄给你一段过时的上下文"。他已经把这个思路做成开源插件 Operator Memory，不依赖向量库、不产生嵌入计算。社区里把这套思路说得更绝的是 James Long 那句：AGENTS.md 不是记忆，是文档——区别在于文档是被刻意加载、被有意组织、永远不会拿一段你早忘了的会话来吓你一跳。它和 claude-mem 解决的是同一个"Agent 跨会话忘掉项目约定"的问题，只是没用数据库、没用嵌入、没在每次检索上烧 token。

我的判断：不是二选一，是分层

把两边的说法都看完，我的结论不是"记忆已死"，而是"它们解决的是不同层的问题"。关于智能体记忆怎么选，答案不是二选一，而是把事实放进对的层：稳定且新人必读的东西（架构、安装、接口、不变式）属于文档，进 Git、经 review；真正动态的那些（用户偏好、本周的环境怪癖、试过又放弃的方案）才属于记忆，而且最好是本地、零 token、可审计的那一类。研究数据也支持"少写废话"：给 Agent 灌完整对话历史，会让 p95 延迟涨约 91%、token 成本涨 90% 以上；而一份结构化的 context 文件能把中位运行时间压 29%、输出 token 减 17%。更说明问题的是，AGENTS.md 这种极简文档格式已经被 6 万多个开源项目采用，Codex CLI、Copilot CLI、Gemini CLI、Cursor 和 Claude Code 全都认它——它几乎成了 Agent 生态里最接近"共享标准"的东西。也别把文档优先理解成"彻底不要记忆"——当 Agent 每天服务同一个用户，记"他偏好简洁草稿、总要把测试文件一起提交"这类个性化、跨会话的状态，记忆比文档更合适；它该是文档这层地基之上的补充，而不是先于文档去扛流程设计。

AGENTS.md 怎么写才有效

AGENTS.md 怎么写，关键是"为行动写"而不是"为入职写"。人类文档常是 onboarding 散文，Agent 文档要的是任务形状的上下文：给智能体写文档，一份编码 Agent 的文档该放 repo map、安装步骤、测试命令、风格规则、常见失败模式、以及被接受 patch 的样例；一份运营 Agent 的文档，该放升级规则、工具权限、数据处理规则、检查清单。每条都要回答 Agent 本来会去猜的那个问题，并且有人维护——没人维护，Agent 就会漂。落地时有个很实用的顺序：先给岗位写一页操作手册，拿十个真实任务跑一遍，看哪些真改善了；只把"不改就会出错"的记忆加上去，其余留在文档和 transcripts 里。

两个容易踩的坑

给智能体走文档优先，也有自己的陷阱。一是文档会过时——它从写下的那天就开始贬值，而没有任何机制强制更新，所以得有人 owning，不能丢进一个巨文件就完事。二是别听信"代码即文档"的极端：有评论说"README.md + 每个子目录的 CLAUDE.md，指向它就行"，这话对简单项目成立，对复杂系统就太天真——Agent 要的是被显式写下的规则、边界和样例，不是让它自己读源码猜。还有个反直觉的研究：让 LLM 自动生成 context 文件，反而让 Agent 性能降约 3%、成本涨 20% 到 23%；起作用的是"人写、精简"的那类，质量才是变量。

一句话原则

给智能体加能力时，默认从文档开始，而不是从记忆开始。先把稳定真相写进 AGENTS.md 并经 review，再用本地、零 token 的记忆补那些个性化、动态的状态。下次谁再跟你说"智能体健忘是核心问题，得装个记忆系统"，先反问一句：你那件活，是真的缺记忆，还是只是没写进文档？

参考来源

     1. Agents Don't Need Memory, They Need Documentation（Kevin Liao, 2026-10-03）— https://getaibook.com/news/agents-dont-need-memory-they-need-documentation     2. Agent Memory vs Documentation: What the HN Debate Gets Wrong（codecora）— https://blog.codecora.dev/agent-memory-vs-documentation-hn-debate     3. Agent memory is not a substitute for readable docs（Ken Ashe）— https://kenashe.ai/blog/2026-10-04-agent-memory-is-not-a-substitute-for-readable-docs     4. Agents Don't Need Memory, They Need Docs（AgentConn）— https://agentconn.com/blog/agents-need-documentation-not-memory