Zui近这段时间，整个 AI 开发圈子里简直像过节一样热闹。自从 Claude Code 的源码意外流出后无数开发者像饿狼扑食一样扑了上去。各种解读、教程、细节分析层出不穷，甚至有人把它用 Python、Go、Rust 重新实现了一遍。这真有一种“一鲸落，万物生”的壮观景象。

之前我也曾深入研读过它的系统提示词，并尝试复刻过其中的记忆系统逻辑。但今天我想抛开那些表面的 Prompt 技巧，带大家潜入源码的深海，去kankan Anthropic 到底是如何用一种极其务实、甚至有些“复古”的方式，构建了这套让无数人惊叹的记忆机制。

当我们翻开源码，第一感觉可Neng不是惊艳，而是困惑。因为 Claude Code 并没有像我们预想的那样，搞一个统一的 Memory Service 加上向量数据库来大包大揽。相反，它走了一条完全不同的路：文件系统优先，分层极其清晰，召回时机明确，而且计算代价完全可控。

拒绝“黑盒”：为什么是文件而不是数据库？

在深入细节之前，我们必须先理解 Claude Code 的核心哲学。在它的设计里记忆被拆解成了四个完全独立的维度：长期记忆、当前轮相关记忆、会话压缩摘要、以及子代理的独立记忆。

这种拆分并非多此一举。源码中明确界定了长期记忆的四种类型，它们dou有一个共同点：无法直接从当前的代码状态中推导出来。比如用户的个人习惯、项目的背景故事、团队的协作约束、甚至是外部系统的 API 入口。这些信息Ru果不显式地存下来下次对话时模型就会像失忆了一样。

反过来代码结构、文件路径、Git 历史记录、当前正在处理的临时任务，这些内容被严格禁止进入长期记忆。为什么？因为它们本来就有一个“权威来源”——也就是代码库本身。Ru果把这些也塞进记忆，就会出现“双份真相”的尴尬局面：代码里写的是 A，记忆里记的是 B，模型在决策时就会左右摇摆，不知所措。

所以记忆系统的职责被限定得死死的：只保存“代码之外的信息”和“会跨轮次影响决策的信息”。

四层架构的精妙之处

源码中清晰地展示了这四层结构，每一层dou有其独特的使命：

第一层：Auto Memory / Team Memory 这是负责跨会话保存信息的基石。它的目录逻辑设计得非常严谨，专门用来存储那些需要持久化的知识。

第二层：Relevant Memories 这一层完全不关心长期存储，它唯一的任务就是判断：用户现在问的这个问题，应该把哪几条历史记忆临时捞出来塞进上下文里？

第三层：Session Memory 这层服务的是长会话的压缩，不负责跨会话的记忆。它位于当前 session 下的 summary.md 文件中，专门用来应对超长对话。

第四层：Agent Memory Ru果子代理需要持久化自己的经验，它Ke以在 user、project 或 local 三种作用域下拥有独立的目录。

一旦把这四层拆开，hen多之前纠结的设计选择瞬间就变得顺理成章了。

写入的艺术：两步走协议与 Frontmatter 的魔力

hen多人好奇，Claude Code 到底是怎么把记忆真正落盘的？这里有一个非常硬核的工程判断。

源码里定义了一套严格的写入约束，我们Ke以把它kan作是一个“两步走协议”：

第一步： 先把记忆内容写入到它自己的独立文件中，并且必须包含 Frontmatter 格式。

第二步： 在一个名为 ENTRYPOINT_NAME 的索引文件中，添加一个指向刚才那个文件的指针。这个索引文件本身不承载正文，每一行就是一个简单的链接格式：`- — one-line hook`。

这个设计kan似简单，实则蕴含了三个极其重要的工程智慧：

第一，索引与内容分离。 hen多团队初期为了省事，把所有记忆dou堆到一个大文件里。这在前期确实简单，但到了后期就是一场灾难。Claude Code 从一开始就坚持每条记忆单文件化。这意味着当你需要geng新某一条信息时只需要修改那一个小文件，而不会引起全量重写，也不会触发巨大的 Git Diff。

第二，强制摘要。 Frontmatter 里强制要求有一个 description 字段。这个字段不是摆设，它直接参与了后续的召回。hen多团队Zuo知识库时只写正文不写摘要，Zui后只Neng靠 embedding 模型硬扛。Claude Code 反其道而行之，它要求在写入阶段就必须产出一条高质量的摘要。召回的质量在写入的那一刻就Yi经注定了。

第三，完全基于文件系统。 这可Neng是Zui“反潮流”的一点。数据库方案Zui大的问题往往不在于性Neng，而在于可观察性。一旦出了问题，你需要查 schema、查索引、查 embedding 版本、查写入日志，排障效率极低。而用文件方案，你Ke以直接去目录里kan文件，团队同步时直接走 Git，调试成本低到令人感动。

当然文件方案也有代价。文件一多，扫描成本会上升；索引文件过长也会逼近 prompt 的 token 上限。但 Claude Code 通过动态召回机制巧妙地兜住了这个问题，这其实是一套组合拳。

双通道写入：实时与后台的博弈

在具体的写入链路上，Claude Code 展现了一种非常有趣的“双通道”策略。

第一条链路是主模型实时写入。系统提示词里Yi经明确告诉了模型：记忆目录在哪、允许写什么、怎么写文件、什么时候写。这意味着 Claude Code 对模型的假设hen明确：模型Ke以自己判断“这条信息值不值得保存”，然后直接调用写文件工具落盘。写入不是一个外置的神秘 API，就是普通的文件操作。这条路的好处是反馈延迟极低，用户刚说完“记住这个偏好”，主模型当轮就Neng写，不用等后台任务。

Ru果主模型这一轮没动手写，系统会在对话结束时触发后台抽取器。这里有一段非常关键的逻辑：它会检查是否Yi经有内存写入操作。Ru果主模型Yi经写过后台抽取器就会直接跳过。这防的是“双写”。hen多系统Zuo异步归档时忘了这件事，Zui后要么生成重复记忆，要么覆盖用户刚刚确认的内容。

而且，后台抽取器的权限被收敛得极死。它只准Zuo归档，绝不允许顺手验证代码，也不许修改业务文件，geng不许借机跑工具链。权限Ru果不锁死，后台代理迟早会从一个简单的归档器膨胀成第二个不受控的主代理。

KAIROS 模式：像写日记一样记录

源码中还隐藏着一个geng有意思的模式，叫Zuo KAIROS。它不要求模型实时维护 MEMORY.md，而是采取了一种geng符合人类直觉的策略：新记忆先按天追加到日志文件里。

规则hen简单：随着工作的进行，把任何值得记住的东西以时间戳列表的形式追加到当天的日志文件中。这是一个只追加的过程。然后会有一个独立的夜间流程，把这些日志蒸馏成 topic files 和 MEMORY.md。

这条策略非常适合长驻 Agent。当会话存活时间hen长时频繁重写主题文件和索引的代价hen高，冲突也多。先写日志，晚上再慢慢整理，吞吐geng稳，模型也不容易在白天工作时把记忆目录写乱。

召回机制：没有向量库的精准打击

Ru果说写入是“存”，那召回就是“取”。Claude Code 的召回机制分成两种：静态注入和动态召回。

hen多系统只Zuo前者，结果上下文越来越肥；或者只Zuo后者，导致基本的行为约束丢失。Claude Code 两条腿走路。

静态注入解决的是“全局框架”问题。它会构造一个稳定的上下文，包含项目规则、用户偏好、团队共享记忆索引。这适合放那些“大方向会持续生效”的内容。

但静态注入解决不了所有问题。长期记忆正文一多，全部塞进 prompt 代价太高。于是动态召回登场了。每轮用户发言后系统会启动一个相关记忆预取。这个预取不会阻塞主流程，等到条件满足时再消费。

Zui让人惊讶的是这里没有用向量库！它的检索逻辑非常朴素但有效：

先决定搜索哪个目录。

读取索引文件。

根据当前的 query，在索引的 description 字段里Zuo关键词匹配。

把匹配到的文件内容读出来变成 attachment。

这套方案的好处是显而易见的：轻量、快速、不需要起向量服务。缺点也hen明确：召回质量强依赖 frontmatter 的 description。写入时 description 写差了后面召回一定差。但这恰恰倒逼了写入质量的提升。

四处入口：记忆是如何注入上下文的？

hen多人kan Agent 源码时老在问“上下文是在什么地方拼进去的”。这个问题本身就有误导性。在 Claude Code 里记忆的注入入口不止一个，它们各司其职。

第一处是 System Prompt。 这里进来的主要是“记忆系统的使用规则”，比如什么时候读、什么时候存、什么时候验证失效。这是行为层指令。

第二处是 getUserContext 构造的 claudeMd。 这里进来的是 CLAUDE.md、rules、MEMORY.md 这种比较稳定的文本。这是稳定背景层。

第三处是 Relevant Memory Attachment。 被召回的正文不会直接拼到 claudeMd，而是先变成 attachment，再包装成系统提醒。这意味着这些记忆是临时的、按轮次加载的、带 freshness header 的。它的优先级和普通用户消息不同。

第四处是 Session Memory Compact。 当上下文过长后系统会把会话前半段替换为一条 summary message。这是上下文续命层。

这四处入口分工明确，规则、稳定背景、临时相关信息、压缩摘要，各走各的通道，互不干扰。这也解释了为什么 Claude Code 的行为相对稳定。

压缩策略：在 Token 边缘的极限求生

hen多人一听“记忆系统”，第一反应是长期 memory 压缩。但实际上，Claude Code 里Zui成熟的压缩逻辑，落在 session memory 上。

当上下文真的不够用时系统会优先尝试会话压缩。它的动作顺序非常讲究：

它不会图省事把所有旧消息dou抹掉，而是保留一段“Zui近窗口”。窗口大小是默认定义好的。这个策略解决了一个痛点：摘要永远会损失细节，Zui近一段工作现场Zui好保留原始消息，模型续Zuo时不至于失真。要是所有内容dou只剩 summary，模型会失去工具调用上下文、局部错误信息、Zui近的计划变geng。

geng硬核的是源码里还有一段防御逻辑：Ru果Zui近保留窗口里出现了 tool_result，系统必须把匹配的 tool_use 也补进来；Ru果 assistant 消息因为流式输出被拆成多个块，thinking 和 tool_use 也要一起补齐。否则 compact 后发给 API 的消息链会断，直接报错。

这一段代码说明作者绝对踩过坑，或者至少认真想过 API 侧的不变量。hen多开源 Agent 框架在消息压缩这里写得hen草率，Zui后线上 bug dou长一个样：tool result 找不到 parent，thinking 丢了message 合并失败。

就算 summary.md Yi经是摘要，compact 时还会再Zuo一次 section 级裁剪。这套逻辑谈不上优雅，语义理解也谈不上深入，但它有一个优点：非常稳。系统真的到了上下文极限时保底截断总比把整个 compact 失败掉强。工程里hen多时候要的是“退化可接受”，不是“完美压缩”。

此外Ru果发生过裁剪，系统会额外附一句话，告诉模型和人类完整 session memory 文件路径在哪。排障时你Ke以直接打开原始 summary.md，不用猜裁掉了什么。

工程启示：简单才是终极的复杂

kan完这套设计，我们不难出它的工程代价与收益。

收益在于：

分层彻底。 长期记忆、当前轮召回、会话摘要、子代理记忆，各自有自己的存储形态和注入入口。系统复杂度是被隔离开的。

文件优先。 排查方便，审计方便，人工纠错方便。hen多团队高估了数据库和向量库的必要性，低估了可观察性的重要性。

动态召回轻量化。 对 CLI Agent 这种高频交互场景，走轻量 manifest + side query 的性价比极高。它把复杂度留给模型的小规模选择，而不是重型检索基础设施。

压缩时的保底机制。 压缩时保 recent window，并修补 tool_use/tool_result 不变量。这一点极少有团队一开始就写对。

代价在于：

对写入质量的高要求。 Frontmatter 的 description 质量变成关键依赖。这个字段一旦写烂，召回效果会大幅波动。它省掉了 embedding 的复杂度，也把一部分压力前置给写入质量。

状态机复杂度。 双通道写入意味着状态机会geng复杂。主模型Ke以写，后台 extractor 也Neng写。虽然代码里有跳过逻辑，但这类架构天然比单通道geng需要小心。

粗粒度的截断。 Session memory 的 section 截断是粗粒度的。它靠字符数近似 token，再按行截断，这属于保底工程，不属于精细压缩。Neng用，谈不上漂亮。

索引容量压力。 MEMORY.md 仍然有索引容量压力。即便动态召回Yi经分担了hen大一部分负担，入口索引的组织质量依然重要。

我们Ke以学到什么？

Ru果把这套思路迁移到我们自己的 Agent 系统，有几条建议值得借鉴：

第一，先拆问题，再选技术。你要先决定自己在解哪件事：跨会话长期记忆、当前轮检索、超长对话压缩、团队共享经验。不要一上来就建一个统一的 Memory API。

第二，先用文件，再考虑数据库。只要你的系统规模还没逼到那个份上，文件系统几乎总是geng划算。它便宜、透明、好调试。hen多团队用数据库，是因为觉得那样“geng像正经系统”，这个判断其实没什么含金量。

第三，把召回质量的责任前移到写入阶段。Claude Code 用 description Zuo manifest 检索这件事，给我的启发hen大。与其指望后面靠复杂召回算法弥补，不如要求写入时就产出高质量摘要和类型信息。

Claude Code 的记忆系统没有神秘技术。它的难点不在某个单点算法，在边界控制和时机设计。什么时候写，写到哪里什么时候读，读多少，压缩后保留什么这些问题dou比“用什么模型Zuo召回”geng重要。

Ru果你把这篇文章里的结论压成一句工程建议，那就是：先把长期记忆、短期相关记忆、会话压缩拆开，再谈检索和存储。

---