为什么你的文档无法作为记忆发挥作用
文档回答“这是什么”，记忆回答“我该怎么做”
几乎所有的内部文档都是描述性的。它解释系统、梳理设计、列出考虑过的选项。对于加入团队的新人来说，这是合适的语调，因为人类会阅读上下文段落并推导出规则。
智能体需要明确陈述的规则。一份 12 页的设计文档中，最有价值的句子往往只有一行——“重试逻辑必须是幂等的，因为上游在超时时会发送重复数据”——而且它被埋在关于其他内容的章节中间。检索可能会返回该页面，但不一定会返回那一行，即使返回了，模型也必须猜测该段落是当前的约束条件还是历史考量。
检索给你的是段落，而段落往往含糊其辞
即使是经过精心调优的检索设置也有其局限性。OpenAI 自身对索引知识源的描述指出，它们“最初设计为最适合问答和搜索相关的查询”，并且“根据查询意图将最相关的数据发送给模型，这限制了在需要聚合多个来源或进行非常复杂查询的场景中的性能”。
这是对文档检索用途的客观描述。你的问题——“关于 X 我们做出了什么决定？”——通常是一个聚合问题，散落在会议记录、文档修订和 PR 评论中。检索能找到文档，但无法得出结论。这种区别正是为什么 RAG 不是记忆的全部主题。
文档中没有任何内容能告诉你它是否仍然有效
页面有一个最后编辑的时间戳，它只能告诉你有人在什么时候修改过它，而不能告诉你其中的主张是否依然成立。文档是逐条失效的：三个段落保持正确，一个段落在迁移后默默变得不再适用，而且由于没有人会重新阅读整个页面，因此永远不会进行编辑。
对于人类来说，这是可以应付的——你会注意到过时文档的语气。但对于智能体来说，它与当前的事实无法区分，智能体会据此采取行动。这就是为什么对于记忆而言，出处比文档更重要的原因，记忆出处详解中讨论了这一点。
而且你无法通过将文档加载到上下文中来解决这个问题
显而易见的解决方法——将文档放入常驻的指令文件中——与每个厂商发布的指南相冲突。Claude Code 建议每个 CLAUDE.md 文件控制在 200 行以内，并指出较长的文件会“消耗更多上下文并降低遵循度”。Cursor 建议将规则保持在 500 行以内。而且 Claude Code 明确指出，将内容拆分为 @path 导入“有助于组织，但不会减少上下文，因为导入的文件在启动时就会加载”——因此导入技巧并不能为你争取空间。
除了大小之外，还有第二种成本。Claude Code 的文档警告说，“如果两条规则相互矛盾，Claude 可能会任意选择一条”。将五个在不同时间编写的文档塞进同一个上下文中，是制造矛盾的可靠方法。
人们的尝试
将智能体指向文档文件夹。 当答案位于某个特定文件中且你知道是哪一个时，这种方法有效。但在你最关心的问题上它会失效，因为这些答案要么散落在多个文件中，要么根本就没有记录下来。
一个巨大的 `CONTEXT.md`。 这是最常见的尝试。它会增长到 800 行，在每次请求时被加载，包含三个矛盾，并且由于与参考资料竞争，对重要规则的遵循度会下降。
将所有内容索引到向量数据库中。 适用于寻找源材料，但无法替代结论。你会找回设计文档，但你仍然无法得知该设计已被废弃。
让智能体总结文档。 这很有诱惑力，它会生成一个看似合理的总结，但恰恰抹平了你所需要的区别——当前与历史、已决定与已考虑、规则与示例。
将文档复制到助手的记忆中。 方向更好，但粒度不对。粘贴的页面会变成一个庞大的记忆条目，在任何情况下都会被检索到，但对任何事情都没有帮助。
什么都不做，每次都重新解释。 这是现状，其成本很容易被低估——你在每条消息上都要永远为此付出 token 和注意力的代价。这就是停止向你的 AI 重新解释上下文所要解决的习惯问题。
解决方法：提取主张，而非文档
这种转化不是导入工作。它是一项阅读工作，具有特定的输出格式：每个条目一条主张，以指令或事实的形式陈述，并附带原因。 针对你的核心文档做一次，其余的就会在你的工作过程中自然累积。
在开始具体操作之前，先进行分类。将文档中的所有内容分成四堆：
提升为记忆。 决定及其原因。从外部看显得随意的约束条件。与工具默认设置不同的规范。历经坎坷才学到的教训。被否决的方案——你尝试过并放弃了什么，以及为什么。这些内容简短、持久，正是智能体无法从代码库中推断出来的材料。
保留为文档，并进行引用。 冗长的步骤、参考表、API 接口描述，以及任何包含多个步骤的内容。这些应该留在文件中；如果你的工具支持按需包（在大多数当前工具中称为技能），那就是它们的归宿，这样它们只在相关时加载，而不是一直加载。
删除。 任何描述你已不再运行的系统的东西。这占了大多数文档文件夹的三分之一，而且是风险最高的三分之一，因为它们读起来很有权威性。
询问相关人员。 你在做这件事时会发现一些空白：那些没有人记录下来的决定。趁现在注意到了，把它们写下来。
然后是设置，分为三个步骤。
步骤 1：创建 API 密钥
登录 MemoryLake 并创建 API 密钥。这是你的智能体用于读取和写入记忆的凭证，与你使用哪种助手无关——因此，即使你下次更换工具，这种转化依然有效。
步骤 2：上传你的第一批记忆
处理“提升为记忆”那一堆内容，并将每个项目写成一个独立的条目。以下四个规则决定了它是成为记忆层，还是仅仅成为第二个文档文件夹：
每个条目一条主张。 如果包含两个想法，请将其拆分。只有一个想法的条目检索更精准，且更容易看出是否过时。
先陈述规则，再陈述原因。 “重试必须是幂等的——上游在超时时会发送重复数据。”原因可以防止人类或模型在第一次觉得不方便时就推翻这条规则。
使其可验证。 “API 处理器位于 src/api/handlers/” 优于 “保持代码整洁”。模型可以针对前者采取行动，而无法针对后者。
明确记录被否决的方案。 “已考虑并否决：基于队列的排序，2026 年 3 月——排序保证在重试时失效。”如果没有这个，每个新智能体都会热情地重新提出它，而你又得从头开始解释。
转化率可能会让你感到惊讶：一份 12 页的架构文档通常只会产生 6 到 10 个条目。这并不是损失——另外 11 页是模型不需要的解释，或者是已经不再真实的过去历史。
步骤 3：连接你的 AI 和智能体
连接你的工具。MemoryLake 可以通过 MCP 和 API 访问，因此支持 MCP 的原生智能体（包括 Claude Code、Codex 和 OpenClaw）可以通过指向 MCP 服务器进行连接，而其他助手则可以通过 API 读取相同的记忆。你的指令文件可以保持简短并专注于其狭窄的任务；提取出的主张变得可查询，因此智能体可以获取 4 个相关的条目，而不是 12 页文档或一无所有。
两个客观的局限性。这不会替你阅读文档——提取是一项判断性工作，由了解哪些主张仍然有效的人一次性完成。而且它不是一个强制执行层：无论模型如何决定都必须遵守的规则应该放在钩子（hook）或 CI 检查中，而不是放在记忆中。
这在实践中带来了什么改变
问题得到的是答案，而不是来源。 “关于账本模式我们做出了什么决定？”返回的是决定，而不是提到该模式的三份文档。
过时的知识变得显而易见。 一个简短的带日期主张列表是可以被审查的。而一个文档文件夹则不行——没有人会为了检查第九段而重新阅读一份 12 页的文档。
每次请求的 Token 成本都会下降。 指令文件缩小，粘贴的上下文消失，检索发送的是几百个 token 而不是几千个。具体的计算见记忆如何降低 token 成本。
文档能更好地发挥文档的作用。 一旦主张存在于其他地方，文档就可以是叙述性的、详尽的，而不需要假装是一套规则。通过互不竞争，这两种产物都得到了提升。
新智能体从一开始就知情。 这正是本实践的意义所在。无论你接下来采用什么工具，它在第一天就能读取提取出的主张，而不是通过反复试验来重新了解你的项目。
最佳实践：本周即可执行的转化方案
从人们引用最多的三份文档开始。 不是最大的文档——而是当新人提问时，有人在 Slack 中链接的那几份。这些文档包含最高密度的核心主张。
边读边提取，而不是读完之后再提取。 保持一个草稿文件打开，在发现主张的瞬间就写下条目。先读完整个文档然后再进行总结，会产生平淡且保留了含糊措辞的文本。
将含糊的措辞转化为决定，或者直接丢弃。 “我们目前倾向于 X”不是一个记忆条目。要么它是决定——将其写成决定——要么它是历史，而历史应该留在文档中。
为任何具有时效性的内容标注日期。 如果某项主张取决于供应商当前的行為或某个版本，请在条目中说明。这就是事实与六个月后陷阱之间的区别。
刻意限制常驻层的大小。 你保留在指令文件中的任何内容都应该足够简短，以便在一屏内读完。其他所有内容都应该是可检索的。厂商的指南在这点上达成一致是有原因的。
对提取出的内容进行版本控制，而不仅仅是文档。 将主张保存在可审查的内容中（如 diff、变更日志）是防止偏差的方法。这就是用于 AI 记忆的 git背后的核心思想。
每次你纠正智能体两次时，就添加一个条目。 这是单一最好的维护习惯。重复的纠正意味着一个缺失的条目在向你发出信号。
结语
对于智能体来说，一个记录在案的项目仍然感觉像没有文档记录一样，原因在于文档和记忆是针对不同读者的不同格式。文档用于解释，记忆用于指导。文档容忍含糊，记忆需要决定。文档在设计上是冗长的，而智能体在每次请求时加载的层在必要时必须是简短的。
因此，这种转化是提取，而不是导入：阅读你实际引用的文档，拉出仍然有效的主张，附上原因，记录被否决的方案，并删除描述你已不再运行的系统的三分之一内容。对于大多数项目来说，这只需要一个下午的时间。你换回的是你以为自己已经拥有的东西——一个其知识可供任何正在开发它的人（或任何智能体）使用的项目。如果你想先了解概念基础，持久记忆究竟是什么更深入地介绍了这一区别。