Headroom 是一个给 Claude Code、Codex、Cursor 等 AI Agent 做上下文压缩的工具。它解决的问题很现实：Agent 一边跑命令、一边读日志、一边搜索代码、一边塞 RAG 片段，很快就会把上下文窗口填满，成本和延迟一起上来。
Headroom 的思路是：在内容进入 LLM 之前，先把工具输出、日志、文件、RAG 片段和会话历史压缩一遍。README 里写的目标很直接：减少 60-95% token，同时尽量保持回答质量。
它解决什么问题
现在很多 Agent 工具不是模型不够聪明，而是上下文太脏：
grep、rg、日志查询一次返回几百上千行；- RAG 检索片段重复、冗余、格式混乱；
- JSON、stack trace、SQL 结果里有大量低价值字段；
- 多轮调试后，旧输出占着上下文不走；
- Claude Code、Codex、Cursor、Aider 等工具各自维护上下文，难以共享记忆。
Headroom 做的是“进入模型前的清洁工”。它不替代 LLM，也不替代 RAG，而是在 LLM 前面加一层压缩、路由、缓存和可回溯检索。
核心能力
从 README 看，Headroom 主要有几种使用形态：
- Library：在 Python 或 TypeScript 里直接调用
compress(messages)； - Proxy：通过
headroom proxy --port 8787做 OpenAI-compatible 代理； - Agent wrap：用
headroom wrap claude|codex|cursor|aider|copilot包一层现有 Agent； - MCP Server：提供
headroom_compress、headroom_retrieve、headroom_stats给 MCP 客户端使用； - Cross-agent memory：让 Claude、Codex、Gemini 等工具共享本地记忆并自动去重；
headroom learn：从失败会话里挖经验，写入CLAUDE.md或AGENTS.md；- Reversible compression：原文不删除，需要时可以通过检索工具取回。
这几个形态很关键。它不是只能嵌入代码里的 SDK，也不是只能当代理。你可以从最轻的 wrap 模式开始试，再决定要不要接到自己的应用里。
它怎么压缩
Headroom 的架构里有几个关键词：
- ContentRouter：识别内容类型，选择对应压缩器；
- SmartCrusher：偏向处理 JSON 等结构化内容；
- CodeCompressor：偏向处理代码和 AST；
- Kompress-base：用于文本压缩；
- CacheAligner：让 prompt 前缀更稳定，提高提供商 KV cache 命中率；
- CCR：保存原文，需要时再通过 retrieve 找回来。
换成人话说，它不是把所有内容都粗暴摘要成一段话，而是先判断内容类型，再选不同压缩策略。代码、JSON、普通文本、日志和 RAG 片段，压缩方式不应该一样。
快速安装
README 给出的安装方式很直接：
|
|
Python 侧需要 Python 3.10+。安装后可以先试这几个命令：
|
|
如果你用的是 MCP 客户端，可以走：
|
|
如果你只是想验证效果，最简单的是先跑 headroom perf，看它对典型工作负载能省多少 token。确认可用后，再把它接到 Claude Code、Codex、Cursor 或自己的 OpenAI-compatible 客户端里。
和普通摘要有什么区别
普通摘要最大的问题是不可逆。日志被总结成“数据库连接失败”，你就看不到原始错误码、时间戳、调用栈和上下文了。Agent 后面如果需要细节，只能重新查。
Headroom 的一个重点是 reversible：原始内容保存在本地，压缩后传给模型；如果模型需要原文，再通过 headroom_retrieve 取回。这个设计更适合调试、代码搜索和生产日志分析，因为这些场景经常需要回到细节。
当然，这也意味着你要管理本地存储和隐私边界。虽然 README 强调 local-first，但只要你把压缩后的内容发给云端模型，仍然要按自己的数据安全要求处理。
适合哪些场景
我觉得 Headroom 最适合这些场景：
- Claude Code、Codex、Cursor 经常因为工具输出太长而变慢；
- 用 Agent 分析大仓库，搜索结果和文件片段很容易爆上下文；
- SRE 排障时要把日志、trace、配置和命令输出交给模型看；
- 做 RAG 应用，检索结果冗余严重；
- 想在多个 Agent 工具之间共享本地记忆；
- 想把 MCP 工具接入已有 AI 工作流。
如果你只是偶尔问几句聊天，或者 prompt 很短，就不一定需要它。Headroom 的价值主要在“Agent 真正在干活”的时候出现。
使用时要注意什么
上下文压缩不是魔法。它能省 token，但也可能带来新问题：
- 压缩策略不合适时，模型可能拿不到关键细节；
- 代码和日志场景要测试 retrieve 是否可靠；
- 接代理模式时，要确认请求到底经过哪些本地和云端环节；
- 团队使用时，要定义好本地缓存、会话记录和敏感数据保留策略；
- 不要只看 token savings，也要看任务完成率和误判率。
我的建议是用真实任务测试，而不是只看 demo。比如拿一组历史 bug、CI 日志、RAG 查询和代码搜索任务，分别比较“直接喂模型”和“经过 Headroom”后的成本、速度和答案质量。
Claude Code 原生 Token 与缓存优化
Prompt Cache 缓存的不是文字本身
Prompt Cache 不是简单地把提示词字符串存起来。对 Transformer 模型来说，更关键的是前缀上下文经过注意力层计算后的 Key/Value 状态，也就是常说的 KV cache。
这意味着两个事实：
- 同一段上下文，只要前缀保持稳定，就可以在后续请求中复用一部分计算结果。
- 如果模型、工具定义、系统提示词或前缀消息发生变化，之前的缓存就可能无法复用。
Anthropic 官方文档也把失效层级概括为 tools -> system -> messages。工具定义变化会影响整段缓存，系统层变化会影响 system 和 messages，messages 层变化则主要影响消息缓存。
Claude Code 里还会额外涉及 CLAUDE.md、Skills、MCP、插件和子代理等上下文，所以实际使用时更容易踩到缓存失效点。
缓存杀手一：中途切换模型
切模型是影响最大的操作。
Prompt Cache 是按模型隔离的。Opus、Sonnet、Haiku 这类模型的结构和权重不同，同一段文本算出来的 KV cache 也不同。你在 Opus 里跑了很长上下文，再切到 Sonnet，并不能让 Sonnet 复用 Opus 的缓存。
这会带来一个反直觉结果：中途为了省钱切模型，可能反而让前面已经积累的缓存全部失效。原本可以按 cache read 价格读取的上下文，需要重新写入和计算。
更稳妥的做法是：
- 主对话尽量固定一个模型。
- 需要便宜模型处理支线任务时，用 subagent 隔离出去。
- 让支线代理完成搜索、探索、整理，再把结果摘要交回主对话。
这样主对话的长上下文尽量不动，缓存命中率更稳定。
缓存杀手二：中途新增 MCP 或重载插件
MCP 会向 Claude Code 提供工具。新增 MCP 服务器后，工具列表会变化，而工具定义处在上下文链条最左侧。
从 Prompt Cache 的角度看，工具列表一变，后面的 system 和 messages 都可能需要重新计算。尤其是 MCP 很多时，工具定义本身就可能占用大量 Token，缓存失效的代价会很明显。
不过有一个细节：Claude Code 通常在会话启动时读取 MCP 配置。你中途改了配置，当前 session 不一定立刻受影响。真正需要小心的是触发重新加载的动作，例如重启、恢复会话、重新加载插件或让工具列表重新组装。
建议是：
- 开始长任务前，一次性装好需要的 MCP。
- 不要做一半才发现缺工具，再安装并重载。
- 对大型 MCP 工具集，优先考虑按需加载或减少默认启用数量。
- 不常用的 MCP 不要长期挂在默认配置里。
如果工具定义稳定，Prompt Cache 才有长期命中的基础。
缓存杀手三：中途修改 CLAUDE.md
CLAUDE.md 是 Claude Code 的项目记忆文件，适合放构建命令、测试命令、架构约定、代码风格和项目注意事项。
它对 Claude Code 很有用，但也会进入上下文。官方帮助文档说明，CLAUDE.md 会在 session 开始时读取，并作为用户消息提供给 Claude；它也会使用 Anthropic 的 Prompt Cache。首次请求会按完整输入计费，后续请求如果在缓存有效期内命中，就按更低的 cache read 成本处理。
问题在于：CLAUDE.md 是内容寻址的。你一改文件内容，旧缓存就对不上了。
所以不要在长任务中途频繁改 CLAUDE.md。更好的方式是：
- 任务开始前先检查
CLAUDE.md是否够用。 - 把稳定规则写进去，把临时指令放在当前对话里。
- 如果只是一次性任务，不要为了临时需求修改长期记忆文件。
- 如果必须改，最好在一个阶段结束后再开始新 session。
CLAUDE.md 应该是稳定的项目说明，而不是每轮任务都改的便签。
缓存杀手四：中途安装或更新 Skills
Skills 也是上下文的一部分。安装新 Skill、更新 Skill，或者让 Skill 列表发生变化，都会让注入到会话里的上下文不同。
这类变化通常不会在当前 session 里立刻完整生效，而是在重新加载、恢复会话或新开会话时体现出来。问题是，一旦重新组装 messages，旧缓存就可能命中不了。
建议和 MCP 类似：
- 开始任务前先确认需要哪些 Skills。
- 同一类任务尽量固定 Skill 集合。
- 不要在一个长任务中途边做边装 Skill。
- 如果安装了新 Skill，最好把它当成新阶段的开始。
对经常做内容生产、代码审查、部署、翻译的工作流，可以把常用 Skills 固定下来，让上下文结构尽量稳定。
缓存杀手五：空闲时间超过 TTL
Prompt Cache 不是永久保存。常见默认有效期是几分钟级别，Anthropic 文档和 Claude Code 相关说明里都提到过 5 分钟左右的缓存窗口。超过 TTL 后，即使你发送完全一样的请求，服务端也可能已经清掉缓存。
这也是很多长任务用户的体感来源：刚才还很省，去喝杯咖啡回来，再发下一步，Token 又突然涨上去了。
长任务尤其容易遇到这个问题。你可能要看 Claude Code 的输出、检查文件、跑测试、思考下一步，这些操作一不小心就超过 5 分钟。
如果你的使用环境支持，可以在长任务前启用 1 小时 Prompt Cache TTL：
|
|
在 Windows PowerShell 里可以写成：
|
|
需要注意的是，1 小时缓存写入成本通常会高于 5 分钟缓存写入成本。它不适合所有短任务，但对大型代码库、长对话、复杂多步骤开发任务，往往比频繁缓存过期更划算。
怎么安排一次更省 Token 的 Claude Code 长任务
比较稳的流程可以这样做：
- 任务开始前选定模型，不要中途频繁切换。
- 提前启用需要的 MCP，不用的 MCP 先关掉。
- 检查
CLAUDE.md，只保留稳定、关键、长期有效的规则。 - 提前准备好本次任务需要的 Skills。
- 如果是复杂任务，考虑启用 1 小时 TTL。
- 把大任务拆成几个阶段，但每个阶段内部尽量保持上下文结构稳定。
- 需要探索支线问题时，用 subagent 或单独 session，不要污染主对话。
这套做法的目标不是绝对不让缓存失效，而是避免那些代价最高、最容易被忽略的失效。
一个简单判断标准
你可以用一句话判断某个操作是否危险：
这个操作会不会改变模型、工具定义、系统上下文或会话开头的固定消息？
如果答案是会，那它大概率会影响 Prompt Cache。越靠近上下文链条左侧，影响越大。
常见操作可以这样理解：
- 切模型：高风险，模型缓存隔离。
- 新增 MCP 或重载插件：高风险，工具列表变化。
- 修改
CLAUDE.md：中高风险，项目记忆变化。 - 安装 Skills：中高风险，注入上下文变化。
- 普通对话继续追问：低风险，主要追加 messages。
- 空闲超过 TTL：高风险，服务端缓存过期。
小结
Claude Code 的 Prompt Cache 优化，关键不是背参数，而是让会话前缀稳定。
模型不要随便切，MCP 和 Skills 不要边做边装，CLAUDE.md 不要当临时草稿频繁改，复杂任务尽量延长 TTL。只要这些基础动作稳定下来，Claude Code 在长任务里的 Token 成本和响应速度都会更可控。
最实用的一句话是：开始前配好，开始后少动。
小结
Headroom 是一个很典型的“上下文工程”工具。它不追求再造一个 Agent，而是站在 Agent 和 LLM 中间，把进入模型的内容压干净、压短，并保留取回原文的能力。
它适合已经在用 Claude Code、Codex、Cursor、Aider、Copilot CLI 或 MCP 工具的人。如果你的痛点是“模型上下文经常被日志和工具输出撑爆”，Headroom 值得试；如果你的问题只是模型能力不够，单纯压缩上下文就不一定能解决。
常见问题
Headroom 是什么？
Headroom 是一个 AI Agent 上下文压缩层，可以在工具输出、日志、文件、RAG 片段进入 LLM 之前先压缩，减少 token 消耗。
Headroom 怎么接入 Claude Code 或 Codex？
README 提供了 headroom wrap claude|codex|cursor|aider|copilot 这类接入方式，也可以通过 proxy 或 MCP Server 接入自己的工具链。
Headroom 和普通摘要有什么区别？
普通摘要通常是一次性压缩文本；Headroom 更强调 reversible，本地保留原文，需要细节时可以再通过检索取回。
什么时候不需要 Headroom？
如果你的任务很短、没有大量日志/搜索结果/RAG 片段，或者主要瓶颈是模型能力而不是上下文污染，Headroom 的收益可能不明显。