chopratejas/headroom 是一个给 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”后的成本、速度和答案质量。
小结
Headroom 是一个很典型的“上下文工程”工具。它不追求再造一个 Agent，而是站在 Agent 和 LLM 中间，把进入模型的内容压干净、压短，并保留取回原文的能力。
它适合已经在用 Claude Code、Codex、Cursor、Aider、Copilot CLI 或 MCP 工具的人。如果你的痛点是“模型上下文经常被日志和工具输出撑爆”，Headroom 值得试；如果你的问题只是模型能力不够，单纯压缩上下文就不一定能解决。