用AI Agent干活，token消耗像流水。工具输出一多，日志一长，上下文就爆了。Headroom就是来解决这个问题的。
项目是什么
Headroom是一个面向AI Agent的上下文压缩层，在内容进入LLM之前先做压缩处理。工具输出、日志、RAG检索结果、代码文件、对话历史，统统可以压。官方数据说能省60-95%的token，而且答案质量不降。
安装要求和过程
要求Python 3.10以上。安装本身很简单：
# 全量安装（推荐）
pip install "headroom-ai[all]"
# Node.js版本
npm install headroom-ai
# Docker
docker pull ghcr.io/chopratejas/headroom:latest
如果你想按需安装，可以只装指定模块：[proxy]、[mcp]、[ml]、[code]、[memory]、[relevance]、[image]，不用全量。装完直接 headroom wrap claude 就能把Claude Code包起来用，零代码修改。
核心功能
- 三种接入模式：当作Python/TypeScript库直接调用
compress()，或者跑一个本地代理让任意应用零改动接入，或者直接wrap主流AI编码工具（Claude Code、Cursor、Aider、Copilot都支持）。 - MCP服务器模式：提供了
headroom_compress、headroom_retrieve、headroom_stats三个工具，可以接进任何MCP客户端。对用Claude Desktop或者Cline的人很方便。 - 可逆压缩（CCR）：原始内容不会删，LLM觉得信息不够的时候可以通过工具调用把原始内容拿回来。不是有损压缩，是”按需取用”。
- 跨Agent共享内存：多个Agent（Claude、Codex、Gemini）可以共享同一套上下文存储，自动去重。做多Agent协作的人会喜欢这个功能。
- 自动学习：跑一下
headroom learn，它会去分析失败的会话，把修正规则自动写进 CLAUDE.md / AGENTS.md 这些配置文件。相当于Agent自己进化。
典型使用场景
先看数据。官方跑了一些真实工作负载的压缩测试：
| 工作负载类型 | 压缩前token | 压缩后token | 压缩率 |
|---|---|---|---|
| 代码搜索（100条结果） | 17,765 | 1,408 | 92% |
| SRE故障排查 | 65,694 | 5,118 | 92% |
| GitHub Issue分类 | 54,174 | 14,761 | 73% |
实际场景里，最爽的是这两个：
第一，长日志排查。SRE场景里把6万多token的日志压缩到5千多，压缩率92%，而且LLM给出的排查结论和质量没差。这意味着你可以用更便宜的模型、更短的上下文窗口，处理同样复杂的任务。
第二，RAG场景。把检索回来的大量chunk先压缩再塞给LLM，原本只能放5条chunk的上下文窗口，现在能放20条。检索质量上去了，token消耗反而下来了。
为什么推荐它
我试过几个类似的方案，RTK、lean-ctx，还有OpenAI自己出的压缩方案。Headroom最打动我的是”可逆压缩”这个设计。很多压缩方案是单向的，压完原始信息就没了，LLM判断需要细节的时候拿不到原文。Headroom的CCR机制让LLM可以按需取回原始内容，这个设计很聪明。
另外就是接入成本真的低。如果你用的是Claude Code或者Cursor，一条命令 headroom wrap claude 就搞定，不需要改代码，不需要重新配置，直接生效。对于已经用上这些工具的人来说，几乎是零成本的优化。
本周Headroom在GitHub周增长榜排第一，新增了13,000+ star。16.4k的总star数不算高，但增长曲线很陡，说明用过的人都在往上加。这种”开发者口碑传播”的项目，通常比营销驱动的项目更值得跟。
GitHub：github.com/chopratejas/headroom
官网文档：headroom-docs.vercel.app
协议：Apache 2.0（可商用）