一句话总结：Claude Code 的记忆不是"把对话全存下来"，而是一套**三层加载 + 四种类型 + 严格写入纪律 + 自动整理（做梦）**的工程系统。它的核心信念只有一句——记忆是提示（hint），不是真理（truth）。
如果你用过 Claude Code 跨天、跨会话地写同一个项目，可能会有种奇怪的感觉：它好像"记得"你上次踩过的坑、记得你偏好 pnpm 而不是 npm、记得这个项目的构建命令——但你明明没有手动告诉它。
这套"记性"是怎么实现的？过去只能靠猜。直到一次意外，把答案直接摆在了所有人面前。
0. 为什么这次能讲清楚：一次本该被删掉的源码
2026 年，Claude Code 的某个版本（v2.1.88）在发布时误带了一个本应被剥离的 source map 文件——将近 60MB、约 51 万行可读的 TypeScript 源码，包括完整的记忆系统实现、Auto Dream 整理流程，甚至还有一个尚未对外发布的常驻守护进程 KAIROS。这个文件很快被镜像到 GitHub，社区据此把整套机制扒了个底朝天。
所以下面讲的东西，大部分不是"逆向猜测"，而是有源码佐证的真实实现。我们一层层来。
1. 全局视角：三层结构 + 四种类型
1.1 按"加载频率"分的三层：把地图而不是百科全书放进口袋
Claude Code 的记忆文件全是放在你磁盘上的纯 Markdown，路径在：
~/.claude/projects/<你的项目>/memory/ ├── MEMORY.md # 索引文件，每次启动都加载 ├── debugging.md # 某个主题的详细笔记（topic file） ├── api-conventions.md └── ...它的关键设计是按加载频率严格分层——不是所有记忆都一直占着上下文：
| 层 | 是什么 | 加载时机 |
|---|---|---|
| CLAUDE.md | 你手写的规则文件（“永远用 X”“构建命令是 Y”） | 每次启动全文加载 |
| MEMORY.md | 记忆目录的索引/目录页 | 每次启动加载，但只加载前 200 行 / 25KB，谁先到算谁 |
| Topic Files | 各主题的详细正文（debugging.md 等） | 启动时不加载，模型觉得需要时才用文件工具按需读 |
为什么要分？因为上下文窗口是稀缺资源。我们拿着Memory.md这张地图，去往Topic Files这个目的地，然后把对应主题文件加载进入上下文。
⚠️ 这里埋着一个非常重要的边界：MEMORY.md 超过 200 行就会被静默截断。后面第 6 节专门讲这个坑。
1.2 按"内容性质"分的四种类型
记忆不是一坨没结构的文本，源码里把它分成四类：
用户偏好：你喜欢的工作方式、沟通风格、工具选择（pnpm not npm）
反馈/纠正：你说过"不对，这样写"的地方
项目上下文：构建/测试约定、架构要点、模块关系
引用指针（reference pointers）：指向外部系统的"地址"——bug 在哪个 tracker、该看哪个 Slack 频道
为什么要分类？因为不同类型的寿命不一样。架构决策可以长期有效，而"进度类"记忆几天后就该淡出。分类是为后面"自动整理"埋的伏笔。
1.3 一条最容易被忽略、却最关键的设计约束
这是很多讲记忆系统的文章都没点透的一句话：
记忆只存"从当前项目状态推导不出来的东西"。
凡是能靠读代码、grep、git log拿到的信息——代码模式、当前架构、提交历史——一律不存进记忆。因为这些东西"现场看一眼代码"就有了，存进记忆只会过期、占地方、互相矛盾。
记忆要装的，是那些**"代码本身告诉不了你"的缝隙信息**：为什么当初选了这个方案、你这个人的偏好、上次那个诡异 bug 的根因。理解了这条约束，你才能理解后面所有取舍。
2. 写入：Auto Memory 是怎么"记笔记"的
Auto Memory = 写入通道。它让 Claude 在干活的过程中，自己给自己记笔记，你一个字都不用写。
它什么时候写？源码里有一个后台抽取 agent，在每一轮"查询循环"结束时悄悄跑一次：回看刚才这段对话，判断"有没有值得长期保存的信息"，有就写、没有就算了——不打断你正在进行的主流程。
你也可以显式下命令：“记住我们用 pnpm，不用 npm”“注意 API 测试需要本地起一个 Redis”——它会直接写进对应的 topic file。
写入纪律：质量比数量重要
这是整套系统里我最欣赏的部分。记忆系统最容易出的问题不是"存得不够"，而是"存了垃圾"——一条过时的记忆比没有记忆更危险，它会主动误导 agent 做错决策。
所以写入有两条铁律：
铁律一：先写文件，再更新索引。
只有当 topic file 成功落盘之后，才去更新 MEMORY.md 里的索引指针。这样可以防止一次失败的写入污染索引——你绝不希望 MEMORY.md 里有一条指向"不存在的文件"的指针。
铁律二：使用前先验证。
这是整个系统的灵魂——记忆是提示（hint），不是真理（truth）。Agent 在真正使用一条记忆之前，会先核实它是否还成立。比如记忆说"项目用 React 17"，它在操作前会先去翻package.json确认，而不是闭着眼睛相信记忆。
源码里甚至有一个memoryFreshnessText()函数，专门给超过一天的记忆生成"过期提醒"，把"这条可能不新鲜了"明明白白写给模型看。这就是"hint 不是 truth"落到代码层面的样子。
3. 召回：两条互补的路径（注意，不是二选一）
——下面这两条路径是同时存在、互相补位的。
路径 A：常驻索引（每次启动就在）
MEMORY.md 作为索引，每次会话开始就加载进上下文（前 200 行）。主模型读这份"目录"，知道有哪些 topic file 存在；当对话里出现相关线索，它就用标准文件工具按需把对应 topic file 整篇读进来。
简单说：目录常驻，正文现取。
路径 B：Sonnet 旁路选择（每轮异步挑相关项）
这条更精巧，也是源码里实锤的：每一轮，只要你发来一句（多于一个词的）提问，系统会单独调用一个便宜的 Sonnet 旁路查询来做召回。流程是：
- 扫描记忆目录下每个 topic file 的头部（读前 30 行，抽出 frontmatter 里的 description、类型、时间戳），最多扫 200 个文件；
- 把这些头部元信息（注意：不含正文）拼成一份清单交给 Sonnet；
- Sonnet 按一个明确的系统提示词来挑——“只挑你确定有用的，最多 5 条；不确定就别挑；一条都没明显有用就返回空列表”；
- 把选中的 ≤5 个 topic file 的完整正文，作为
relevant_memories附件塞进当前这一轮上下文。
这一步本质是语义相关性筛选，但它不是向量检索——只是一个语言模型在读"文件名 + 一行描述"的清单做判断。理解这点很重要（第 6 节会说为什么这是个局限）。
两条路径的分工：路径 A 保证"全局目录始终在线"，路径 B 保证"每轮把最相关的几篇正文精准送达"。一个管广度，一个管精度。
4. 做梦：Auto Dream 是怎么"整理记忆"的
光会写、会读还不够。你想象一下：一个人天天往笔记本里塞便签，从不整理——三个月后这本子就成了垃圾场：自相矛盾的条目（"我们用 Express"和后来的"改用 Fastify"并存）、“昨天”"上周"这种早已失效的相对时间、引用了已经被删掉的文件……
Auto Dream 就是给记忆做的那场 REM 睡眠。它是一个后台子 agent，在你不干活的间隙，把 Auto Memory 攒下的乱账重新整理成干净、有条理的知识库。
触发时机：两个条件必须同时满足
- 距离上次"做梦"已过24 小时；
- 且期间累积了至少 5 个新会话。
两个条件缺一不可。所以如果你只是一个长会话跨了两天（会话数不够），Dream 不会触发。也可以用/dream手动触发。
执行方式：Fork 一个受控子 agent
Dream 会 fork 出一个拥有独立上下文的子 agent，复用父对话已经缓存的 system prompt 和工具定义（省去重复加载的开销），专门去做"记忆整理"这一件事。它有一段专属的系统提示词，大意是：把最近学到的东西综合成持久、有条理的记忆，让未来的会话能快速进入状态；并且明确要求它"用窄范围的 grep，而不是把整个 transcript 读一遍"——这是为了省 token。
四阶段流程
Dream 的整理严格走四步（这也是你可以直接写进文章的"完整指令"骨架）：
- Orient（定位）：读取现有记忆目录和 MEMORY.md 索引，先在脑子里建一张"我现在都有啥、怎么组织的"的地图，动手之前先盘点。
- Gather recent signal（采集新信号）：去翻最近的会话 transcript（本地存的 JSONL 文件），但不整篇读，而是用窄关键词定向搜——只找用户纠正、明确的保存请求、反复出现的主题、关键决策。读 500 篇完整 transcript 是纯烧 token 的低回报操作，所以这一步刻意"挑着读"。
- Consolidate（合并）：把新信息并进已有的 topic file。关键维护都发生在这一步——合并重复、删掉被推翻的旧条目、把"昨天决定用 Redis"这种相对时间改写成"2026-03-15 决定用 Redis"的绝对时间，从根上消除时间错乱。
- Prune and index（修剪与重建索引）：重建 MEMORY.md，把它压回 200 行 / 25KB 以内——删掉指向已不存在文件的死指针、把太啰嗦的条目"降级"（索引里只留一句话，详情挪进 topic file）、解决索引和正文打架的矛盾。没改动的文件原样保留，Dream 是"外科手术式"的，不会每次把所有东西重写一遍。
整个过程结束，MEMORY.md 索引被更新、Topic Files 被重新组织。Agent 下次"醒来"时，面对的是一个更干净、更准确、更有条理的知识库。
5. 安全设计：梦境不能污染现实
这是 Dream 最重要、也最容易被忽略的一条护栏。
Auto Dream 子 agent 的工具访问是受限的：它只能读写记忆文件，不能动你的项目源码、配置，也不允许联网 / 使用 web 工具。
为什么要这么严？想象一下如果"做梦"过程能联网、能改代码——一次错误的整理判断，就可能把你的记忆连同项目文件改得面目全非，而且这种污染很难追溯。所以设计上划了一条死线：
整理记忆的过程，只能影响记忆本身，不能影响外部世界。
梦里发生的事，留在梦里。
6. 局限与坑：
坑一：200 行静默截断。
MEMORY.md 一旦超过 200 行，超出的部分会被悄悄截断。最要命的是——它会在被截断的内容里追加一句警告，但这句警告只有你去翻文件才看得到；模型那边看到的是一份"干净的 system prompt"，完全不知道索引被砍过。于是当你用了三个月、攒到第 201 条时，最旧的记忆会无声无息地掉队，模型不是幻觉、不是坏了，它只是忘了，而且没法告诉你它忘了。
坑二：召回靠关键词，不是语义。
前面说过，Sonnet 旁路是在读"文件名 + 一行描述"。而真正的检索层面更接近grep——字面关键词匹配。如果你的笔记写的是"docker-compose 端口映射"，你搜"端口冲突"，可能什么都召不回来。这也是 mem0、Hindsight、memsearch 这些第三方记忆层存在的理由：它们用向量/语义检索补上了这块。
坑三：单仓库范围。
Auto Memory 默认是按 git 仓库根目录隔离的。A 项目里学到的东西，不会自动跨到 B 项目。
彩蛋：KAIROS。
泄露源码里还有一个尚未发布的常驻守护进程 KAIROS（always-on daemon mode），任何公开版本里都还没启用——这是 Claude Code 记忆系统未来形态的一点剧透。
7. 收尾：它到底牛在哪
绝大多数 AI 记忆系统在优化"召回率"——尽可能把"可能相关"的全捞上来。而 Claude Code 优化的是**“恰当的召回”（appropriate recall）**：在对的时机、送上对的几条、还诚实地标注"这条可能过期了"。
把这套系统浓缩成三句话，也是你可以直接拿去当结尾的：
- 存得克制：只存代码里推导不出来的东西；
- 取得精准：常驻索引 + Sonnet 旁路双路径，每轮最多 5 条；
- 信得保留：记忆是 hint 不是 truth，用之前先验证、过期了有警告、闲时还会自己"做梦"整理。
工程上最不起眼、却最能"复利"的能力，往往就是这种——它安静地运行，直到有一天你发现，没有它的 AI 工具简直没法用。
本文基于 Claude Code 官方文档及社区对泄露源码的分析整理。其中涉及 Sonnet 旁路选择、四阶段 Dream、200 行截断、memoryFreshnessText()等实现细节，均来自源码层面的公开分析；KAIROS 等未发布特性以实际版本为准。
