别再给 Agent 装记忆插件了：一篇檄文说它们全错了，文档才是正解

2026 年 10 月 3 日，工程师 Kevin Liao 在个人博客 liao.gg 上发表了一篇檄文，标题就是论点："Agents Don't Need Memory. They Need Documentation."（Agent 不需要记忆，需要文档。）文章当天冲上 Hacker News 前页，拿下 300 多点赞和一条长长的争论串。

它骂的是一个正当红的品类：Agent 记忆插件。过去一年，每个 coding agent 生态里都长出了一堆"记忆"产品，话术高度统一——"让你的 Agent 记住一切"。Liao 的诊断毫不留情：这个品类解决的是一个错误的问题。

记忆插件的解剖：全是同一套架构

Liao 把市面上的记忆插件扒了个底朝天，发现它们几乎全是同一个架构，只是包装不同：

• 翻你的历史会话转录；
• 切成约 1000 个互不相干的"记忆"片段；
• 做成 embedding，塞进向量数据库；
• 每个 prompt 都检索最相似的 5 个片段，注入上下文；
• Agent 还迷糊？再给它一个搜索工具，让它自己去记忆库里翻。

这就是全部。有些产品加了多层记忆分类、后台"造梦"整理、rerank 重排——Liao 说，这些都是在给一个有结构缺陷的架构打补丁，烧掉的 token 越来越多，可靠性没有本质变化。

核心指控：相似度检索是一台"抽奖机"

为什么说架构错了？关键在检索机制。向量检索按"看起来像"返回文本——一条上周已作废的旧笔记，和今天的正确事实，在向量空间里可能长得一模一样。你的代码库每天都在变，Agent 却可能自信满满地"回忆"起一个上周就过期了的事实。

Liao 的原话很刻薄：你得到的不是记忆，而是一场"基于 RAG 片段的抽奖"（a lottery over RAG snippets），每次 prompt 都指望正确的片段能浮上来。更糟的是，即使抽奖抽中了，Agent 依然不懂你的项目——它只是一堆聊天记录的拼接。

而你真正想要的，从来不是"记得我们聊过什么"的 Agent，而是"懂我的项目"的 Agent：功能在哪、为什么这么做、我们约定过什么、我在乎什么。

开出的药方：文档工作区，而不是记忆库

Liao 的替代方案简单到让人意外：给 Agent 一个可读可写的 Markdown 文档工作区。里面放指令、项目 spec、决策日志、索引、调研笔记。工作循环从"prompt → 构建 → 遗忘"翻转为"prompt → 查阅 → 构建 → 更新"。

开工前，Agent 先读相关文档；收工后，把过时的更新、把新结论写下来。不需要向量数据库，不需要 embedding，不需要 7×24 的后台进程。工作区的每个文档你都能直接打开读、直接改、直接提交、直接分享给队友。

这套方法他自己用了一年多，并把它做成了一个开源插件 Operator Memory：一条 npm 命令安装，支持 Claude Code、Codex、OpenCode 等多个平台。知识分三层：.operator/ 放项目私有知识，.operator-shared/ 放随代码仓库共享的知识，~/.operator/user/ 放跨项目的个人规则。

反方也很强：两个绕不过去的质疑

HN 评论区的高赞质疑值得认真对待。第一，Agent 写的文档很潦草。让 Agent 自己维护文档，三个月后你会得到一堆没人敢删、没人敢信的 Markdown 垃圾。Liao 的隐含前提是"人会 review"，但很多人装记忆插件恰恰是因为懒——指望同一批人去 review 文档，可能是一厢情愿。

第二，"evals or it didn't happen"（没评测就等于没发生）。这是一篇观点檄文，不是受控实验。它没有量化"文档法"比"记忆插件法"少犯多少错。在工程决策上，一篇写得漂亮的文章不等于证据。

这两个质疑都成立。但它们没有杀死这个观点，只是给它加了使用说明：文档法不是"装上就灵"，而是"有人维护才灵"。

为什么 vibe coder 应该认真读这篇

因为你们很多人已经在用"文档法"的雏形了：项目根目录的 CLAUDE.md、AGENTS.md、MEMORY.md。Liao 的文章，是给这个习惯的一篇理论背书——把它从"一条指令文件"升级成"一套文档工作区"。

文档相对记忆插件，有三个结构性好处：第一，可审计。Agent 为什么这么干？去翻文档的 git 历史，一目了然；向量库里的 1000 个片段，你翻一个试试。第二，换模型不丢。文档是模型的无关层，今天用 Claude 明天换 GPT，知识还在；记忆插件的 embedding 和模型/向量库深度绑定。第三，团队可共享。文档能进 git，记忆库进不了。

我的判断是：记忆插件不会消失，但它会退回到它真正擅长的位置——跨会话的个人偏好、模糊的"感觉"。而项目知识这种"对了就是对、错了就是错"的东西，就该放在文档里，用 git 管起来。

今晚就能做的最小实践

不用装任何插件，80% 的收益来自三样东西：

• 在项目里建一个 docs/ 文件夹，放三份文档：ARCHITECTURE.md（架构与关键决策）、DECISIONS.md（决策日志，日期+结论+原因）、CONVENTIONS.md（代码约定）；
• 在 CLAUDE.md / AGENTS.md 里加两行："开工前先读 docs/ 下相关文档；收工后更新过时的文档"；
• 每周花 10 分钟自己 review 一遍 docs/，删掉 Agent 写潦草了的部分——这是你作为"主编"的 10 分钟，比任何插件都值钱。

Liao 的檄文骂的是产品，但真正有价值的是它逼你回答的问题：你的 Agent 的"知识"，到底住在哪里？如果答案是"某个黑盒向量库里"，这篇文章就是写给你的。

记忆派的反击：文档也会过期，凭什么你就不会

公平起见，记忆插件的支持者也有话说，而且不无道理。第一，文档也会过期——Agent 忘更新文档，和记忆库里躺着过期片段，是同一个"人懒"问题的两种症状。把知识从向量库搬到 Markdown，并没有自动解决"谁来维护"的问题，只是把维护动作从"看不见的后台"变成了"看得见的文件"。

第二，记忆插件真正擅长的不是项目知识，而是情景知识：你喜欢用 pnpm 还是 bun、你讨厌某种代码风格、你上周随口说"下次记得先跑测试"。这些碎片不值得写成正式文档，但塞进向量库做模糊召回刚刚好。Liao 骂的是"用记忆插件管项目知识"，但记忆插件厂商卖的一直是"记住你这个人"。

所以更诚实的结论可能是分工：文档管"事实"，记忆管"偏好"。项目架构、决策、约定——写进文档，进 git；个人习惯、模糊偏好——交给记忆插件。拿记忆插件去背架构文档，是用错了工具；反过来，要求文档记住你随口一说的偏好，也是用错了工具。

把三层结构搬进你的 vibe 项目

Operator Memory 的三层目录设计，其实可以直接抄作业，不用装插件：

• 项目层（.operator/ 或 docs/）：这个项目的架构、决策、约定。随项目走，换电脑、换 Agent 都带着。这是最重要的层，也是你今晚就该建的。
• 共享层（.operator-shared/）：进 git 仓库的部分——给协作者（或未来的你）看的。vibe 项目大多是单人，这层可以和项目层合并；但如果你打算开源或找人接手，单独分一层会干净很多。
• 个人层（~/.operator/user/）：跨项目的个人规则，比如"我所有项目都用 pnpm""提交信息用中文""不要给我写 class 组件"。这层不住在项目里，住在你的 home 目录，跟着你走。

三层一分，困扰很多人的问题就消失了："这些规则到底写在哪？"——项目相关的进项目，个人习惯进个人层，公开的进共享层。不再是一团浆糊。

最后说一句大实话：无论你站哪一派，最差的选择是两派都不站——既不用记忆插件，也不写文档，全靠每次重新讲一遍需求。这是大多数 vibe 项目的现状，也是 Agent 反复犯同一个错的根因。Liao 的檄文至少逼你选一边：要么给 Agent 一套它能查的文档，要么承认你享受每次从头讲起。

补充一个冷知识：Liao 在原文评论区承认，这套方法最大的敌人不是技术，而是"写文档这件事本身很无聊"——所以他的插件把"更新文档"做成了 Agent 工作流的默认步骤，而不是靠人的自觉。这恰恰是 vibe coder 该抄的细节：把好习惯做进流程，而不是考验人性。

十月的一个收敛：显式正在战胜隐式

把 Liao 的檄文放进 2026 年 10 月第一周的版面里看，会发现一个有趣的收敛：同一周，HN 前页同时在讨论"给按量计费服务加默认硬预算上限"（花出去的钱要有显式的墙）、"Agent 不需要记忆需要文档"（知识要有显式的文档）、"cloud agent harness 趋势"（执行要有显式的脚手架）。

三件事说的其实是同一句话：Agent 时代，隐式的、黑盒的、"相信我"的东西正在失效，显式的、可审计的、写下来的东西正在升值。账单要显式，知识要显式，执行边界要显式。Liao 的文档工作区，只是这个大趋势在"记忆"这个具体问题上的投影。

对 vibe coder 来说，这个趋势有个极简的行动版本：凡是 Agent 需要知道的东西，问自己一句——它是写下来的吗？需求写下来了，架构写下来了，决策写下来了，预算上限设下来了，你的 Agent 才是一个可预测的 Agent。否则你拥有的不是一个助手，而是一个很聪明、很勤快、但全凭猜测干活的实习生。

这场争论短期内不会有胜负——记忆插件厂商不会认输，文档派也拿不出决定性评测。但方向是清楚的：Agent 的知识管理正在从"黑盒召回"走向"白盒文档"。早一年把文档工作区建起来的人，会在每一次模型换代时都比别人快一步，因为知识从来不住在模型里，住在你写下来的地方。