GitHub Trending #1：chopratejas/headroom —— AI Agent 上下文压缩层，Token 用量直降 60-95%

Fri, 05 Jun 2026 00:00:00 +0000

项目概览

仓库：chopratejas/headroom
语言：Python 76.9% · Rust 18.3% · TypeScript 2.7%
Stars：13,522（今日新增 +3,142）
Forks：858
许可证：Apache 2.0
最新版本：v0.23.0（2026-06-04）

在 AI Agent 遍地开花的今天，一个绕不开的痛点是 Token 成本。Agent 每执行一次工具调用，返回的原始输出动辄数万 token —— JSON 响应、日志堆栈、代码搜索结果、RAG 文本块，这些数据在进入 LLM 上下文窗口之前几乎不做任何筛选。headroom 正是为了解决这个问题而生：它是一个运行在本地、对 LLM 完全透明的上下文压缩层，在内容进入模型之前自动瘦身，实测可节省 47-92% 的 token 用量，且关键基准测试的准确率没有降低。

核心架构

你的 Agent / 应用
  (Claude Code, Cursor, Codex, LangChain, Agno, Strands, 你自己的代码…)
       │  prompts · tool outputs · logs · RAG results · files
       ▼
   ┌────────────────────────────────────────────────────┐
   │  Headroom   (本地运行 — 数据不出你的机器)            │
   │  ────────────────────────────────────────────────  │
   │  CacheAligner  →  ContentRouter  →  CCR            │
   │                    ├─ SmartCrusher   (JSON压缩)    │
   │                    ├─ CodeCompressor (AST感知)     │
   │                    └─ Kompress-base  (文本，HF模型) │
   │                                                    │
   │  跨Agent记忆  ·  headroom learn  ·  MCP Server     │
   └────────────────────────────────────────────────────┘
       │  压缩后的 prompt + retrieval tool
       ▼
LLM Provider  (Anthropic · OpenAI · Bedrock · …)

关键组件

组件	功能
ContentRouter	自动检测内容类型（JSON/代码/文本/日志），分派最优压缩器
SmartCrusher	通用 JSON 压缩：折叠数组、嵌套对象和混合类型
CodeCompressor	AST 感知压缩，支持 Python / JS / Go / Rust / Java / C++
Kompress-base	基于 HuggingFace 的专用压缩模型，用 Agent 轨迹训练
CacheAligner	稳定前缀引擎，使 Provider KV 缓存真正命中
CCR（可逆压缩）	原始内容存本地，LLM 可通过 `headroom_retrieve` 按需取回

五种使用模式

headroom 的设计哲学是「零摩擦接入」，提供从一行代码到一条命令的多层接入方式：

模式	使用方式	适用场景
Library（库）	`compress(messages)` — Python / TypeScript 内联调用	已有代码集成
Proxy（代理）	`headroom proxy --port 8787`	零代码改动，任意语言
Agent wrap	`headroom wrap claude\|codex\|cursor\|aider\|copilot`	开箱即用
MCP Server	`headroom_compress` / `headroom_retrieve` / `headroom_stats`	MCP 生态原生支持
SDK 中间件	`withHeadroom(new Anthropic())` / `wrapLanguageModel(...)`	框架级别集成

支持的 Agent 矩阵：

Agent	支持	特性
Claude Code	●	`--memory` · `--code-graph`
OpenAI Codex	●	与 Claude 共享记忆
Cursor	●	打印配置 — 粘贴一次即可
Aider	●	启动代理 + 启动 Aider
GitHub Copilot CLI	●	启动代理 + 启动，订阅模式
OpenClaw	●	ContextEngine 插件安装

实测性能

真实 Agent 工作负载的 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%

标准基准测试的准确率保留

基准	类别	基线准确率	Headroom准确率	差值
GSM8K	数学推理	0.870	0.870	±0.000
TruthfulQA	事实性	0.530	0.560	+0.030
SQuAD v2	问答	—	97%	19%压缩
BFCL	工具调用	—	97%	32%压缩

数学推理零损失，事实性问答甚至略有提升——这在压缩领域极为罕见。

竞品对比

产品	覆盖范围	部署方式	本地	可逆
Headroom	全部上下文（工具/RAG/日志/文件/历史）	代理·库·中间件·MCP	✅	✅
RTK	CLI 命令输出	CLI 包装器	✅	❌
lean-ctx	CLI 命令、MCP 工具	CLI·MCP	✅	❌
Compresr / Token Co.	发送到远程 API 的文本	托管 API	❌	❌
OpenAI Compaction	对话历史	Provider 原生	❌	❌

唯一同时做到本地运行 + 全上下文覆盖 + 可逆压缩的产品。

独特亮点

1. 跨 Agent 记忆（Cross-agent Memory）

Claude、Codex、Gemini 之间共享压缩记忆，自动去重，Agent 来源追踪。多 Agent 协作场景下这一步节省了大量重复上下文。

2. headroom learn

`1`	`headroom learn`

自动挖掘失败的 Agent 会话，分析失败原因，将修正写入 CLAUDE.md / AGENTS.md / GEMINI.md。等于 Agent 自己能「从错误中学习」。

3. 图像压缩

通过训练的 ML 路由器实现 40-90% 的图像压缩，这对多模态 Agent 场景尤其有价值。

4. SharedContext

在多 Agent 工作流中通过压缩上下文实现高效传递，避免每个 Agent 都重新加载完整上下文。

安装与快速上手

# 60 秒上手
pip install "headroom-ai[all]"

# 选择你的使用模式
headroom wrap claude          # 包装 Claude Code
headroom proxy --port 8787    # 零改动代理模式

# 查看节省效果
headroom perf

也支持 npm install headroom-ai（TypeScript）、Docker 部署和 pipx 安装。

总结

headroom 解决了一个真实且紧迫的问题：Agent 好用，但 Token 烧钱。它用一套精巧的压缩管道（ContentRouter → 多压缩器 → CCR 可逆存储），在保持准确率不变的前提下，将上下文体积压缩到原来的 1/5 到 1/12。

对于每天重度使用 AI Coding Agent 的开发者来说，headroom 几乎是必装工具。它不绑定任何特定 Agent 或 LLM Provider，本地运行不泄露数据，且提供了从库调用到 MCP 协议的完整接入矩阵。

一句话推荐：如果你每天跑 Agent 心疼 token，装上 headroom，同样的答案，省 60-95% 的钱。

LLM优化 on AI