Headroom:开源上下文压缩层斩获43K星,三阶段管道帮Agent削减60-95%的Token
一个已累积 43K+ GitHub 星数的开源项目,用本地轻量管道把 Agent 发送给模型的上下文 Token 砍掉 60-95%,答案的准确性却不受影响。Hermes Agent 技术负责人 Teknium 已公开转发跟进,这件事被正式内置进 Hermes 只是时间问题。

43K
GitHub Stars
60-95%
Token 削减率
6
内置压缩算法
什么是Headroom?
Headroom 是一个开源的上下文压缩层,它会拦截 Agent 即将发送给大模型的全部内容——工具调用的返回、搜索片段、文件正文、RAG 结果、日志输出——并在这些材料进入模型之前进行针对性压缩。其核心思路是:让模型读到更少的干扰,回答的速度更快,花销也更低。
这个项目由 chopratejas 维护,采用 Python + Rust 实现,遵循 Apache 2.0 开源协议。上线不到半年就揽下 43K stars。
哪些工具已集成Headroom?
▸ Claude Code — 通过 headroom wrap claude 单条命令完成包装,同时附带记忆与代码图能力。
▸ Codex / Cursor / Aider / Copilot CLI — 同样支持 wrap 模式。
▸ OpenClaw — 可直接作为 ContextEngine 插件安装。
此外,Headroom 还提供了代理模式:headroom proxy --port 8787。开发者只需更换一个 baseURL,即可零侵入地让压缩生效。
三阶段压缩管道:如何实现60-95%的Token削减?
Headroom 的压缩管道分为三个阶段,每一阶段都可以独立开启或关闭,且失败时会静默回退到原始内容,不会破坏链路。
第一阶段 — CacheAligner
它把动态内容(例如日期、UUID、会话 Token)从 system prompt 中挪到末尾,利用固定前缀让 Anthropic/OpenAI 的 KV 缓存能够真正命中,从而提升推理缓存效率。
第二阶段 — ContentRouter + 压缩器集群
管道会自动判定内容类型,然后交给对应的压缩器:SmartCrusher 负责 JSON 的统计采样;CodeCompressor 进行 AST 感知的代码压缩;Kompress-base 则是一条纯文本的轻量 ML 压缩管线。异常、边界值和报错信息会在压缩时被无条件保留,避免丢失关键信号。
第三阶段 — CCR + Context Manager
压缩后的结果会写入本地缓存。CCR(Compress-Cache-Retrieve)机制确保原始数据始终留存在本地而不被清空,Agent 还可以通过 MCP 工具 headroom_retrieve 按需取回原文。上下文管理器则通过滚动窗口或智能评分,保证最终发给模型的总 Token 不会突破窗口上限。
实际性能表现
官方 benchmark 模拟了真实 Agent 负载,结果如下:
- 代码搜索 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 数学评测稳定在 0.870 ±0.000,TruthfulQA 真实性评测甚至从 0.530 提升到 0.560。
输出端Token成本同样可以削减
大部分压缩工具只关心输入端。但对于 Opus 级别模型,输出价格是输入价的 5 倍,而大量输出其实是开场白、重复粘贴的代码片段,以及例行步骤中的“深度思考”。Headroom 的代理模式可以在系统提示末尾附加“保持简洁、不重复上下文”的后缀,并在模型返回工具结果后自动降低 thinking effort。实测估算,输出端 Token 使用量大约能够减少 30%。
为何Hermes Agent开发者需要关注?
Teknium(Hermes Agent 联合创始人兼首席工程师)已对项目公开表示关注。在 Hermes 的架构里,存在多个非常适合接入压缩层的节点:
- 子代理
delegate_task返回的汇总上下文 - Cron 任务输出及历史 session 注入
- Skill 文件加载时的前置上下文
- Memory 和 session_search 涉及的持久化数据检索
- 工具调用结果的批量返回
对于用户来说,在 Agent 框架层面内置压缩层,远比各自部署代理方案来得可靠:不需要额外安装、配置代理或更换客户端,透明完成上下文压缩。
哪些场景适合立即使用,哪些可以观望?
现在就可以用的场景
- 每天运行 Agent 的长对话,工具调用输出累积超过 20K token
- 跨多个 Agent 工作,需要共享上下文并对记忆进行去重
- 偏重 JSON 的工作流:API 查询、数据库结果、搜索返回的批量输出
可以观望的场景
- 只进行短对话,上下文从未超过 10K token
- 仅使用单一提供商的原生压缩,且不需要跨 Agent 能力
- 工作在沙箱环境,本地无法运行额外进程
SOURCES
Headroom 项目 — github.com/chopratejas/headroom
Headroom 官方文档 — headroom-docs.vercel.app/docs
Hermes Agent 官方文档 — hermes-agent.nousresearch.com/docs