深度解读:编码智能体的记忆插件被指解错了题,五项缺陷与文档路线的落地做法

编码智能体每次新开会话都从空白的上下文开始，团队几个月里定下的架构约束与技术决策无法带入新会话。为填补这个缺口，市面上出现了一批给智能体加装跨会话记忆的第三方插件。10 月 3 日，开发者 Kevin Liao 发文指出这类插件解错了题：智能体需要的不是记忆，是文档。

记忆插件的统一架构

开发者 Kevin Liao 把文章《Agents Don't Need Memory. They Need Documentation.》（智能体不需要记忆，需要文档）发布在个人博客 liao.gg 上，10 月 5 日更新。文章在 Hacker News 上引发讨论。

他批评一类第三方产品：记忆插件。这类插件给 Claude Code、Codex 等编码智能体补足跨会话的记忆，让智能体在新会话里仍然知道项目已有的约定。

文章归纳出市面产品的统一架构：插件翻查智能体的会话记录，从中生成 1000 条孤立的记忆片段，插入向量数据库（vector database，把文本转成数值向量、按相似度组织的数据库）；此后每次提交提示词，插件取出与当前输入最相似的五条片段注入上下文；不够用时，再给智能体一个检索工具去搜索库里的内容。这套「存片段、按相似度取回」的做法属于检索增强生成（RAG，retrieval-augmented generation），是各类记忆插件共同的底层方案。部分产品在此之上增加了多层记忆、后台整理进程等能力，作者认为这些增补没有改变底层架构，产品也仍然不能可靠工作。

五项结构性缺陷

文章逐条列出这套架构的五项结构性缺陷：

• 相似度检索判断不了正确性。检索按两条片段在嵌入（embedding，把文本映射为数值向量）空间里的距离排序，从这个排序里看不出哪一条正确、哪一条仍然有效、还缺什么。
• 片段脱离上下文存储。一条检索片段的容量有限，写入时的场景、动机、教训与环境信息都被丢掉。
• 过去被当作真理。这些插件都依赖对过去的召回，而代码库每天都在变；关于认证模块的 500 条旧记忆里还有多少条与现状相符，机制上没有答案。
• 智能体不知道自己不知道。即便配上检索工具，智能体也不清楚自己缺哪方面的知识，因此不会在正确的时机主动发起搜索。
• 存储不可审计。10000 条嵌入放在一个 SQLite 数据库里，哪些存在、哪些过期、哪些从未被检索、哪些有错误并且正在悄然影响智能体的行为，从外部无法查明。

作者认为，五项缺陷出自同一个假设：智能体会遗忘，解法是记住更多、索引更好、检索更聪明。

文档路线与维护规则

文章的替代路线从一个日常观察出发：没有人靠重看三年前的会议录像来回忆某个功能的约束，人们把事情写下来，之后直接使用这些记录（"No one rewatches a team meeting from 3 years ago to remember constraints around a feature. People write things down and use those records instead."）。

作者写道，给智能体的也应当是写下来的记录：一个由指令、规格、调研、映射组成的结构化工作区，开工之前先读，完工之后维护。他认为单个 AGENTS.md（放在仓库根目录、编码工具开工前读取的指令文件）已经承载不了这个职能，只够支撑黑客松级别的演示项目。

对「文档会过时」的常见质疑，文章回应说：过时问题出现在由人主导的项目里，因为写文档对人是一项负担；智能体没有这种负担，可以像对待测试一样读文档、改文档。

作者给出两条规则：文档由正在执行任务的智能体趁上下文完整时写入，不交给后台的整理进程；事实变化时重写原文，不做追加。智能体写文档的最大失败模式是膨胀：不加约束时，智能体会反复概括代码、记录每一次细小改动，把文档写成不可读的长文，因此需要调校过的指令和人工评审来控制。

这条路线出自作者自己的实践。他从 2025 年 8 月起让智能体把规格、计划、索引写进一个 internal/ 文件夹，逐步整理成开源插件 Operator Memory。作者称这款插件不依赖向量数据库、嵌入和后台进程，整体是磁盘上的 Markdown 文件加一份调校过的提示词，支持 Claude Code、Codex、OpenCode、Pi 等工具，知识可以像代码一样进行差异比较、评审和回退。对记忆插件的批评与对自有插件的介绍出现在同一篇文章里。

评论区的落地做法

文章之外，落地经验集中出现在 Hacker News 评论区。

一位评论者给出三份文件的组合做法：用开发者 Matt Pocock 的技能包 mattpocock/skills（一组可安装的指令与流程定义）生成架构决策记录（ADR，Architecture Decision Record，逐条记录「为什么这样决定」的文档）；在 AGENTS.md 里写入指向这些文档的引用；再配一份 CONTRIBUTING.md 记录开发流程、一份 CODING_STANDARDS.md 记录编码规范。按他的说法，再加上 README、架构文档和提交信息，智能体就能找到并使用这些文档，还能让它们保持更新。

另一位评论者提出用写下的原则代替记忆：写下智能体思考时必须遵守的原则，给每条原则加版本号，并要求代码注释引用所依据的原则版本；原则演进时，引用它的代码也要随之重新核对。他说自己使用这套方法约两个月，智能体对规则的遵守程度超出他的预期。这条评论的回复中有人指出，这个做法与现成的指令文件属于同一类方案。

还有一位评论者在个人的中小型项目里维护一份 STATUS.md 作为交接主文档，指示智能体每次会话先读、每次提交后更新，另配路线图、待办清单和多份 ADR，并要求开发新功能时先写 ADR 再写代码。他称在 Claude Code 与 Codex 之间切换智能体时没有遇到交接问题。

反对与保留意见

文档路线在同一个评论区里遇到两类保留意见。

第一类针对知识记录的极限。一位评论者引用了丹麦计算机科学家 Peter Naur 在 1985 年发表的《Programming as Theory Building》（编程作为理论构建）：程序的核心是开发者头脑中形成的理论，仅靠文档无法完整保存这个理论，团队解散时理论随人离开，留下的程序文本不足以重建理论。这位评论者同时提出，智能体的处境与人不同，它的工作上下文必须大量显式化，因此可能催生一种全新形态，用于维护与重建程序模型。他既否定记忆插件，也不认为现有文档已经够用。

第二类来自使用成本。一位为家庭基础设施自建记忆库的评论者警告，数据量一大，读取与更新两头的 token 成本会快速上升，为了保持信息不过期还需要持续整理，小任务的消耗也会跟着膨胀。这位评论者同时表示，一份维护得当的基础设施参考文档跨项目共享时效果很好。

评论区里还有第三种立场：一部分评论者认为代码本身就是文档，提交信息足以记录「为什么」，记忆系统与文档系统都是在增加多余的负担。

事实来源为 Kevin Liao 的个人博客文章（liao.gg，2026 年 10 月 3 日发布、10 月 5 日更新）和 Hacker News 讨论帖（10 月 7 日核对时为 376 分、295 条评论），两处原文均于 10 月 7 日直接打开核对。评论区的落地做法、成本警告与 Naur 引述来自评论者的个人经验与观点，未经独立验证。作者在原文中附上了自己开源的 Operator Memory 插件的链接。Peter Naur《Programming as Theory Building》按公开出版信息记为 1985 年发表。