Headroom：开源上下文压缩层斩获43K星，三阶段管道帮Agent削减60-95%的Token

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

Image

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