claude-code-7-layer-memory-architecture¶

Ch01.857 claude-code-7-layer-memory-architecture¶

📊 Level ⭐⭐⭐ | 17.2KB | entities/claude-code-7-layer-memory-architecture.md

文章概要¶

troyhua（卡内基梅隆大学博士）对 Claude Code 源码的深度分析，聚焦其 7 层渐进式记忆管理系统。该架构借鉴人脑记忆分层原理，从毫秒级轻量清理到"做梦机制"巩固长期记忆，层层递进，成本递增，能力递增。

核心问题：上下文窗口 = LLM 的"金鱼记忆"¶

Claude Code 默认 200K token 上下文窗口（加 [1m] 后缀可达 1M）。一次真实 coding：读大文件 + grep 全仓库 + 几轮编辑 = 轻松超标。 Token 计数基础：tokenCountWithEstimation() 函数：

优先使用 API 返回的精确 input_tokens
对新增消息粗估（普通文本 ~4 bytes/token，JSON 更省）
预留约 20K tokens 作为输出缓冲，避免压缩时自己都塞不下 上下文窗口优先级：模型后缀 [1m] → 模型能力查询 → Beta Header → 环境变量 → 默认 200K

7层记忆架构详解¶

设计原则：防御金字塔¶

"预防为主" — 尽可能防止下一层（更昂贵的）触发。每层成本递增、能力递增，层层防护。

第1层：工具结果存储 — "日常清洁工"¶

问题：单次 grep 可返回 100KB+，大文件 cat 可达 50KB，直接塞上下文浪费 token。 解决方案：

超过阈值时，完整结果写到磁盘：tool-results/<sessionId>/<toolUseId>.txt
上下文里只放前 ~2KB 预览，用 <持久输出> 标签包裹
模型需要时，用 Read 工具读取完整版 关键设计：内容替换状态"冻结"——后续所有 API 调用用同样的预览，确保 Prompt 前缀字节完全一致，最大化缓存命中率。 远程可调：通过 tengu_satin_quoll 功能标志调节阈值，Anthropic 无需代码部署即可调整。

第2层：微压缩 — "每轮对话前的日常保洁"¶

最轻量级上下文清理，几乎不花 API 成本，每轮 API 调用前执行。 三种机制： a) 基于时间

距离上次助手消息超过阈值（默认 60 分钟）
服务器端 Prompt Cache TTL 约 1 小时，缓存已过期，可安全清理
替换为 [Old tool result content cleared]，保留最近 N 条 b) 缓存微型压缩（技术最有趣）
使用 cache_edits 在服务器端删除旧工具结果
本地消息不变，避免破坏缓存前缀
工具结果注册到全局 CachedMCState，超过阈值选最旧删除
关键约束：只运行主线。分支子代理（session_memory、agent_summary）若修改全局状态，会破坏主线程缓存编辑 c) API级上下文管理
使用 context_management API 参数，直接让 API 处理部分清理

第3层：会话记忆 — "最聪明的一层"¶

核心洞察：不是等上下文满了再慌张总结，而是实时维护结构化笔记。位置：~/.claude/projects/<slug>/.claude/session-memory/<sessionId>.md 结构化模板：会话期间自动维护结构化笔记 触发条件：Token 增长达到阈值 +（工具调用次数达标或上轮无工具调用） 零成本压缩： 1. 检查会话记忆是否有实际内容（而非空模板） 2. 用会话记忆标记作为压缩摘要——无需调用 API 3. 计算哪些最近消息要保留（从 SummarizedMessageId 向后扩展） 4. 返回压缩结果：会话记忆为摘要 + 保留的近期消息

第4层：全压缩 — "上下文快满时的紧急刹车"¶

当 tokenCountWithEstimation() 超过自动压缩阈值（有效窗口 - 13K）且 Session Memory 不可用时触发。 压缩流程： 1. 预处理：执行用户 PreCompact hook，去除图片、技能附件等 2. 生成摘要：向摘要代理分支请求 9 部分摘要

先写 <分析> 草稿思考，再输出 <摘要> 正文
草稿剥离，不占最终 Token
压缩后修复：重新注入最近读的文件、技能内容、计划附件
插入 SystemCompactBoundaryMessage 标记压缩点
只压缩部分消息：提示本身过长时分组丢弃最旧消息，重试 3 次

第5层：自动记忆提取 — 构建跨会话长期知识库¶

每任务结束时，提取跨会话持久知识，存到 ~/.claude/projects/.../memory/。 四种记忆类型：每种有特定条件和格式 MEMORY.md 索引文件：

最多 200 行或 25KB，超出自动截断
每个条目 ≤ ~150 字符

第6层：做梦机制 — "跨会话记忆巩固"¶

最惊艳的部分。积累足够会话后触发，像人脑睡眠时巩固记忆一样。 门控序列：从最便宜检查开始，大部分情况早早退出 互斥锁：.consolidate-lock 锁文件（PID + 时间戳），支持崩溃恢复和 stale 检测 四阶段： 1. 标定位置：扫描 memory 目录，读 MEMORY.md，避免重复 2. 收集：只 grep 怀疑重要的片段，检查矛盾记忆 3. 合并：合并新信号到现有文件，删除矛盾事实，把相对日期转绝对日期 4. 整理与索引：更新 MEMORY.md，删除过时条目，解决文件间矛盾 Dream Agent 工具限制：Bash 只读，Edit/Write 只限 memory 目录 UI 显示：后台任务，用户可从后台任务对话框终止，锁会回滚方便下次重试

第7层：跨代理沟通 — Multi-Agent 协作的基础¶

几乎所有后台操作（Session Memory、Dreaming 等）都基于分支代理模式。 分支代理设计：

状态隔离（克隆 LRU 缓存、AbortController 等）
通过 CacheSafeParams 和相同前缀共享 Prompt Cache，高效协作 Agent Tool 支持多种模式：
SendMessage Tool：Agent 间实时通信（支持广播、跨会话等）
Agent Summary：每 30 秒用最便宜的 Haiku 模型生成 3-5 词进度快照，用于协调 持久内存范围：三个级别

关键设计原则¶

原则	说明
分层防御	每层设计为防止下一层更昂贵的触发
提示缓存保存	几乎每个设计决策都考虑即时缓存的影响
隔离但共享	分叉代理克隆可变状态防止交叉污染，但共享提示缓存前缀防止成本爆炸
到处都是阻断	3次失败自动阻断、锁文件 PID 检测、互斥检查
GrowthBook 远程特征开关	几乎所有系统都被功能标志限制，关键功能随时可回滚

与其他层的关联¶

层级	核心机制	触发成本
第1层	工具结果磁盘存储	~0
第2层	微压缩（时间/缓存/API）	~0
第3层	会话记忆实时维护	~0
第4层	全压缩（9部分摘要）	高（API调用）
第5层	跨会话记忆提取	中
第6层	做梦机制（四阶段）	高
第7层	分支代理 + SendMessage	中

深度分析¶

1. "防御金字塔"架构的系统工程价值¶

Claude Code 的 7 层记忆架构本质上是一个成本递增、能力递增的漏斗型防御系统。这个设计的精髓不在于某一层的具体实现，而在于层级之间的成本梯度设计。第1层（工具结果磁盘存储）和第2层（微压缩）的成本几乎为零，但能处理绝大多数日常的上下文膨胀。只有当这两层都无法解决问题时，才会触发第3层（会话记忆，需要判断逻辑）和第4层（全压缩，需要 API 调用）。这种设计思路体现了"能用便宜方法解决就不动用昂贵方法"的工程哲学。这对我们的启示是：在设计 Agent 系统时，不仅要考虑每一层的功能实现，更要设计好层级之间的触发条件和成本梯度。否则很容易出现"小事大做"的资源浪费。

2. Prompt Cache: 容易被忽视的基础设施¶

整篇文章中，"Prompt Cache" 出现了无数次——工具结果"冻结"是为了缓存一致性、微压缩要"避免破坏缓存前缀"、分支代理"共享提示缓存前缀"。Claude Code 几乎在每一个设计决策中都把 Prompt Cache 的影响考虑进去了。这提醒我们，Prompt Cache 不是一个可选项，而是 Agent 系统的基础设施。在实际工程中，我们不仅要关注单次 API 调用的质量，更要关注如何在多轮对话中最大化缓存命中率。每一次改变 Prompt 前缀的操作（如替换工具结果内容）都会导致缓存失效，这是需要刻意管理的。

3. "做梦机制"的认知架构启示¶

第6层的"做梦机制"（四阶段：标定→收集→合并→整理）是整个架构中最有趣的设计。它模拟的是人脑在睡眠期间的记忆巩固过程：将分散的、短期的、易混淆的信号，转化为集中的、长期的、一致性更高的知识结构。这个机制有几个值得我们学习的工程决策：

门控序列：从最便宜的检查开始，大部分情况下早早退出，避免无意义的计算
互斥锁 + PID 检测：防止并发冲突和 stale 状态，支持崩溃恢复
工具限制（Bash 只读，Edit/Write 只限 memory 目录）：确保做梦过程不会对主系统造成意外破坏

4. 分支代理模式的安全隔离¶

第7层揭示了 Claude Code 如何处理多代理协作：状态隔离（克隆 LRU 缓存、AbortController）+ 共享 Prompt Cache。这个设计解决了两个互相矛盾的需求：隔离性（防止分支代理的副作用污染主线程）和效率性（共享缓存前缀避免重复计算）。这种"隔离但共享"的设计模式，对于构建复杂的多 Agent 系统有重要的参考价值。

实践启示¶

对 Agent 记忆系统设计的启示¶

不要等到上下文满了才处理：Claude Code 的第3层设计核心是"实时维护结构化笔记"而非"等满了再总结"。这提示我们在设计 Agent 时，应该采用预防性记忆管理而非被动式压缩。
建立清晰的成本梯度：设计 Agent 的记忆管理层级时，要明确每层的触发条件、计算成本和效果。通常可以先实现多层轻量级清理（基于时间、基于缓存、基于大小），最后才动用昂贵的 API 调用。
Prompt Cache 是基础设施：在系统设计之初就要考虑缓存一致性，而不是事后优化。每次可能改变 Prompt 前缀的操作（工具结果替换、消息删除）都需要评估对缓存的影响。
跨会话状态需要显式管理：Claude Code 通过 ~/.claude/projects/ 目录结构管理跨会话状态（memory/、session-memory/）。这提示我们，Agent 的长期知识库需要与对话历史分离，并且需要独立的索引和清理机制。

对 Agent 工程可靠性的启示¶

处处留退出路径：Claude Code 的"3次失败自动阻断"、互斥锁、PID 检测、后台任务可终止等设计，提示我们在构建 Agent 系统时要假设任何操作都可能失败，并且要为每种失败情况设计恢复路径。
远程特征开关是安全网：几乎所有系统参数都能通过 GrowthBook 功能标志远程调整，这意味着即使线上发现了问题，也不需要重新部署代码就能回滚或调整行为。在 Agent 这种高不确定性系统中，这个能力至关重要。
做梦机制可以借鉴：如果你正在构建需要长期运行的 Agent，可以考虑引入类似的"记忆巩固"机制——在低峰期或空闲期，对积累的知识进行系统性整理和去重，提高后续会话的效率。

对多 Agent 协作系统设计的启示¶

代理间通信需要独立的抽象层：Claude Code 的 SendMessage Tool 支持广播、跨会话等多种模式，说明代理间通信的需求比最初想象的更复杂。需要为不同场景设计不同的通信模式。
代理摘要是一种廉价的协调机制：每 30 秒用最便宜的 Haiku 模型生成 3-5 词进度快照，这个设计非常务实——不需要昂贵的 LLM 调用，就能实现基本的代理间状态同步。
状态隔离是安全的基础：分支代理模式中，克隆 LRU 缓存和 AbortController 是必须的。这提示我们，在构建多 Agent 系统时，必须为每个代理提供独立的执行状态副本，防止状态污染导致的不确定性行为。