夜雨聆风
Claude Code 源码分析之 Context 管理记忆机制
Context 管理机制
本章概要
当对话变长，Context 窗口会逐渐填满。Claude Code 实现了四层防御体系来智能管理 Context，确保主循环能持续运行。本章深入剖析各层压缩机制。
前置知识：第3章主循环架构后续章节：第5章权限系统
4.1 四层防御体系
┌─────────────────────────────────────────────────────────────┐
│ Context 管理四层防御 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ Layer 1: microCompact │ │
│ │ • 触发：60分钟无响应 或 GrowthBook 配置 │ │
│ │ • 频率：最高 │ │
│ │ • 代价：最低 │ │
│ │ • 效果：轻量级清理 │ │
│ └───────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ Layer 2: snipCompact (ANT专用) │ │
│ │ • 触发：HISTORY_SNIP feature │ │
│ │ • 频率：中等 │ │
│ │ • 代价：中等 │ │
│ │ • 效果：历史消息剪裁 │ │
│ └───────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ Layer 3: contextCollapse (ANT专用) │ │
│ │ • 触发：CONTEXT_COLLAPSE feature │ │
│ │ • 频率：较低 │ │
│ │ • 代价：较高 │ │
│ │ • 效果：上下文折叠投影 │ │
│ └───────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ Layer 4: autoCompact │ │
│ │ • 触发：token 达到阈值 │ │
│ │ • 频率：最低 │ │
│ │ • 代价：最高（需要 AI 生成摘要） │ │
│ │ • 效果：完整 AI 总结压缩 │ │
│ └───────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
4.2 触发条件
|
|
|
|
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
4.3 压缩调用顺序
4.3.1 压缩执行顺序代码
// [源码位置] src/query.ts:401-468 压缩调用顺序
state.messages = await snipCompactIfNeeded(state.messages, deps)
state.messages = await microcompactMessages(state.messages, deps)
state.messages = await contextCollapse.applyCollapsesIfNeeded(state.messages, deps)
if (state.autoCompactTracking) {
state = await autoCompactIfNeeded(state, deps)
}
4.3.2 四层防御触发顺序图
主循环 Setup Phase
│
├─▶ applyToolResultBudget() ▶ 工具结果预算控制（5% token 预留）
│
├─▶ snipCompactIfNeeded() ▶ ANT 专用历史剪裁（Feature 控制）
│ └── 触发条件：HISTORY_SNIP feature 启用
│
├─▶ microcompactMessages() ▶ 微压缩（最高频率，无成本）
│ └── 触发条件：60分钟无响应 或 GrowthBook 配置
│
├─▶ contextCollapse.apply() ▶ ANT 专用上下文折叠（Feature 控制）
│ └── 触发条件：CONTEXT_COLLAPSE feature 启用
│
└─▶ autoCompactIfNeeded() ▶ 完整 AI 压缩（最低频率，高成本）
└── 触发条件：token 使用率 > 90%
4.3.3 压缩层数据流图
原始消息 (token 数: 10000)
│
▼
microCompact → 9000 tokens (压缩率 10%, 延迟 <1ms)
│
▼
snipCompact → 8500 tokens (压缩率 16%, 延迟 <5ms)
│
▼
contextCollapse → 7000 tokens (压缩率 30%, 延迟 <10ms)
│
▼
autoCompact → 3000 tokens (压缩率 70%, 延迟 ~1000ms)
4.4 Layer 1: microCompact
4.4.1 定位
microCompact 是最轻量的压缩，执行频率最高。
4.4.2 实现机制
// [源码位置] services/compact/microCompact.ts
functionmicrocompactMessages(messages: Message[]): Message[] {
// 1. 移除过时的工具结果
// - 保留最近的 N 个工具结果
// - 移除超出窗口的旧结果
// 2. 压缩长文本输出
// - 超过限制的输出被截断
// - 添加 "[truncated]" 标记
// 3. 保留关键上下文
// - 系统提示
// - 用户初始请求
// - 最近的对话
}
4.4.3 触发条件
const MICROCOMPACT_INTERVAL_MS = 60 * 60 * 1000; // 60 分钟
functionshouldMicroCompact(state: State): boolean{
// 时间触发
const lastCompact = state.lastCompactTimestamp;
const now = Date.now();
if (now - lastCompact > MICROCOMPACT_INTERVAL_MS) {
returntrue;
}
// GrowthBook 配置覆盖
if (growthbook.isFeatureEnabled('microcompact_enabled')) {
returntrue;
}
returnfalse;
}
4.5 Layer 2: snipCompact
4.5.1 定位
snipCompact 是ANT（Anthropic 内部）专用的历史剪裁机制。
4.5.2 实现机制
// [源码位置] query.ts:401-410
asyncfunctionsnipCompactIfNeeded(state: State): Promise<void> {
if (!feature('HISTORY_SNIP')) {
return;
}
// 1. 识别可以剪裁的消息
// - 早期的工具执行结果
// - 冗长的中间过程
// - 已过时的上下文
// 2. 用摘要替换原始消息
// - 保留关键决策点
// - 移除细节
// 3. 更新消息历史
state.messages = applySnip(state.messages);
}
4.6 Layer 3: contextCollapse
4.6.1 定位
contextCollapse 是上下文折叠投影机制，将多轮对话压缩为简洁视图。
4.6.2 实现机制
// [源码位置] query.ts:440-447
interface CollapseConfig {
preserveFirst: number; // 保留前 N 条
preserveLast: number; // 保留后 N 条
windowSize: number; // 中间窗口大小
summaryModel: string; // 摘要模型
}
asyncfunctionapplyCollapsesIfNeeded(
state: State,
config: CollapseConfig
): Promise<void> {
// 1. 检查是否需要折叠
if (!shouldCollapse(state)) {
return;
}
// 2. 识别折叠点
const collapsePoints = findCollapsePoints(state.messages);
// 3. 对每个折叠点进行处理
for (const point of collapsePoints) {
// 保留首尾，中间用摘要替代
const summary = await generateSummary(
state.messages[point],
config.summaryModel
);
state.messages[point] = summary;
}
}
4.7 Layer 4: autoCompact
4.7.1 定位
autoCompact 是最重量级的压缩，使用 AI 生成摘要。
4.7.2 实现机制
// [源码位置] services/compact/autoCompact.ts
asyncfunctionautoCompact(state: State): Promise<void> {
// 1. 保存最近 N 条消息（保持上下文连贯）
const recentMessages = state.messages.slice(-KEEP_COUNT);
// 2. 调用 AI 生成摘要
const summaryPrompt = buildSummaryPrompt(state.messages);
const summaryResponse = await callModel(summaryPrompt);
// 3. 用摘要替换历史消息
state.messages = [
// 系统提示（保持不变）
state.messages[0],
// AI 生成的摘要
createSummaryMessage(summaryResponse),
// 最近的消息
...recentMessages
];
// 4. 更新追踪状态
state.autoCompactTracking = {
lastCompactAt: Date.now(),
compactedCount: state.messages.length - recentMessages.length
};
}
4.7.3 摘要生成提示
functionbuildSummaryPrompt(messages: Message[]): string{
return`
请总结以下对话的要点，保留关键信息和决策：
${formatMessages(messages)}
摘要应包含：
1. 用户的主要目标
2. 已完成的操作
3. 当前状态
4. 后续建议
请用简洁的语言总结。
`.trim();
}
4.8 Context 管理源码地图
services/compact/
├── autoCompact.ts # 完整 AI 压缩
│ │
│ └─ callModel() → 生成摘要
│
├── microCompact.ts # 微压缩
│ │
│ └─ removeStaleToolResults()
│ └─ truncateLongOutputs()
│
├── compact.ts # 完整上下文压缩
│ │
│ └─ applyToolResultBudget()
│ └─ buildContext()
│
└── contextCollapse.ts # 上下文折叠
│
└─ applyCollapsesIfNeeded()
4.9 设计模式与最佳实践
4.9.1 设计模式分析
-
责任链模式：四层压缩按顺序执行，每层处理后传递给下一层，任意一层都可以独立决定是否需要处理 -
策略模式：不同压缩场景使用不同算法，支持灵活替换扩展 -
渐进式降级：优先使用轻量级压缩，极端情况下才使用高成本AI压缩
4.9.2 最佳实践
-
优先依赖前三层压缩，autoCompact作为最后防线使用，降低成本 -
长会话定期使用 /session compact手动触发压缩，避免突然性能下降 -
重要上下文可以通过 /pin命令固定，防止被压缩丢失
4.9.3 常见问题与调试技巧
-
上下文丢失关键信息
-
调试：运行 /ctx-inspect查看压缩历史 -
解决：使用 /force-snip手动裁剪冗余历史，或/pin固定关键消息 -
token 计数不准
-
调试：检查 autoCompactTracking.tokenCount字段 -
解决：对比 API 返回的实际 token 使用量，运行 /ctx-reset重置计数
4.9.4 设计权衡
-
microCompact 轻量级设计 -
✅ 优点：速度快，无额外开销 -
❌ 缺点：压缩率仅 5%-10%，只能处理冗余格式 -
决策背景：90%场景下轻量级压缩即可解决token不足问题
4.10 小结
本章完成了以下内容：
-
四层防御体系：microCompact → snipCompact → contextCollapse → autoCompact -
触发条件：时间、token 阈值、feature flags -
调用顺序：在主循环 Setup Phase 依次执行 -
各层机制： -
microCompact：轻量级清理 -
snipCompact：历史剪裁 -
contextCollapse：上下文折叠 -
autoCompact：AI 摘要压缩
修正说明：autoCompact不是唯一的压缩机制，四层防御共同工作，各有适用场景。
下一步：第5章将深入分析权限系统，这是 Claude Code 安全的核心保障。
源码位置
-
压缩调用顺序： src/query.ts:380-470 -
microCompact： services/compact/microCompact.ts -
autoCompact： services/compact/autoCompact.ts -
contextCollapse： src/query.ts:440-447