Claude Code 源码拆解
Book 第三十七章：Claude Code 的 Memory 其实分四层
第六部分：迁移与附录

第三十七章：Claude Code 的 Memory 其实分四层

把 memdir、session memory、team memory 和 autoDream 合成一张完整 memory 地图。

1. 为什么这章必须单独拆

前面的文档里已经讲过：

  • transcript / resume
  • attachments / context 注入
  • settings sync

但 Claude Code 的 memory 体系一直是散着出现的。

如果只看某一个点，很容易误以为“memory 就是某个 MEMORY.md 文件”。

实际完全不是。

从源码看，它至少同时有四层：

  1. memdir
  2. session memory
  3. team memory sync
  4. autoDream consolidation

这四层分别对应：

  • 本地长期记忆目录
  • 当前对话摘要
  • repo 级共享记忆
  • 后台沉淀与整理

相关源码锚点：

  • src/memdir/paths.ts
  • src/memdir/memdir.ts
  • src/memdir/teamMemPrompts.ts
  • src/services/SessionMemory/sessionMemory.ts
  • src/services/SessionMemory/sessionMemoryUtils.ts
  • src/services/teamMemorySync/index.ts
  • src/services/teamMemorySync/watcher.ts
  • src/services/autoDream/autoDream.ts
  • src/services/autoDream/consolidationLock.ts
  • src/services/autoDream/consolidationPrompt.ts

2. 先说结论

我对这一块的判断是：

Claude Code 的 memory 不是一层“记忆功能”，而是一套分层存储和分阶段沉淀策略。

最重要的结论有四个：

  1. memdir 是正式的长期记忆目录协议，不是随便放几份 Markdown。
  2. session memory 是按阈值触发的会话摘要，不是每轮都写。
  3. team memory 是 OAuth + repo scope + checksum sync 的共享层。
  4. autoDream 是后台 consolidation，不是实时主链路。

3. 总体结构图

flowchart TD
    A["当前 session / transcript / tool usage"] --> B["SessionMemory"]
    B --> C["session summary file"]

    D["project memory dir"] --> E["memdir contract<br/>MEMORY.md + typed memory files"]
    C --> E

    E --> F["TeamMemorySync"]
    F --> G["server-side repo memory"]

    H["autoDream"] --> I["读取 transcript / logs / memdir"]
    I --> E

这张图最关键的一点是：

Claude Code 把“记忆”拆成了不同寿命、不同作用域、不同触发方式的几层。

4. memdir：这是长期记忆目录协议

源码锚点：

  • src/memdir/memdir.ts
  • src/memdir/paths.ts
  • src/memdir/teamMemPrompts.ts

4.1 路径解析是有安全边界的

getAutoMemPath() 的优先级并不是随便拼路径：

  1. cowork 环境变量显式覆盖
  2. 受信任 settings 的 autoMemoryDirectory
  3. <memoryBase>/projects/<canonical-git-root>/memory/

这里很重要的一点是：

  • 它明确不接受 project settings 随便改 memory 根目录

也就是说，memory 落盘位置本身就被当成安全边界。

4.2 MEMORY.md 不是普通文件，而是索引入口

memdir prompt 里明确约束了：

  • MEMORY.md 作为索引
  • 记忆类型有分类
  • 内容有行数和字节上限
  • 团队记忆和私有记忆有拼装规则

这说明 memdir 不是“让模型自己瞎写笔记”，而是一份 prompt/runtime 契约。

5. Session Memory：会话内摘要层

源码锚点：

  • src/services/SessionMemory/sessionMemory.ts
  • src/services/SessionMemory/sessionMemoryUtils.ts

session memory 的触发方式很有意思。

它不是每轮都更新，而是依赖：

  • context token 总量阈值
  • tool call 次数阈值
  • post-sampling hook

达到条件后，才会：

  • 在受控目录里维护当前会话的 markdown 摘要文件
  • 用 forked subagent 做摘要更新

这有两个很明确的设计意图：

  • 不把摘要写入成本塞进主回合
  • 不让会话记忆无限膨胀

6. Team Memory：共享，但不是双向实时数据库

源码锚点：

  • src/services/teamMemorySync/index.ts
  • src/services/teamMemorySync/watcher.ts

team memory sync 这层特别值钱，因为它很清楚地界定了“共享记忆”该怎么做。

6.1 它有严格的 eligibility

要启用它，至少要满足：

  • first-party
  • OAuth
  • profile / inference scope
  • repo 级上下文

也就是说，共享记忆不是本地 feature toggle，而是带身份前提的服务能力。

6.2 它的同步协议是 checksum/delta 风格

这一层会维护：

  • last checksum
  • per-key checksum
  • server max entries 学习值

同步策略也很克制：

  • pull 以服务端为准覆盖本地 key
  • push 走 delta upload
  • 删除不会自动传播

这说明作者追求的是“稳定的共享增量同步”，不是强一致数据库。

7. autoDream：后台 consolidation 层

源码锚点：

  • src/services/autoDream/autoDream.ts
  • src/services/autoDream/consolidationLock.ts
  • src/services/autoDream/consolidationPrompt.ts

这一层很容易被误解成“自动摘要”。

但从实现看，它更像：

后台 durable memory consolidation job。

它会按顺序检查：

  • 时间阈值
  • 触达的 session 数量阈值
  • lock 文件

满足条件后，才启动 forked agent 去看：

  • transcript
  • logs
  • 现有 memdir

然后把值得长期保留的内容沉淀回 memory。

这里特别成熟的一点是 lock 文件设计：

  • mtime 表示 lastConsolidatedAt
  • 文件内容记当前 holder PID

这说明作者很清楚这类后台任务最怕并发踩踏。

8. 这四层放在一起，Claude Code 的 memory strategy 才完整

如果把四层合在一起看，就能看出很清楚的分工：

8.1 Session scope

由 session memory 负责：

  • 当前对话摘要
  • 控上下文膨胀

8.2 Project scope

由 memdir 负责：

  • 项目长期记忆
  • 结构化索引

8.3 Team scope

由 team memory 负责：

  • repo 级共享经验
  • 服务端同步

8.4 Consolidation scope

由 autoDream 负责：

  • 把零散历史沉淀成 durable memory

这说明 Claude Code 的 memory 不是“记住更多”，而是：

把不同寿命和不同共享范围的信息分别放进不同层。

9. 对 C# 拆分最有用的建议

如果做 C# 版，这一层非常适合拆成四个独立模块：

9.1 MemoryDirectoryService

负责：

  • memory 根路径解析
  • MEMORY.md 索引契约
  • typed memory file 约束

9.2 SessionSummaryService

负责：

  • session threshold
  • hook 触发
  • 摘要文件更新

9.3 TeamMemorySyncService

负责：

  • OAuth eligibility
  • checksum / delta sync
  • watcher / debounce

9.4 MemoryConsolidationJob

负责：

  • 后台调度
  • lock
  • transcript/logs 到 durable memory 的沉淀

10. 哪些值得抄，哪些不要抄

值得抄的：

  • 按 scope 拆 memory 层
  • 不把所有记忆维护都塞进主回合
  • 用 prompt + 文件结构双重约束 memory 目录

不要原样抄的：

  • 第一版就把四层全做完
  • 让共享记忆承担强一致数据库职责
  • 让项目级配置随便改 memory 根目录

11. 一句话收口

Claude Code 的 memory 体系最值钱的地方，不是它“会记忆”，而是它把会话、项目、团队和后台沉淀拆成了四种不同的长期性协议。