用 Claude Code、Cursor 这类 AI 编程工具多了，有没有发现一个烦人的问题：对话越用越卡，上下文越撑越大，每次请求都要等半天，账单也蹭蹭涨。特别是做代码搜索、翻日志排查问题的时候，光工具输出就能塞满整个上下文窗口。
Headroom 就是来解决这事的。它是一个开源的上下文压缩层，在你把内容发给 LLM 之前，先把工具输出、日志、RAG 结果、文件、对话历史统统压缩一遍——压缩率 60–95%，回答质量基本不变。
是什么
Headroom 是个 Python/TypeScript 库，也是代理和 MCP 服务器。跑在本地，数据不出你机器。它在你和 LLM 之间加了一层，所有发给模型的上下文经过压缩再出去。
作者叫 Tejas Chopra，今年 1 月上线的项目，6 个月拿到 27.6K GitHub Stars。最新版 v0.25.0 是 3 天前（6 月 12 日）发布的，迭代速度很快。
项目地址：github.com/chopratejas/headroom
核心优势
60–95% Token 压缩
不说虚的，直接看实测数据：
- 代码搜索（100 条结果）： 17,765 → 1,408 Token，省 92%
- SRE 故障排查： 65,694 → 5,118 Token，省 92%
- GitHub Issue 分类： 54,174 → 14,761 Token，省 73%
- 代码库探索： 78,502 → 41,254 Token，省 47%
而且不是无脑截断——压缩完的准确性在 GSM8K、TruthfulQA、SQuAD、BFCL 这些基准上基本做到无损失（GSM8K 完全持平，TruthfulQA 甚至略升 +3%）。
三种接入方式，总有一种适合你
1. 库模式： 在自己代码里直接调 compress(messages)，Python 和 TypeScript 都支持。一行代码搞定压缩。
2. 代理模式： headroom wrap claude，一行命令把 Claude Code、Codex、Cursor、Aider、Copilot CLI 全部套上一层压缩层。零代码改动。
3. MCP 服务器： 任何支持 MCP 的客户端都能用 headroom_compress、headroom_retrieve、headroom_stats 这三个工具。
6 种压缩算法自动路由
Headroom 不是「一刀切」压缩。它的 ContentRouter 会先判断内容类型，再选最合适的压缩器：
- SmartCrusher： 通用 JSON 压缩，数组、嵌套对象、混合类型通吃
- CodeCompressor： AST 感知的代码压缩，支持 Python、JS、Go、Rust、Java、C++
- Kompress-base： HuggingFace 上训练过的文本压缩模型，专门优化过 Agent 轨迹数据
- CacheAligner： 稳定前缀缓存，让 Anthropic/OpenAI 的 KV 缓存真正命中
- 图片压缩： ML 路由，40–90% 压缩比
- IntelligentContext： 评分制上下文裁剪，学得会哪些信息更重要
可逆压缩（CCR）
压缩了以后如果 LLM 需要看原文怎么办？Headroom 的 CCR（可逆压缩）机制会把原始内容缓存到本地，LLM 可以通过 headroom_retrieve 工具按需获取。既省了每次对话都传全文的钱，又不怕丢了信息。
跨 Agent 共享记忆
Claude Code 和 Codex 之间切换用？Headroom 帮你打通。它有个跨 Agent 记忆存储，共享上下文、自动去重。写了几轮 Claude Code 后切到 Codex 不需要从零开始。
headroom learn：从失败中学习
这功能挺有意思——headroom learn 会自动挖掘失败的 Agent 会话，找出哪里出错了，然后直接写进 CLAUDE.md 或 AGENTS.md，下次同样的坑就不踩了。
一秒上手
# 安装
pip install "headroom-ai[all]"
# 包装 Claude Code
headroom wrap claude
# 看看省了多少
headroom perf
# 或者跑个代理
headroom proxy --port 8787
就这么简单。
不是没有槽点
1. 只对上下文密集型工作流有明显收益。 纯粹的简单问答（比如问一句"今天天气怎么样"）完全没必要，压缩那几行文字反而增加延迟。
2. 本地跑需要 Python 3.10+。 有些旧系统可能得先升级 Python。
3. 跨 Agent 记忆还在快速迭代。 v0.25.0 刚加了差分网络捕获等新功能，API 还没完全稳定下来。
4. 仅限 AI 编码 Agent —— 不是通用产品。 如果你只用 ChatGPT 网页版聊天，不需要它。如果你是 Codex、Claude Code 或者 Cursor 的重度用户，收益最大。
5. 企业环境需要额外配置。 SSL 检查、代理、离线安装都有解决方法（文档写得很清楚），但确实不是即开即用。
跟同类怎么比
| 工具 | 范围 | 部署 | 本地 | 可逆 |
|---|
| Headroom | 所有上下文 | 库/代理/MCP | ✅ | ✅ |
| RTK | CLI 命令输出 | CLI 包装 | ✅ | ❌ |
| lean-ctx | CLI 命令 + MCP | CLI 包装 | ✅ | ❌ |
| Compresr / Token Co. | 纯文本 | 托管 API | ❌ | ❌ |
| OpenAI Compaction | 对话历史 | 提供商内置 | ❌ | ❌ |
Headroom 是唯一覆盖全场景 + 本地跑 + 可逆压缩的开源方案。RTK 他们也在用，作为管道的一部分整合进去了。
一句话总结
如果你天天用 AI 编码 Agent，并且觉得上下文撑、Token 贵、切来切去记忆不连贯——Headroom 是目前写得最完整的开源解决方案。27.6K Stars 说明了一切。
GitHub：github.com/chopratejas/headroom
文档：headroom-docs.vercel.app/docs
标签：#Headroom #上下文压缩 #AI编程工具 #ClaudeCode #Codex #Token优化 #Agent记忆 #开源 #MCP #本地优先
关注我，每期分享一个帮你省事的强大工具 🛠️