Claude Code源码学习之上下文压缩（Compact）

Claude Code Compact 深度分析本文档面向 Java 开发者，深度解析 Claude Code 的上下文压缩（Compact）体系设计。源码路径：src/services/compact/分析版本：Claude Code 2.1.88一、先澄清边界：compact 包 ≠ 全部记忆管理很多人看到"上下文压缩"就以为这是 AI 记忆管理的全部，实际上 Claude Code 的"记忆"分为三个维度：维度负责模块说明对话轮次管理（多轮对话）QueryEngine.ts维护 messages 数组，每轮追加用户/AI消息Token 超限压缩services/compact/当消息总 Token 接近模型上限时，压缩历史持久化会话记忆services/SessionMemory/跨会话保存的结构化记忆，类似数据库工程化记忆文件memdir/（CLAUDE.md）项目级别的静态说明文件，每次会话注入本文档专注 compact 包，即解决"对话历史太长、Token 快溢出了"这一核心技术问题。二、为什么需要压缩？2.1 Token 限制背景大语言模型都有Context Window（上下文窗口）限制，例如 Claude 3.5 Sonnet 是 200K tokens。一次 API 调用 = System Prompt + 历史消息 + 当前输入 + AI 输出 ↑ ↑ ↑ 固定消耗 随对话增长 需要预留空间当历史消息越积越多，最终会超出 Context Window，API 调用失败。2.2 核心矛盾需要保留历史：AI 需要了解之前做了什么、用户的需求是什么必须压缩历史：Token 有上限，不可能无限增长压缩有代价：每次压缩都要调用 AI 写摘要，消耗时间和费用compact 包的核心任务就是在这三者之间找到最优平衡。三、压缩体系总览：5层架构Claude Code 设计了 5 层递进式压缩策略，从轻量到重量依次尝试：层级 名称 文件 代价 ───────────────────────────────────────────────────────────────────── 第1层 Time-based MicroCompact microCompact.ts 极低（无AI调用） 第2层 Cache-based MicroCompact microCompact.ts 极低（无AI调用） 第3层 SessionMemory Compact sessionMemoryCompact.ts 低（读文件） 第4层 Full Compact (Auto/手动) compact.ts 高（AI调用） 第5层 Partial Compact compact.ts 中（AI调用，局部）设计哲学：能不调用 AI 就不调，能少处理就少处理，最后迫不得已才全量压缩。四、第1层：Time-based MicroCompact（时间触发微压缩）4.1 触发条件// microCompact.ts// 当距离上次 AI 响应超过 N 分钟时触发constTIME_BASED_MC_THRESHOLD_MINUTES=...// 具体阈值场景：用户去吃饭了，回来继续对话。这期间 Anthropic 服务端的Prompt Cache（提示词缓存）已经失效（缓存有效期约5分钟），再发送这些历史工具调用结果完全是浪费。4.2 执行逻辑触发 → 找到所有旧的工具调用结果消息 → 把内容替换为 '[Old tool result content cleared]' → 不删除消息，只清空内容（保留结构完整性） → 不调用 AI，纯本地操作4.3 为什么不删消息？AI 模型要求消息满足以下不变量：每个tool_use（工具调用请求）必须有对应的tool_result（工具调用结果）它们必须成对出现，不能只有一个所以只能清空内容，不能删除消息，否则 API 会报错。Java 类比：类似于把MapString, Object中的 value 设为 null，但保留 key，否则外部代码遍历 key 时会出错。五、第2层：Cache-based MicroCompact（缓存感知微压缩）5.1 触发条件在正常响应时，如果检测到消息中有大量工具调用结果且 Token 数较高，会触发此层。5.2 核心逻辑// COMPACTABLE_TOOLS - 可被微压缩的工具集合constCOMPACTABLE_TOOLS=['FileRead',// 文件读取结果（可能很长）'Bash',// 命令行输出（可能很长）'Grep',// 搜索结果'Glob',// 文件列表'WebSearch'