Headroom：为AI代理压缩上下文，削减50-90%的token成本

Headroom 是一个开源的上下文压缩层，致力于解决 AI 代理在与大语言模型（LLM）交互时 token 消耗过高的问题。该工具能够在内容到达 LLM 之前，对所有由 AI 代理读取的信息——包括工具输出、日志、RAG（检索增强生成）块、文件以及对话历史——进行压缩，从而显著降低 API 调用成本，同时保持答案的准确性。

Headroom 提供了多种灵活的使用方式。开发者可以将其作为 Python 或 TypeScript 库集成到现有应用中，通过 compress(messages) 函数调用；也可以使用代理模式 headroom proxy --port 8787 实现零代码集成；或者通过 headroom wrap 命令直接封装 Claude Code、Codex、Cursor、Aider 等流行编码代理。此外，Headroom 还支持 MCP（Model Context Protocol）服务器，方便与任何 MCP 客户端集成。

Headroom 的压缩机制基于内容路由和多种专用压缩算法。其 ContentRouter 组件能自动检测内容类型（如 JSON、代码、文本），并选择最优压缩器：SmartCrusher 适用于通用 JSON，CodeCompressor 以 AST（抽象语法树）方式压缩多种编程语言代码，Kompress-base 则是基于 HuggingFace 模型、针对代理追踪训练的高效文本压缩器。CacheAligner 组件通过稳定前缀模式，帮助提供商（如 Anthropic、OpenAI）的 KV 缓存实现更高命中率，进一步提升效率。一项突出特性是 CCR（可逆压缩），它确保原始数据永远不会被删除，LLM 可在需要时通过 headroom_retrieve 工具按需获取原始内容。

在性能表现上，Headroom 展示了令人印象深刻的压缩率。在真实代理工作负载测试中，代码搜索场景从 17,765 个 token 压缩至 1,408 个（节省 92%），SRE 事故调试从 65,694 压缩至 5,118（节省 92%），GitHub 问题分类从 54,174 压缩至 14,761（节省 73%）。在标准基准测试中，准确性不仅没有下降，反而在某些任务上略有提升：GSM8K 数学基准准确率保持 0.870，TruthfulQA 事实性基准从 0.530 提升至 0.560。Headroom 还提供了跨代理记忆共享功能，使多个代理（如 Claude、Codex、Gemini）可以共享上下文并自动去重，进一步提升协作效率。

Headroom 由 chopratejas 维护，采用 Apache 2.0 许可证。项目要求 Python 3.10 或更高版本，可通过 pip 或 npm 安装，也支持 Docker 部署。社区已通过该项目节省超过 600 亿 token，并设有实时排行榜跟踪节省情况。对于日常使用 AI 编码代理的开发者而言，Headroom 提供了一条无需更改代码即可大幅降低成本的捷径。