Headroom：AI Agent 的上下文压缩层

AI 编程工具用得越多，token 费用越高。上下文窗口就那么大，日志、工具输出、RAG 检索结果一股脑塞进去，很快就撑满了。Headroom 解决的就是这个问题。

Headroom 是一个本地运行的上下文压缩层，截获 AI Agent 发给大模型的所有内容，压缩后再送出去。实测数据：10,144 个 token 压缩到 1,260 个，诊断结果不变。

项目拿到了超过 23,000 个 Star，支持 Python 和 TypeScript 两种语言。

它能压缩什么

Agent 工作时产生的内容都可以压缩：工具调用的返回值、终端日志、RAG 检索到的文档片段、本地文件内容、对话历史。覆盖 JSON、代码、纯文本、图片等常见格式。

六种压缩算法

Headroom 内置了六种压缩器，根据内容类型自动选择：

SmartCrusher 处理 JSON 数据，把冗长的数组和嵌套对象精简到最小体积。CodeCompressor 基于 AST 分析，支持 Python、JavaScript、Go、Rust、Java、C++。Kompress-base 是在 HuggingFace 上训练的专用模型，针对 Agent 场景的文本压缩。CacheAligner 稳定 prompt 前缀，让 Anthropic 和 OpenAI 的 KV Cache 真正命中。图片压缩通过 ML 路由器实现，压缩率 40% 到 90%。CCR 负责可逆压缩，原始内容缓存在本地，大模型需要时可以随时取回。

四种接入方式

1. 库模式：Python 调用 compress(messages)，TypeScript 调用 await compress(messages, { model })，嵌入现有应用。
2. 代理模式：headroom proxy --port 8787，零代码改动，任何语言都能用。
3. Agent 包装：headroom wrap claude 一条命令搞定，也支持 Codex、Cursor、Aider、Copilot CLI。
4. MCP 服务端：提供 headroom_compress、headroom_retrieve、headroom_stats 三个工具，任何 MCP 客户端都能调用。

压缩效果

官方给出了几组真实工作负载的数据：代码搜索场景 17,765 token 压到 1,408，节省 92%；SRE 故障排查场景 65,694 压到 5,118，同样 92%；GitHub Issue 分类 54,174 压到 14,761，节省 73%。

准确率方面，GSM8K 数学基准压缩前后得分完全一致，TruthfulQA 事实性基准还略有提升。

跨 Agent 记忆

多个 Agent 之间可以共享压缩后的上下文。Claude、Codex、Gemini 各自工作的记忆会自动去重合并，避免重复压缩同一段内容。

headroom learn 命令可以从失败的会话中提取经验，自动写入 CLAUDE.md 或 AGENTS.md 等配置文件，下次遇到类似场景时 Agent 会参考这些修正。

安装

pip install "headroom-ai[all]"    # Python
npm install headroom-ai           # Node / TypeScript

然后选一种模式启动：

headroom wrap claude              # 包装 coding agent
headroom proxy --port 8787        # 代理模式，零改动

项目使用 Apache 2.0 开源协议，完整文档在 headroom-docs.vercel.app。

项目使用 Apache 2.0 开源协议，完整文档在 headroom-docs.vercel.app。