GitHub 今日爆火！headroom：一个帮你省 60-95% Token 的 AI Agent 上下文压缩神器

GitHub 今日爆火！headroom：一个帮你省 60-95% Token 的 AI Agent 上下文压缩神器

上周我在跑一个 SRE 故障排查的 agent 任务时，眼睁睁看着 token 消耗蹭蹭往上涨------日志输出、工具调用结果、RAG 检索片段，每次对话上下文都在膨胀。一个排查任务跑下来，轻轻松松烧掉几万 token。

当时就在想：有没有什么东西能把这些冗余信息压一压，又不影响 agent 的判断？

然后今天刷 GitHub Trending，看到一个项目直接飙到日榜第一------headroom，12k+ stars，今天一天涨了 3000 多颗星。

点进去一看，好家伙，这不就是我想要的东西吗。

headroom 是什么？

简单说，headroom 是一个上下文压缩层，专门给 AI agent 用的。它能在你的 agent 把数据发给 LLM 之前，先对内容做一轮智能压缩------工具输出、日志、文件、RAG 检索结果、对话历史，全都能压。

关键数据：

• 60-95% 的 token 节省
• 准确率不变（GSM8K 数学题准确率 87%，压缩前后完全一致）
• 本地运行，数据不出你的机器
• 可逆压缩，原始数据随时能取回

用一句话概括：同样的答案，几分之一的 token。

实际效果有多猛？

官方给了一组真实 agent 工作负载的测试数据，我觉得挺有说服力：

工作负载	压缩前 Token	压缩后 Token	节省比例
代码搜索（100条结果）	17,765	1,408	92%
SRE 故障排查	65,694	5,118	92%
GitHub Issue 分类	54,174	14,761	73%
代码库探索	78,502	41,254	47%

SRE 故障排查那个场景，6.5 万 token 压到 5 千，省了 92%，而且 agent 的判断结果完全一致。这个数字说实话有点超出我的预期。

更关键的是，他们在标准 benchmark 上做了验证：

• GSM8K（数学推理）：准确率 87%，压缩后还是 87%，纹丝不动
• TruthfulQA（事实性问答）：准确率从 53% 提升到 56%（反而涨了 3 个点）
• SQuAD v2（阅读理解）：97% 准确率，同时压缩 19%
• BFCL（工具调用）：97% 准确率，同时压缩 32%

压缩不降准确率，甚至有些场景还提升了------这说明它的压缩算法确实"知道什么该留、什么该丢"。

它怎么做到的？

headroom 的核心架构分三层，每一层解决不同的问题：

第一层：ContentRouter（内容路由器）

收到内容后先判断类型------这是 JSON？代码？纯文本？日志？然后路由到对应的压缩器。不同类型用不同策略，比一刀切聪明多了。

第二层：三种压缩引擎

• SmartCrusher：专门处理 JSON。agent 的工具调用结果经常是几百行的 JSON，SmartCrusher 能识别结构、去重、合并相似条目，保留关键字段
• CodeCompressor：基于 AST（抽象语法树）的代码压缩。支持 Python、JS、Go、Rust、Java、C++。不是简单截断，而是理解代码结构后做语义级精简
• Kompress-base：他们自己在 HuggingFace 上训练的文本压缩模型，专门针对 agent 交互场景优化

第三层：CCR（可逆压缩）

这是我觉得最巧妙的设计。压缩后的内容不会把原始数据删掉------原始数据存在本地，LLM 如果觉得压缩后的信息不够，可以主动调用 headroom_retrieve 工具取回原文。

等于说给了 LLM 一个"展开详情"的按钮，需要的时候点一下就行。

还有一个CacheAligner模块，专门优化 Anthropic 和 OpenAI 的 KV Cache 命中率。这个对频繁调用的场景特别有用，能进一步降低延迟和成本。

怎么用？三种模式任选

headroom 支持三种集成方式，从零代码到深度集成都有：

模式一：Agent Wrap（最简单）

如果你用 Claude Code、Codex、Cursor、Aider 这些 coding agent，一行命令搞定：

headroom wrap claude      # 包装 Claude Code
headroom wrap codex       # 包装 Codex
headroom wrap cursor      # 包装 Cursor
headroom wrap aider       # 包装 Aider
headroom wrap copilot     # 包装 GitHub Copilot CLI

包装后 agent 的所有上下文都会自动经过压缩层，完全无感。

模式二：Proxy 代理（零代码）

启动一个本地代理，所有请求走代理自动压缩：

headroom proxy --port 8787

然后把你 agent 的 API endpoint 指向 http://localhost:8787 就行了。任何语言、任何框架都能用。

模式三：Library 库（深度集成）

Python：

from headroom import compress

compressed = compress(messages, model="claude-sonnet-4-5")

TypeScript：

import { compress } from 'headroom-ai';

const result = await compress(messages, { model: 'claude-sonnet-4-5' });

对于 Anthropic/OpenAI SDK 用户，还有更简洁的 wrapper：

from headroom import withHeadroom
from anthropic import Anthropic

client = withHeadroom(Anthropic())
# 之后所有调用自动压缩

跨 Agent 共享记忆

这个功能我觉得特别实用。如果你同时用 Claude Code 和 Codex（或者在不同项目里切换），headroom 提供了一个跨 agent 共享记忆的能力：

from headroom import SharedContext

ctx = SharedContext()
ctx.put("这个项目的数据库连接字符串是 xxx")
# 切换到另一个 agent 后
db_url = ctx.get("数据库连接字符串")  # 自动去重、自动关联

所有 agent 共享同一份记忆存储，自动去重，还记录每条记忆的来源 agent。对于多 agent 协作的场景简直是刚需。

headroom learn：从失败中学习

还有一个挺有意思的功能叫 headroom learn。它会分析 agent 的失败会话，自动提取教训，写入 CLAUDE.md 或 AGENTS.md：

headroom learn --agent claude --source ./sessions/

比如你的 agent 反复犯同一个错误，headroom learn 会检测到这种模式，然后在项目配置里加上一条规则，下次 agent 就不会再犯了。这个功能让我想起了 Cursor 的 rules，但 headroom 是自动化的。

安装和上手

Python 环境：

pip install "headroom-ai[all]"

Node.js 环境：

npm install headroom-ai

Docker：

docker pull ghcr.io/chopratejas/headroom:latest

支持 Python 3.10+，也支持按需安装子模块（proxy、mcp、ml、code、memory 等）。

和同类工具的对比

特性	headroom	RTK	lean-ctx	Compresr/Token Co.
压缩范围	全部上下文	CLI 输出	CLI + MCP	文本
部署方式	本地	本地	本地	云端 API
可逆压缩	✅	❌	❌	❌
跨 Agent 记忆	✅	❌	❌	❌
代码 AST 压缩	✅	❌	❌	❌
开源	✅	✅	✅	❌

headroom 的优势很明显：覆盖面最广、本地运行、可逆压缩、跨 agent 记忆。RTK 和 lean-ctx 也是好工具（headroom 甚至内置了 RTK），但 scope 小很多。至于 Compresr 这种云端方案，数据要传出去，很多人会有顾虑。

我的使用感受

试用了一下午，说几个真实感受：

好的方面：

1. wrap 模式是真的零配置 。headroom wrap claude 回车就能用，比我想象的简单太多
2. 压缩效果肉眼可见。跑同一个代码搜索任务，token 消耗从 1.7 万降到 1400，Claude 的回答质量完全没变
3. CCR 机制让人放心。压缩不是破坏性的，需要的时候随时能取回原文
4. 跨 agent 记忆很实用。我在 Claude Code 里配好的项目信息，Codex 里直接就能用

需要注意的：

1. 目前还在快速迭代中，API 可能会有 breaking change
2. Kompress-base 模型需要额外下载（pip install headroom-ai[ml]），第一次加载稍慢
3. 如果你只用单个 agent 且不关心 token 消耗，可能用不上它的全部功能

适合谁用？

• 日常使用 AI coding agent 的开发者：每天省下的 token 钱积少成多
• 同时使用多个 agent 的团队：跨 agent 共享记忆是杀手级功能
• 做 RAG 应用的同学：检索结果压缩能大幅降低成本
• 对数据隐私有要求的场景：本地运行，数据不出机器

不适合的情况：只用单个 provider 的原生 compaction、在沙箱环境里跑不了本地进程。

总结

headroom 解决了一个很实际的痛点：AI agent 的上下文越来越臃肿，token 消耗越来越大，但很多信息其实是冗余的。它用一套智能压缩管线，在保证准确率的前提下，把 token 消耗砍掉 60-95%。

最打动我的是它的设计哲学------不破坏原始数据，不依赖云端服务，不绑定特定框架。本地运行、可逆压缩、跨 agent 兼容，这三个点加在一起，让它在同类工具里显得特别靠谱。

项目今天刚冲到 GitHub Trending 第一，12k+ stars，社区活跃度很高。如果你日常在用 AI coding agent，强烈建议试试。

项目地址：github.com/chopratejas...