Headroom榜首：AI Agent上下文压缩神器省60-95%Token

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工作负载的测试数据，挺有说服力：

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、Ja va、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的优势很明显：覆盖面最广、本地运行、可逆压缩、跨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/headroom

来源：互联网