Claude Code 上下文管理系统

（下文基于公开技术梳理；产品名以官方为准。）

概述

上下文管理是工程含量很高的子系统：约 15 个文件、15000+ 行代码，多来自生产踩坑与修补。

曾暴露的问题（量级）：例如 1279 个会话出现 50+ 次连续自动压缩失败，单次最多约 3272 次；由此导致全区每天约 25 万 次无效 API 调用。修复思路：连续失败超过 3 次则停止重试，避免空转。

---

第一层：微压缩（Micro Compact）

核心逻辑

• 纯规则驱动，不调用模型。
• 按工具类型白名单保留最近 n 条工具结果，更早的清理掉。
• 白名单示例：file read、bash grep、web search、web fetch、file edit、file write 等时效短的输出。

与 Prompt Cache 的配合

需兼顾 Anthropic Prompt Cache，避免清理方式整块失效缓存，分两条路径：

路径	行为
cache micro compact	用户连续对话时，通过 cache editing API 让服务端删掉工具结果，不破坏 prompt 前缀缓存；维护全局状态，追踪已注册的工具结果
time-based micro compact	用户离开一段时间后，按「距上一条助手消息」的时间间隔判断；超过阈值则直接改消息内容，用占位符替换旧工具输出

工程细节

cache micro compact 仅对主线程生效：通过 query source 隔离子 agent（如 fork 的 choose agent），避免删到对话里本不存在的工具结果。

---

第二层：会话记忆压缩（Session Memory）

核心思路

• 不做整段对话摘要。
• 抽取结构化事实（项目结构、用户偏好、任务进度等）写入本地记忆目录，用 memory.md 等内容替代「长对话摘要」。

配置（示意）

• 最小 tokens（如默认约 5 条量级）
• 最大 tokens（如默认约 4 万）
• 从最后一条已总结消息往前扩，需同时满足「最小 token + 最小消息数」，或触达最大 token 上限。

边界

• 不可拆开 tool use 与 tool result 成对消息。
• 存在 thinking block 时：同一 message id 下多段（thinking 与 tool use）不能只留后半段。

优势

成本相对低（不必为摘要再调大模型）、仍保留近几轮原始消息，模型能看到近期完整细节。

---

第三层：完整压缩（Full Compact）

触发

当会话记忆压缩不可用或仍不够时回退，需要调用模型。

Prompt 设计

要求模型按约 九个维度 归纳，例如：用户请求与意图、关键概念、文件与代码片段、错误与修复、解决过程、用户原话、待办、当前工作状态、可选下一步等。

Analysis 机制

• 模型先在 analysis 里写详细推理，再在 summary 里出终稿。
• 格式化时剥掉 analysis，仅用于辅助质量（类 chain-of-thought）。

超长输入

压缩请求本身可能超长：按 API 轮次分组，从最早组开始丢弃，最多重试 3 次。

压缩后恢复

清空文件读取缓存，重新注入 plan、skill、MCP 说明、agent 列表等曾被挤掉的上下文。

---

第四层：自动触发

项	说明
触发条件	每次模型调用后看 token；超过阈值（如 上下文窗口 − 约 13000 token 缓冲）则触发压缩
顺序	先试会话记忆压缩；不行或压完仍超 → 完整压缩
熔断	连续失败 >3 次停重试（对应前述 API 浪费治理）
排除	session memory、compact 等带特定 query source 的请求不触发自动压缩，避免子 agent 触发死锁

---

工具系统与上下文工程

• 工具加载：内置 80+ 工具；核心启动即载，扩展通过 tool search 按需发现。
• 参数校验：各工具 Zod schema 校验模型输出的 JSON。
• 大输出：过大则进外部 tool result storage，给模型引用/按需取。
• Snip compact：不跑完整压缩，而是从对话里剪掉某段消息以腾 token，作为更轻的中间手段。

---

核心原则

四层（微压缩 → 会话记忆 → 完整压缩 → 自动触发）是层层回退：每层假设上一层可能不够；成本与适用场景不同。

统一认知：上下文是稀缺资源；每个决策都可问一句——「这个 token 是否值得留在上下文里？」

管理得当，可在数小时量级的会话里保持连贯；管理不当则会大量浪费 API 与质量。