在你的数据和模型之间的一次挤压

Headroom 是给 AI 智能体的上下文压缩层。它在你的智能体读取的一切,工具输出、日志、RAG 块、文件、对话历史,到达 LLM 之前压缩它们,号称少 60 到 95% 的 token、答案不变。README 的例子是一个 10,144 token 的输入被压到 1,260,却仍然浮出同一行 FATAL。前提是:填满上下文窗口的大部分,是少数承重 token 周围的低价值噪声,而把噪声挤掉在答案质量上几乎免费。

让它不只是一招的,是那个可逆设计。原文从不删除;在它称为 CCR 的机制下,模型能按需取回全文。所以压缩不像截断那样有损,它是延迟的:智能体看到一个紧凑视图,只在真正需要时把细节拉回来。Headroom 还出厂带六种压缩算法、而非一个固定变换,于是你能为某个工作负载调节挤压的激进程度。这个可逆存储还兼作安全网:万一压缩丢掉了模型后来需要的东西,原文只在一次取回之外、而非永久消失。

四种接入方式

Headroom 刻意在形态上灵活,这也是它易于采纳的主要原因:

  • 库:在 Python 或 TypeScript 里内联调用 compress(messages)。
  • 代理:跑 headroom proxy --port 8787,把任意客户端指向它,零代码改动、任意语言。
  • Agent wrap:headroom wrap claude|codex|cursor|aider|copilot 一条命令包住一个编程智能体。
  • MCP server:headroom_compress、headroom_retrieve、headroom_stats,供任意 MCP 客户端。

它还维护一个跨智能体的记忆存储,在 Claude、Codex、Gemini 间共享、自动去重,而 headroom learn 挖掘失败的会话、把纠正写进你的 CLAUDE.md 或 AGENTS.md。

安装

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

然后挑一种形态:headroom proxy --port 8787 做即插代理、headroom wrap claude 包住一个智能体,或 headroom mcp install 走 MCP 原生路径。

README 没摆在前头的那个取舍

这是值得带走的洞见,而它直接来自 issue 区:压缩会和 prompt 缓存打架。讨论最热的 open issue 是缓存命中率大幅下降。服务商按稳定的 prompt 前缀缓存,而如果 Headroom 重写了上下文,那个前缀就变了,于是之前缓存的 token 未命中、被按全价(有时更高)重新计费。于是净 token 成本是一场赛跑:压缩省下的,对上失去缓存命中所花的。在围着一个庞大、稳定、被缓存的上下文搭的工作负载上,激进压缩可能打平甚至更糟;而在被新鲜、不可缓存的工具输出主导的工作负载上,它是明显的赢。测你自己的流量,别假设那个 60 到 95 的数字净落得下来。

第二个报告的坑:Codex 代理路径对一些用户弄坏了 OpenAI 认证。如果你经代理包住 Codex、认证失败,那是个已知帖子、不只是你这端的配置错。截至 2026-06 有 227 个 open issue、发版频繁(2026 年 6 月 v0.24.0),它快速移动;稳定管线就钉死一个版本。

Headroom 与 LLMLingua 的对比

headroomLLMLingua
Stars21,1446,272
形态库、代理、agent wrap、MCP研究库
可逆是,按需取回否
侧重智能体集成的上下文压缩prompt 压缩

计数取自 GitHub,截至 2026 年 6 月。LLMLingua 是知名的 prompt 压缩研究项目,核心技术强,但作为一个你自己接线的库来用。Headroom 与众不同的押注是多种即插形态、可逆的按需取回模型,以及直接的智能体集成。如果你想要一个可在其上构建的、被研究过的压缩算法,选 LLMLingua;如果你想要以最少代码接进一个运行中智能体的压缩,选 Headroom。

相关

要「预索引代码、让智能体少 grep」这种互补的 token 节省,见 CodeGraph。要在上游把文档转成紧凑、可喂 LLM 的文本,见 MarkItDown。想看还有什么在往上爬,见 LLM 工具、每日速报和周报。

FAQ

Headroom 压缩什么? 工具输出、日志、RAG 块、文件和对话历史,在它们到达 LLM 之前,据称削减 60 到 95% 的 token。

压缩有损吗? 它可逆。原文保留、模型能按需取回全文,所以细节是被延迟、而非丢弃。

它真能降低我的账单吗? 不总是。压缩会降低 prompt 缓存命中率,而失去缓存命中要花 token,所以在缓存重的工作负载上,先测净值再假设是赢。

怎么加它? 装 headroom-ai,然后作为库、代理(headroom proxy)、agent wrap(headroom wrap)或 MCP server 使用。