Claude Code Memory System — Diagrams

配合 002-memory-system-deep-dive.md 文档使用。所有图表基于源码分析绘制。

图 1 — 三层记忆架构

CLAUDE.md 指令层 生命周期:永久 存储位置:项目目录 触发方式:用户手写 注入形式:系统提示正文 项目级规则和指令 Auto Memory 知识层 生命周期:跨会话持久 存储位置:~/.claude/.../memory/ 触发方式:自动提取 + 用户要求 注入形式:MEMORY.md + 语义召回 用户偏好、项目状态、反馈 Session Memory 恢复层 生命周期:当前会话 存储位置:session-memory/ 触发方式:token > 10K 注入形式:压缩时替代摘要 上下文压缩后恢复

三层架构解决不同时间尺度的记忆问题:永久指令 → 跨会话知识 → 会话恢复

图 2 — 四种记忆类型

user 我在和谁说话? 范围:始终 private 衰减:慢 格式:自由 被动学习用户信息 不做负面判断 调整沟通策略和深度 user_seandong.md feedback 怎么做才对? 范围:默认 private 衰减:中 格式:Rule+Why+How 同时记录成功和纠正 监听安静的确认信号 Why 用于边界情况判断 feedback_design.md project 在做什么?为什么? 范围:偏向 team 衰减:快 格式:Fact+Why+How 使用绝对日期 Why 判断记忆是否过期 不存代码可推导的信息 project_status.md reference 去哪找信息? 范围:通常 team 衰减:慢 格式:自由(指针) 指向外部系统 最轻量的类型 无需 Why/How 结构 reference_skills.md

闭合四类分类法覆盖「不可从代码推导的上下文」的完整谱系:谁 · 怎么做 · 在做什么 · 去哪看

图 3 — 语义记忆召回流程

用户发送消息 startRelevantMemoryPrefetch() 与模型流式输出并行执行 — 非阻塞 前置检查 auto memory 启用? · 多词查询? GrowthBook 开关? · 会话累计 < 60KB? scanMemoryFiles() 递归扫描 .md · 解析 frontmatter(30行) · 最多 200 文件 selectRelevantMemories() Sonnet 选择 ≤ 5 个文件 · 排除已激活工具文档 · JSON 输出 readMemoriesForSurfacing() 每文件 200 行/4KB · 附加 memoryAge · 新鲜度警告(>1 天) 注入为 <system-reminder> 附件 预算控制 单次:5 × 4KB 会话累计:60KB 去重:双层机制

语义召回使用 Sonnet 做选择(非 embedding),与主模型流式输出并行执行

图 4 — 自动记忆提取流程

对话轮结束 守卫检查 节流:每 N 轮运行一次(GrowthBook 配置) 游标:只处理 lastMemoryMessageUuid 之后的消息 互斥:主 agent 已写 memory 则跳过 Fork 后台子 agent(共享 prompt cache) 最多 5 轮 · 工具:Read/Grep/Glob + memory 目录内 Edit/Write 注入现有记忆清单(避免重复创建) 分析新消息中的可记忆内容 写入文件 + 更新 MEMORY.md 无需记忆 — 推进游标 有内容 无内容

后台 Fork Agent 不干扰主对话,共享 prompt cache 实现近零额外成本

图 5 — 记忆完整生命周期

创建 用户说「记住 X」 后台 Fork 自动提取 团队同步拉取(REST API) 存储 独立 .md 文件 + MEMORY.md 索引 Frontmatter: name · description · type (user|feedback|project|reference) 召回 MEMORY.md 始终在系统提示中 语义召回(Sonnet) 每轮异步预取 嵌套记忆 文件触发注入 注入 <system-reminder> 附件消息 使用 引用前先验证 · 新鲜度标注 「记忆说 X 存在」≠「X 现在存在」 清理 用户手动编辑/删除 模型更新/删除过时记忆 团队同步推送

完整生命周期:创建(3 种方式)→ 存储 → 召回(3 种方式)→ 注入 → 使用 → 清理(3 种方式)

图 6 — 六种记忆的加载时序

会话时间线 会话启动 每轮对话 工具使用 轮结束 / 压缩 CLAUDE.md ← 一次性,记忆化 MEMORY.md 索引 ← 系统提示节 语义召回记忆 ← 异步预取 嵌套记忆 ← 工具触发 自动提取 写入文件,下次会话加载 ↑ Session Memory 压缩时替代摘要(零 API 调用)

六种记忆在会话时序中的加载位置:越靠右越是「按需」加载