1. Claude Code 记忆架构的技术背景
在当今大模型技术快速发展的背景下,Anthropic 的 Claude Code 通过一套创新的记忆架构设计,解决了大模型应用中的关键瓶颈问题。与大多数厂商专注于基准测试性能不同,Anthropic 选择了一条更为人性化的技术路线,致力于让 AI 系统具备更接近人类的记忆处理能力。
1.1 上下文窗口的工程挑战
大模型在实际应用中面临一个基础性的工程瓶颈:固定的上下文窗口限制。Claude Code 的标准配置是在 200k token 的窗口下运行(通过特殊后缀可扩展至 1M)。这个看似庞大的容量,在实际编程会话中却可能被迅速耗尽:
- 读取几个中等规模代码文件
- 执行几次 grep 搜索操作
- 经过几轮代码编辑和讨论
这些常规操作就能轻易撑爆上下文限制,导致模型"遗忘"早期的重要信息。
1.2 记忆系统的设计理念
面对有限上下文与无限输入的矛盾,Anthropic 工程师构建了一套包含7个层级的记忆架构。这套系统的核心设计理念可以概括为:
"用低成本的浅层拦截,避免昂贵的深层压缩"
每一层记忆机制都有不同的触发条件和计算成本,系统会优先尝试成本最低的解决方案,只有在必要时才会启用更高层的处理机制。这种分层防御策略显著降低了运算开销,同时保持了对话的连贯性。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 记忆架构的7个层级详解
2.1 第1层:工具结果存储
技术实现:
- 文件路径:
src/utils/toolResultStorage.ts - 触发时机:每个工具结果产生时立即执行
- 成本:仅磁盘I/O,无API调用
核心挑战:
常见的代码操作如grep搜索可能返回100KB以上的文本,直接放入上下文会快速耗尽token预算。而这些结果通常在几分钟后就会失去时效价值。
解决方案:
- 每个工具结果在进入上下文前经过预算系统评估
- 超阈值的结果被写入磁盘(
tool-results/<uuid>.txt) - 上下文中仅保留约2KB的预览内容
- 模型可通过Read工具按需访问完整结果
关键技术点:
typescript复制ContentReplacementState = {
seenIds: Set<string>, // 已处理的结果(冻结)
replacements: Map<string, string> // ID -> 预览文本
}
这种状态持久化机制确保即使会话中断恢复,缓存映射依然有效。
2.2 第2层:微压缩
技术实现:
- 文件路径:
src/services/compact/microCompact.ts - 触发时机:每个API调用轮次前
- 成本:零至极低的API成本
三种工作机制:
a) 基于时间的微压缩
- 触发条件:闲置超过阈值(默认60分钟)
- 设计原理:利用API服务端提示词缓存1小时过期的特性
- 执行动作:清理旧工具结果,保留最近的N个
b) 缓存微压缩
通过API的cache_edits机制从服务端缓存删除工具结果,同时不使本地前缀失效。这是技术上极为精妙的设计:
- 工具结果注册到全局
CachedMCState - 超量时标记最旧结果删除
- 生成
cache_edits块随API请求发送 - 服务端从其缓存前缀中删除指定结果
c) API级上下文管理
使用context_managementAPI参数,将清理权限下放给服务端:
typescript复制ContextEditStrategy =
{ type: 'clear_tool_uses_20250919', // 清理旧工具结果
trigger: { type: 'input_tokens', value: 180_000 },
clear_at_least: { type: 'input_tokens', value: 140_000 } }
2.3 第3层:会话记忆
技术实现:
- 文件路径:
src/services/SessionMemory/ - 成本:每次提取消耗一次派生Agent API调用
- 触发时机:对话期间周期性执行
核心价值:
"边聊边记笔记"的策略避免了在上下文满载时才进行昂贵的全局摘要。当需要压缩时,直接使用现成的会话记忆作为摘要,省去API调用。
记忆模板结构:
markdown复制# Session Title
_A short descriptive title_
# Current State
_What is actively being worked on_
# Task specification
_What the user asked to build_
# Files and Functions
_Important files and their relevance_
# Workflow
_Bash commands and interpretation_
# Errors & Corrections
_Issues encountered and fixes_
# Codebase Documentation
_System components and relationships_
# Learnings
_What worked and what didn't_
# Key results
_Specific outputs requested_
# Worklog
_Step-by-step progress_
触发逻辑:
同时满足:
- 自上次提取token增长量 > 更新间距
- 工具调用次数达标 或 最近无工具调用
2.4 第4层:完整压缩
技术实现:
- 文件路径:
src/services/compact/compact.ts - 成本:一次完整API调用
- 触发时机:上下文超过自动压缩阈值且会话记忆不可用
熔断机制:
连续3次压缩失败会熔断当前会话的自动压缩,避免陷入失败死循环(曾导致单日25万次API调用浪费)。
压缩算法四阶段:
-
预处理:
- 执行
PreCompact钩子 - 剥离图片和技能发现附件
- 执行
-
生成摘要:
- 使用两阶段Prompt(先
组织思路,后 输出) - 包含9大区块的结构化摘要
- 使用两阶段Prompt(先
-
压缩后恢复:
- 重新注入关键上下文(最近文件、技能内容等)
- 重新执行
SessionStart钩子
-
边界标记:
插入System CompactBoundary消息明确压缩点:typescript复制compactMetadata = { type: 'auto' | 'manual', preCompactTokenCount: number, compactedMessageUuid: UUID, preCompactDiscoveredTools: string[], preservedSegment?: { headUuid, anchorUuid, tailUuid } }
2.5 第5层:自动记忆提取
技术实现:
- 文件路径:
src/services/extractMemories/extractMemories.ts - 成本:一次派生Agent API调用
- 触发时机:每个完整查询循环结束时
记忆类型:
- 反馈记忆:用户偏好和风格
- 流程记忆:重复性工作流程
- 事实记忆:需要记住的具体事实
- 代码记忆:重要代码模式和解决方案
记忆文件格式:
markdown复制---
name: testing-approach
description: User prefers integration tests over mocks
type: feedback
---
Integration tests must hit real database, not mocks.
**Why:** Mock/prod divergence masked broken migration.
**How to apply:** Use test database helper for db code.
互斥机制:
typescript复制function hasMemoryWritesSince(messages, sinceUuid): boolean {
// 扫描针对自动记忆路径的Edit/Write工具块
// 如果主Agent已保存记忆则返回true
}
2.6 第6层:梦境
技术实现:
- 文件路径:
src/services/autoDream/autoDream.ts - 成本:一次派生Agent API调用(可能多轮)
- 触发时机:后台运行,积累足够时间和会话后
生物学启发:
模拟人类睡眠中的记忆巩固过程,将近期碎片经历整合进长期知识体系。
级联门控序列:
- 锁可用性检查
- 时间阈值检查(≥24小时)
- 会话数量检查(≥3个)
- 记忆目录状态检查
四阶段巩固:
-
定位:
- 阅读
MEMORY.md了解当前索引 - 快速扫读现有主题文件
- 阅读
-
收集信号:
- 审查每日日志
- 检查"漂移"记忆
- 定向grep搜索历史记录
-
巩固:
- 写入/更新记忆文件
- 合并新信号到现有主题
- 转换相对日期为绝对日期
-
修剪索引:
- 保持
MEMORY.md在200行/25KB内 - 删除过时指针
- 解决文件矛盾
- 保持
锁机制:
/.consolidate-lock文件包含:
- 主体:进程PID(单行)
- mtime:最后巩固时间戳
2.7 第7层:跨Agent通信
技术实现:
- 文件路径:
src/utils/forkedAgent.ts等 - 成本:因模式而异
- 触发时机:Agent生成、后台任务、团队协调
派生Agent基础:
typescript复制CacheSafeParams = {
// 必须与父级字节一致
systemPrompt: SystemPrompt,
userContext: { [k: string]: string},
systemContext: { [k: string]: string},
tooluseContext: ToolUseContext,
forkContextMessages: Message(), // 父级对话(缓存前缀)
}
Agent工具模式:
- 同步:阻塞主线程
- 异步:后台运行
- 分离:完全独立
- 管道:流式输出到主线程
SendMessage通信:
typescript复制SendMessage({
to: 'research-agent', // 或'*'广播
message: 'Check Section 5',
summary: 'Requesting section review'
})
Agent记忆范围:
- 调用级:单次工具调用
- 会话级:单个会话期间
- 项目级:跨会话持久化
3. 核心设计原则与技术洞见
3.1 提示词缓存优化
挑战:
API服务端缓存提示词前缀约1小时。200K token场景下,缓存命中($0.003)与未命中($0.60)成本相差200倍。
缓存保留策略:
- 派生Agent继承相同前缀实现缓存命中
renderedSystemPrompt内存直传复用ContentReplacementState克隆冻结决策- 缓存微压缩使用
cache_edits修改服务端缓存 - 派生消息构建保持字节一致前缀
- 压缩后缓存断裂通知
缓存失效检测:
通过promptCacheBreakDetection.ts监控意外未命中,预先注册良性断裂避免误报。
3.2 分层防御体系
纵深防御策略:
- 工具结果存储 → 避免微压缩清理过多内容
- 微压缩 → 阻止会话记忆压缩
- 会话记忆压缩 → 阻止完整压缩
- 完整压缩 → 阻止上下文溢出错误
熔断机制:
- 自动压缩:3次重试限制
- 梦境扫描:10分钟节流
- 会话记忆:顺序执行包装器
- 提取记忆:与主Agent写入互斥
3.3 特性开关控制
关键系统由GrowthBook特性开关总控:
tengu_session_memory:会话记忆tengu_sm_compact:会话记忆压缩tengu_onyx_plover:梦境机制tengu_slate_heron:基于时间的微压缩
4. 实操经验与优化建议
4.1 记忆系统配置优化
关键参数调整建议:
| 参数 | 默认值 | 优化建议 | 影响 |
|---|---|---|---|
| 会话记忆更新间距 | 10,000 token | 根据项目复杂度调整 | 平衡新鲜度与成本 |
| 自动压缩阈值 | 上下文窗口-33K | 保留更多上下文余量 | 减少压缩触发频率 |
| 梦境触发条件 | ≥24小时+≥3会话 | 增加会话数量要求 | 提高巩固质量 |
| 工具结果预览大小 | 2KB | 增大技术文档预览 | 提升上下文效用 |
4.2 常见问题排查
问题1:压缩后关键信息丢失
- 检查
compactMetadata.preservedSegment - 验证
PreCompact钩子是否正确执行 - 确保关键文件在压缩后恢复列表中
问题2:梦境过度消耗资源
- 检查
/.consolidate-lock状态 - 验证门控条件是否被正确触发
- 限制梦境Agent的工具调用范围
问题3:缓存命中率下降
- 检查
ContentReplacementState一致性 - 验证派生Agent的前缀一致性
- 监控
promptCacheBreakDetection日志
4.3 性能优化技巧
-
会话记忆预加载:在项目启动时加载历史记忆文件,减少冷启动时间。
-
工具结果智能预览:根据文件类型动态调整预览策略:
- 代码文件:保留结构定义
- 日志文件:保留最后关键行
- 文档:保留标题和目录
-
分层触发阈值调优:基于项目特点调整各层触发条件:
typescript复制// 示例:调整微压缩配置 TimeBasedMCConfig = { enabled: true, gapThresholdMinutes: 30, // 缩短至30分钟 keepRecent: 3 // 保留最近3个结果 } -
记忆提取优先级:为自动记忆提取设置主题优先级,确保关键知识优先保存。
5. 技术影响与未来展望
Claude Code的记忆架构代表了大模型工程化的前沿实践。其分层处理、成本优化和生物学启发的设计理念,为AI系统如何有效管理长期交互提供了重要参考。
在实际应用中,这套架构显著提升了Claude在长周期编程会话中的表现力。开发者反馈表明,相比传统的大模型交互,具备记忆能力的Claude能够:
- 保持更好的上下文一致性(减少重复解释)
- 积累项目特定的知识(形成个性化技能)
- 发展更自然的工作节奏(类似人类协作)
从工程角度看,这种架构的真正突破在于它成功平衡了多个看似矛盾的目标:
-
即时响应与长期记忆:通过分层设计,既保持了对话的流畅性,又实现了知识沉淀。
-
计算成本与功能丰富:精细化的成本控制使复杂功能在经济上可行。
-
系统一致性与灵活性:严格的缓存一致性与灵活的记忆更新并存。
未来可能的演进方向包括:
- 跨项目记忆共享:在保护隐私前提下,允许相关项目间记忆迁移。
- 记忆版本控制:引入git-like机制管理记忆的演变更迭。
- 用户可配置的压缩策略:提供更多压缩算法和摘要风格选择。
这套系统的设计哲学也值得其他AI工程团队借鉴——不是盲目追求参数规模或基准分数,而是从真实用户场景出发,解决那些真正影响体验的工程瓶颈。这种务实创新的态度,或许正是Anthropic技术领先的关键所在。
