Agent 不需要记忆，它们需要文档
英文标题：🔶 Agents don't need memory, they need documentation
文章认为，当前多数 AI Agent「记忆」插件本质上都是基于 RAG 的片段检索，无法可靠地让 Agent 理解项目背景、决策和最新状态。作者指出，相似度检索会丢失上下文、将历史误作事实，且其内部向量库难以审计。相比让 Agent 从海量历史对话中回忆信息，更可行的方案是建立可读取、更新、提交和共享的 Markdown 文档工作区。作者据此开发了开源插件 Operator Memory，将 Agent 工作流程从“提示 → 构建 → 遗忘”改为“提示 → 查阅 → 构建 → 更新”。
40.2 KB
114.5 KB
125.1 KB
中文
Agent 不需要记忆，它们需要文档。
一个记忆插件会分析你的对话，为此生成 1,000 条彼此孤立的片段，并将其写入向量数据库。对于你的每一次提示，它都会附加其中最相似的五条片段；如果 Agent 感到困惑——而它确实会困惑——它就会手动搜索更多内容。这就是他们所谓的“记忆”产品。
当你仔细想想自己要解决的问题时，这是一种很奇怪的使用方式。你希望 Agent 理解你的项目：知道某项功能位于何处、为何被构建、你们达成了什么共识，以及你重视什么。结果得到的却是一场针对 RAG 片段的抽奖：每次提示都注入一些片段，期待正确的信息能够浮现。
即使它确实奏效，Agent 依然没有真正理解你的项目。整个记忆插件生态系统都在解决错误的问题。
因为 Agent 不需要记忆。它们需要文档。
这终究只是 RAG
市面上的每一个记忆插件，其工作方式都相同：
- 遍历会话记录
- 生成“记忆”片段
- 写入 RAG 数据库
- 在每次提示时，检索排名前 5 的内容并注入
- 还需要更多？给 Agent 一个搜索 RAG 数据库的工具
这就是完整的架构。有些工具会做得格外花哨：它们让 Agent 能够逐字搜索过去的会话记录；或者实现某种多层级记忆系统，对短期和长期记忆进行分类；又或者添加一堆后台守护进程，用于审阅、合并或去重记忆。“Dreamers” 会在夜间重写记忆，此外还有持续上下文压缩、重排序器等等。
每个插件都试图加入新的、消耗 token 的“功能”，来修补同一套存在缺陷的底层架构。这也正是它们没有一个能够稳定工作的原因。
回忆的问题
所有这些记忆插件都面临同一组广泛的问题。
- 记忆通过相似度被呈现。 相似度搜索只会对两个片段在嵌入空间中的接近程度进行排序，仅此而已。你无法知道哪些内容是正确的、最新的，或缺少了什么。
- 记忆脱离上下文存储。 一个 RAG 片段能够容纳的信息有限。其余一切都会丢失：上下文、动机、经验、环境以及更多内容。
- 过去被当作真相。 这些插件全都依赖回忆，无论是搜索会话记录还是向量数据库。但代码库每天都在变化；那么，关于认证的 500 条片段里，每一条究竟有多准确？
- Agent 无法搜索自己不知道的事。 即便你确实向 Agent 提供了搜索工具，Agent 又如何知道该在何时使用它？Agent 不知道自己不知道什么。
- 存储库无法审计。 SQLite 中有 10,000 个 embedding。究竟存在哪些记忆？哪些已经过期？哪些从未被检索？哪些是错误的，并在暗中影响 Agent 的工作方式？
这只是记忆插件所面对、试图解决却始终失败的众多问题中的五个，因为它们全都做出了同一个假设：
Agent 会遗忘：这才是问题。因此，解决办法是记住。为了记得更好，我们应当捕获更多信息、更好地建立索引、更智能地检索。
它们的整套论点都围绕着捕获和回忆过去展开。但其他人并不是这样处理知识的。没有人会重看三年前的团队会议录像，来回忆某项功能的约束条件。人们会把事情写下来，并使用这些记录。
同样，解决方案不是给 Agent 一个搜索工具，让它在价值 1,000 万 token 的历史对话中搜索，重新拼凑曾经发生过的事情。
解决方案是基于文档的记忆。
如今，人们借助 AI 以光速批量产出产品、功能和垃圾内容，却不阅读或理解任何一行代码。在这种情况下，很容易理解为什么文档会沦为事后补充；但实际上，它现在应当比以往任何时候都更重要。
文档优先于回忆
人们早已知道 Agent 需要上下文。这就是他们发明 AGENTS.md 文件的原因：避免 Agent 在不了解情况时直接闯入代码库。这种方式有效。但很多时候，这一个文件就是项目拥有的唯一文档。
单个文件并不够。Agent 需要完整的大脑：一个结构化工作区，让它无需被要求即可记录指令、规格、决策、研究、索引以及其他任何内容。它可以记录代码审查流程的操作说明、详细记录与用户讨论结果的规格说明，以及针对陌生库或 API 可复用的研究资料。
当 Agent 工作时，它可以从这个大脑中读取文件，以获得相关且完整的上下文。工作完成后，在完整信息仍处于上下文中时，它会更新过时内容，并在必要时新增文档。这样一来，Agent 工作循环就从 提示 → 构建 → 遗忘 转变为 提示 → 查阅 → 构建 → 更新。记忆不再是你附加给 Agent 的 RAG 数据库，而会成为一个你可以读取、更新，甚至与他人共享的工作区。
接受测试
一年多前，当我刚开始使用 AI 编程时，我就意识到了这个问题。我想让 Agent 能够跨会话记住工作内容，因此一开始我创建了一个 internal/ 文件夹，要求 Agent 将所有内容写下来：规格、计划、索引。我要求 Agent 在工作前始终阅读相应文档和索引，并在工作后进行更新。
这些初步指令逐渐演变成了一套正式系统，继而成为名为 Operator Memory 的插件。我一直在自己的所有项目中经常使用它。
Operator Memory 使用上述模型提供基于文档的记忆。Operator 为你的 Agent 提供一个 Markdown 大脑，使其能够持久保存重要知识：指令、规格、研究和索引。在工作前，Agent 始终会查阅大脑中的相关文档；在工作后，Agent 会更新这个大脑，重新审阅过时文档，并在缺少文档时补充新文档。
没有向量数据库。没有 embedding。没有摘要器、整理器、更新器、Dreamers，或任何其他消耗 token 的后台守护进程。没有黑盒检索。
在 Operator 中，一切都是纯 Markdown 文档，你可以读取、更新、提交，并与团队共享。我已经使用这套系统一年多了。如果你想尝试，它是免费且开源的：https://github.com/aerovato/operator-memory
English / 原文
Agents Don’t Need Memory. They Need Documentation.
A memory plugin analyzes your conversations. It generates 1,000 isolated snippets and inserts them into a vector database. With your every prompt, it attaches the five most similar snippets; if the agent is confused (which it is), it manually searches for more. That’s the product they call “memory.”
It’s a strange thing to use when you think about what problem you’re trying to solve. You want your agent to understand your project. To know where a feature is, why it was built, what you agreed on and what you care about. Instead, you get a lottery over RAG snippets, injected on every prompt, hoping the right ones float up.
Even when it does work, the agent still doesn’t understand your project. The entire memory plugin ecosystem is solving the wrong problem.
Because agents don’t need memory. They need documentation.
It’s All Just RAG
Every memory plugin on the market works the same way:
- Go through session transcripts
- Generate snippets of “memories”
- Insert into a RAG database
- On every prompt, retrieve the top 5 and inject
- Need more? Give the agents a tool to search through the RAG database
That’s the whole architecture. Some tools are extra fancy; they let the agent search through past transcripts word for word. Or they implement some kind of multi-tier memory system that classifies short or long-term memory. Or they add a bunch of background daemons to review, merge, or deduplicate memories. “Dreamers” that rewrite memories overnight. Continuous context compression. Rerankers. Et cetera.
Each plugin tries to add new token-burning “features” to fix the same flawed architecture underneath. And that’s why none of them reliably work.
The Problem with Recall
All of these memory plugins suffer from the same broad set of problems.
- Memories are surfaced by similarity. Similarity search ranks how close two snippets are in embedding space. That’s it. You don’t know which is correct, current, or what’s missing.
- Memories are stored without context. A RAG snippet can only contain so much. You lose everything else: context, motivations, lessons, environment, and more.
- The past is treated as truth. All of these plugins rely on recall; whether it’s search through transcripts or a vector database. But the codebase changes everyday; so how accurate are each of the 500 snippets about authentication?
- Agents can’t search for what they don’t know. Even if you do expose a search tool to the agent, how would the agent know when to use it? The agent doesn’t know what it doesn’t know.
- The store is unauditable. There are 10,000 embeddings in SQLite. Which memories exist? Which are stale? Which have never been retrieved? Which are incorrect and secretly affecting the way your agent works?
These are only five of the many problems that memory plugins face, attempt, and fail to fix, because they all make the same assumption:
Agents forget: that’s the problem. So the fix is to remember. To remember better, we should capture more, index better, retrieve smarter.
Their entire thesis revolves around capturing and recalling the past. But that’s not how anyone else handles knowledge. 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.
Similarly, the solution is NOT to give an agent a search tool that it uses to search over the past 10 million tokens worth of conversations, reconstructing fragments of what happens.
The solution, is document-based memory.
Today, people use AI to pump out products, features, and slop at the speed of light, all without reading or understanding a single line of code. Under these circumstances, it’s easy to see how documentation ends up becoming an afterthought when it should be more important than ever.
Documentation Over Recall
People already knew agents needed context. That’s why they invented AGENTS.md files: so agents don’t jump into a codebase blind. It works. But oftentimes, that single file is the ONLY documentation that the project has.
A single file is not enough. The agent needs an entire brain, a structured workspace where it can record instructions, specs, decisions, research, indexes, anything without being asked. Instructions for how the code review process works, specs detailing what was discussed with the user, reusable research into a foreign library or API.
When the agent works, the agent can read files from the brain to gain relevant and complete context. After the agent works, it updates what’s outdated, adding new documents where necessary, while the full picture is still in context. In this way, the agentic loop changes from prompt → build → forget to prompt → consult → build → update. Memory turns from a RAG database you bolt onto the agent into a workspace you can read, update, and even share.
Putting It to the Test
I recognized this problem over a year ago when I first started programming with AI. I wanted a way for an agent to remember work across sessions, so I started by creating an internal/ folder where I asked the agent to write everything down: specs, plans, indexes. I tasked the agent with always reading the appropriate documents and index before doing work and updating afterwards.
This set of rudimentary instructions slowly transformed into a formal system, and then into a plugin called Operator Memory that I’ve been using regularly within all of my projects.
Operator Memory provides document-based memory using the model described above. Operator provides your agent with a Markdown brain where it can persist important knowledge: instructions, specs, research, indexes. Before working, the agent always consults the brain for relevant documents. After working, the agent updates the brain; revisiting stale documents, adding documents where missing.
No vector databases. No embeddings. No summarizers, curators, updaters, dreamers, or any other token-burning background daemon. No black-box retrieval.
With Operator, everything is a plain Markdown document that you can read, update, commit, and share with your team. I’ve been using this system for over a year. If you want to try it out, it’s free and open source: https://github.com/aerovato/operator-memory