Headroom 深度调研报告

🎉 最新版本：v0.28.0（2026-06-29 发布，距今 1 天）
GitHub 仓库：https://github.com/headroomlabs-ai/headroom
PyPI：pip install headroom-ai[all]
npm：npm install headroom-ai
官方文档：https://headroom-docs.vercel.app/docs
项目主页：https://headroomlabs-ai.github.io/headroom/
Stars：54,377 ⭐ | Forks：3,903 | Watchers：167 | License：Apache 2.0 | 主语言：Python
Releases：28+ 个稳定版本（v0.21.x → v0.28.0，约 1 周一个版本）
Topics：agent · ai · anthropic · claude-code · compression · context-engineering · mcp · openai · rag · token-optimization · typescript 等 20 个
核心卖点：60–95% 更少 token、答案不变、可逆（CCR）、本地优先——给所有 AI agent 用的"上下文压缩层"
官方 KPI（docs 站 hero）：87% 平均 token 节省 · 100% 答案准确度 · 6 个压缩算法 · 100+ LLM provider
日期：2026-06-30 | 调研人：Hermes Agent ✨

一、项目概览

Headroom 是一个开源的LLM 上下文压缩层（context compression layer），定位为 "AI agents 的中间件"：在工具输出 / 日志 / RAG chunks / 文件 / 对话历史到达 LLM 之前先压缩掉 60–95% 的 token，模型照旧得到正确答案。

核心价值主张（README + 实测数据）：

60–95% 上下文 token 节省，对答案准确度无影响或更优（GSM8K ±0、TruthfulQA +0.03）
输出 token 也省（Opus 上输出 = 5× 输入）：消掉"Great, let me…"前置、把"读文件"这种常规动作的 thinking 调小
三种接入形态：library（Python/TS 内联）· proxy（端口级零代码）· MCP server
可逆（CCR, Cacheable Compressed Representation）：原文本地缓存，LLM 可调 headroom_retrieve 取回
跨 agent 共享内存：Claude Code ↔ Codex ↔ Gemini ↔ Aider 之间共享上下文，自动去重
内容感知路由：JSON 走 SmartCrusher、代码走 CodeCompressor（AST）、散文走自研的 Kompress-v2-base 模型
CacheAligner：稳住 prompt 前缀，让 Anthropic / OpenAI KV cache 真的命中，省缓存重算的钱
headroom learn：从失败会话里挖教训，自动写到 CLAUDE.local.md / CLAUDE.md / AGENTS.md / GEMINI.md

典型用户画像：每天重度用 Claude Code / Codex / Cursor 的个人开发者；想把 token 账单砍掉的企业工程团队（提供 self-hosted + managed 两种付费版）。

二、入口地址一览

类型	地址
GitHub 仓库	https://github.com/headroomlabs-ai/headroom
原 GitHub 仓库（重定向前）	`github.com/chopratejas/headroom`（原作者 / 现仍活跃贡献者）
官方文档站	https://headroom-docs.vercel.app/docs
项目主页	https://headroomlabs-ai.github.io/headroom/
PyPI 包	https://pypi.org/project/headroom-ai/（最新版 0.28.0，2026-06-29）
npm 包	https://www.npmjs.com/package/headroom-ai（⚠️ 当前仅 0.22.4，明显落后于 PyPI）
Docker 镜像	`docker pull ghcr.io/chopratejas/headroom:latest`
核心模型（HF）	chopratejas/kompress-v2-base —— 自研压缩模型
Discord 社区	discord.gg/yRmaUNpsPJ
企业版咨询邮箱	hello@headroomlabs.ai
License	Apache 2.0

三、实现原理

3.1 整体架构

Headroom 暴露一条统一的请求生命周期，三种接入形态（library / SDK / proxy）都遵循：

Setup → Pre-Start → Post-Start → Input Received → Input Cached
     → Input Routed → Input Compressed → Input Remembered
     → Pre-Send → Post-Send → Response Received

Headroom 实时压缩演示：10,144 tokens → 1,260 tokens，同一 FATAL 被找到 — Headroom Demo · 10,144 → 1,260 tokens（87.6% 节省）· 同一 FATAL 仍被定位

3.1b 数据流示意（架构图）

┌─────────────────────────────────────────────────────────────────────┐
│  Your agent / app                                                    │
│  (Claude Code · Cursor · Codex · LangChain · Agno · Strands · ...)   │
└────────────────────────────────┬────────────────────────────────────┘
                                 │  raw prompts · tool outputs · logs
                                 │  RAG hits · files · chat history
                                 ▼
        ┌────────────────────────────────────────────────────┐
        │  Headroom — runs locally, data never leaves you    │
        │ ─────────────────────────────────────────────────  │
        │                                                    │
        │   CacheAligner ──► ContentRouter ──► CCR (cache)   │
        │                       │                            │
        │                       ├─► SmartCrusher    (JSON)   │
        │                       ├─► CodeCompressor  (AST)    │
        │                       └─► Kompress-v2-base (text) │
        │                                                    │
        │   Cross-agent memory · headroom learn · MCP        │
        └────────────────────────────────┬───────────────────┘
                                         │  compressed prompt
                                         │  + headroom_retrieve tool
                                         ▼
        ┌────────────────────────────────────────────────────┐
        │  LLM provider  (Anthropic · OpenAI · Bedrock · …)  │
        └────────────────────────────────────────────────────┘

关键点：所有数据处理在本地；CCR 把原文留在本地缓存，LLM 看不到全量但能按需取回。

四层流水线（核心 Transform）：

CacheAligner — 稳定 prompt 前缀，让 provider KV cache 真正命中
ContentRouter — 检测内容类型（JSON / AST / prose / log / image），分发到对应压缩器
CCR（Cacheable Compressed Representation） — 原文本地缓存，压缩结果带 retrieval handle，LLM 按需 headroom_retrieve
压缩器矩阵：
- SmartCrusher：通用 JSON（嵌套对象、数组 of dicts、混合类型）
- CodeCompressor：AST 感知，支持 Python / JS-TS / Go / Rust / Java / C-C++ / Perl
- Kompress-v2-base：HuggingFace 自研模型，针对 agentic traces 训练
- Image 压缩：训练好的 ML router，40–90% reduction

3.2b ContentRouter 全量压缩器（docs 站权威列表）

内容类型	压缩器	怎么工作
JSON 数组 / 嵌套对象	SmartCrusher	统计方差分析：保留错误、异常、边界值，不靠硬编码规则
源代码	CodeCompressor	AST-aware（tree-sitter）：保函数签名、折叠函数体
纯文本	Kompress	ModernBERT token classification：去掉冗余 token，保语义
构建/测试日志	LogCompressor	保失败/错误/警告，过滤通过的噪音
搜索结果	SearchCompressor	按与查询相关性排序，保留 top 命中
Git diff	DiffCompressor	保留变更 hunks，丢掉未变上下文
HTML	HTMLExtractor	剥掉标签，提取可读内容
图片	Image ML Router	训练好的 ML 路由器，按内容自动选 resize/quality 权衡，40–90% 节省

Live-zone-only compression（docs 站强调的关键原则）：

Headroom 只压缩最新的内容块——最新的 user message 和 tool results。
不动：system prompt · tool definitions · 较早的对话轮次（也就是 provider cache 的"热区"）。

这就是为什么 CacheAligner 能稳定命中：被压缩的区域和 provider cache 的 prefix 边界对齐。README 提了 CCR + CacheAligner 但没明说这个边界策略——docs 站讲得更透。

3.2 接入形态

形态	命令 / API	典型场景
Library	`from headroom import compress`	Python/TS 应用内联
SDK Wrap	`withHeadroom(new Anthropic())` / `withHeadroom(new OpenAI())`	改一行代码透明启用
Proxy	`headroom proxy --port 8787`	任意 OpenAI 兼容客户端，零代码
CLI Wrap	`headroom wrap claude\|codex\|copilot\|cursor\|aider\|opencode\|cline\|continue\|goose\|openhands\|openclaw\|vibe`	命令行直接接管 AI coding agent
MCP Server	`headroom_compress` / `headroom_retrieve` / `headroom_stats`	任意 MCP 客户端
Vercel AI SDK	`wrapLanguageModel({ model, middleware: headroomMiddleware() })`	Vercel AI Gateway 用户
LiteLLM	`litellm.callbacks = [HeadroomCallback()]`	LiteLLM 代理用户
LangChain	`HeadroomChatModel(your_llm)`	LangChain 替换 LLM 包装
Agno / Strands	`HeadroomAgnoModel(...)` / Strands guide	多代理框架适配
ASGI middleware	`app.add_middleware(CompressionMiddleware)`	任何 ASGI 应用
Multi-agent	`SharedContext().put / .get`	跨代理压缩上下文传递

3.3 代码组织（推断）

headroom/providers/：每个 agent 一个子目录（claude/, codex/, copilot/, openclaw/, gemini/），注册表在 registry.py
headroom/wrap.py、client.py、cli/proxy.py、proxy/server.py：核心编排层，专注 lifecycle / sequencing / policy
headroom/compressors/：SmartCrusher / CodeCompressor / Kompress 各一份
headroom/ccr/：可逆压缩 + 本地缓存 store
headroom/memory/：跨 agent 共享内存 + auto-dedup
扩展点：on_pipeline_event(...)（lifecycle 观察）、compression hooks、proxy extensions

四、使用场景

场景	为什么需要 Headroom
Claude Code / Cursor 长时间会话	工具输出（RAG hits、grep 结果、stack trace）膨胀很快，Headroom 压在到达 LLM 之前
RAG 检索结果批量注入	100 条结果 17,765 tokens → 1,408（README 实测，92% 节省）
CI 中跑 AI agent	每条 LLM 调用都按 token 付费，按比例降本
多 agent 协作	SharedContext + cross-agent memory 共享上下文，无需每次重发
企业统一压缩层	self-hosted + SSO + 集中 dashboard + 版本统一分发
学习自己的偏好	`headroom learn --verbosity` 从历史会话自动判断"我有多啰嗦"
Proxy 模式快速验证	不改任何代码，跑 `headroom proxy --port 8787` + 改 base_url，立竿见影

Skip 它的情况（README 自陈）：

只用某个 provider 自带的 compaction，不跨 agent，也不需共享内存
沙箱环境无法跑本地进程
模型上下文窗口完全不是瓶颈

五、使用案例详解

5.1 案例 A：SRE 事件调试（92% 节省）

一次真实的 SRE 排查：调 100+ 次 kubectl get + 20+ 个 stack trace + 几 MB 日志，全部塞给模型诊断 FATAL 根因。

指标	Before	After
Tokens	65,694	5,118
节省	—	92%
结论正确性	找到 FATAL	同样找到 FATAL

5.2 案例 B：代码搜索 100 条结果

指标	Before	After
Tokens	17,765	1,408
节省	—	92%

CodeCompressor 在 AST 层做摘要，搜索结果保留可定位的"骨架 + 引用"，丢失几乎不影响下一步定位。

5.3 案例 C：GitHub issue triage

指标	Before	After
Tokens	54,174	14,761
节省	—	73%

issue 正文里大量样板（"Steps to reproduce"、"Expected"/"Actual"）可被识别压缩，正文保留关键 diff。

5.4 案例 D：代码库探索

指标	Before	After
Tokens	78,502	41,254
节省	—	47%

代码库探索需要保留较多上下文（类签名、依赖关系），节省率较低但仍可观。

5.5 输出 token 节省（实战估算）

$ headroom output-savings
# Reduction: 31.7%  (95% CI 27.7% … 35.7%)   [estimated]

Headroom 老实标注"estimate"——它不可能看到模型"原本会写什么"，所以给置信区间。开启 HEADROOM_OUTPUT_HOLDOUT=0.1 留 10% 控制组可得 measured 值。

六、Benchmark 数据汇总

6.1 节省率（输入 token）

工作负载	Before	After	节省
代码搜索（100 结果）	17,765	1,408	92%
SRE 事件调试	65,694	5,118	92%
GitHub issue triage	54,174	14,761	73%
代码库探索	78,502	41,254	47%
官方宣称范围	—	—	60–95%

6.2 准确度保留

基准	类别	N	Baseline	Headroom	Delta
GSM8K	数学	100	0.870	0.870	±0.000
TruthfulQA	事实	100	0.530	0.560	+0.030
SQuAD v2	QA	100	—	97%	19% 压缩
BFCL	工具	100	—	97%	32% 压缩

复现命令：python -m headroom.evals suite --tier 1

6.3 节省可视化（README 截图）

Headroom savings dashboard 截图：输入/输出 token 节省与 estimated 置信区间 — headroom dashboard · 实测的输入/输出 token 节省（estimated / measured）

官方演示：10,144 → 1,260 tokens，同一条 FATAL 被找到。这是项目核心叙事之一——省 token 不丢信息。

七、新增特性（v0.21 → v0.28 时间线）

版本	日期	关键特性
v0.28.0	2026-06-29	`--disable-kompress-fallback` 还原 legacy PASSTHROUGH；持续 bug 修复（pricing 解析 provider prefix / MCP lifetime totals）
v0.27.0	2026-06-22	`headroom doctor` 安装诊断；output savings CI；OpenCode native providers + transport plugin
v0.26.0	2026-06-16	Copilot BYOK provider wrapper + CLI 支持；KV cache 对齐 + tool search
v0.25.0	2026-06-12	Differential network capture harness（基准测试基础设施）
v0.24.0	2026-06-09	`headroom perf --format {text,json,csv}`；cache prefix 工具化
v0.23.0	2026-06-04	GitHub Copilot subscription mode——本地代理转发到 Copilot hosted API
v0.22.4	2026-06-01	Wrap CLI 扩展：cline / continue / goose / openhands；tokens_saved_rtk data plane
v0.22.2	2026-05-20	memory IDs 暴露给 auto-tail + memory_list tool
v0.21.x	5 月	连续 30+ 个快速迭代（0.21.30 → 0.21.38），主要为稳定性

近期 commit 亮点（来自最近 20 个 commit）：

fix(proxy): strip Codex lite header from OpenAI WebSockets（v0.28 周边）
docs: sync README + benchmarks with code (drop retired IntelligentContext/RollingWindow)——退役组件清晰记录
fix(bedrock): add boto3 1.41 + CRT for aws login credentials——AWS Bedrock 支持完善
fix(packaging): move hnswlib to optional [vector] extra so [all] needs no C++ toolchain——解决安装门槛
fix(proxy): bind before eager preload / offload /v1/compress to compression executor——启动鲁棒性 + 防事件循环阻塞

八、Cloud Providers（docs 站完整列表）

Headroom 直接支持 5 类 backend，加上 LiteLLM 转发可触达 100+ provider：

headroom proxy                                  # 默认：Anthropic / OpenAI 直连
headroom proxy --backend bedrock --region us-east-1    # AWS Bedrock
headroom proxy --backend vertex_ai --region us-central1 # Google Vertex AI
headroom proxy --backend azure                          # Azure OpenAI
headroom proxy --backend openrouter                     # OpenRouter (400+ models)

通过 LiteLLM 间接触达 100+ provider：

Provider	类型	典型场景
Together	托管多模型	开源模型托管
Groq	超低延迟推理	对延迟敏感的应用
Fireworks	托管推理	开源模型 + 高 QPS
Ollama	本地推理	完全离线 / 数据不出本机
vLLM	自托管	团队私有部署

九、Observability（docs 站独有）

相比 README，docs 站显式列出更多可观测能力：

能力	作用
Prometheus endpoint	metrics 暴露给标准监控栈（Grafana 等）
Per-request logging	每条请求的压缩率、延迟、token 节省
Cost tracking	按 model 单价实时算钱（依赖 LiteLLM pricing）
Budget limits	设上限防爆预算——README 没提，docs 站独有
Pipeline timing breakdowns	每阶段（CacheAligner / Router / Compressor）的耗时拆解，便于定位瓶颈

十、Persistent Memory 细节

docs 站给出更清晰的分层：

四层作用域：user（跨用户所有会话）/ session（单次会话）/ agent（单个 agent 实例）/ turn（单个 turn）
后端：SQLite（默认）+ HNSW（optional `[vector]` extra，需 C++ toolchain）——用于语义检索
跨会话存活：Headroom proxy 重启不丢

十一、快速上手

11.1 三步上手（README 推荐路径）

# 1) 安装
pip install "headroom-ai[all]"          # Python
npm install headroom-ai                 # Node / TypeScript

# 2) 选一种模式
headroom wrap claude                    # wrap 一个 coding agent
headroom proxy --port 8787              # 零代码 drop-in proxy
# 或者：from headroom import compress    # 内联库

# 3) 验证
headroom doctor                         # 健康检查
headroom perf                           # 看压缩率
headroom dashboard                      # 实时 dashboard（需 proxy 在跑）

11.2 Granular extras（按需装）

[proxy] · [mcp] · [ml]（Kompress-v2-base）· [code] · [memory]
[vector]：HNSW 后端，需要 C++ toolchain，不在 [all] 里
[relevance] · [image] · [agno] · [langchain] · [evals]
[pytorch-mps]：Apple GPU 上把 memory embedder offload 出去

需要 Python 3.10+。

11.3 Proxy 模式（最快的体验方式）

headroom proxy --port 8787
# 然后把 client 的 base_url 改成 http://localhost:8787/v1
# 比如 Claude Code: ANTHROPIC_BASE_URL=http://localhost:8787
# 比如任何 OpenAI 兼容客户端: OPENAI_BASE_URL=http://localhost:8787/v1

11.4 跨代理共享内存 + learn

# 把 Codex / Cursor / Aider 都 wrap 进来后，跨 agent 自动共享上下文 + 自动 dedup
headroom learn --verbosity            # 预览你"啰嗦度"基线（dry run）
headroom learn --verbosity --apply    # 写到 CLAUDE.local.md（默认 gitignored）

11.5 Copilot CLI 订阅模式（v0.23+）

headroom copilot-auth login
headroom wrap copilot --subscription -- --model gpt-4o

11.6 升级 & 容器

headroom update          # 自动检测 pip/pipx/uv tool
headroom update --check  # 仅报告
docker pull ghcr.io/chopratejas/headroom:latest

11.7 企业 SSL 检测环境

若 pip install 报 CERTIFICATE_VERIFY_FAILED（公司 MITM 代理）：

# 先装 Rust 让 maturin 不走 TLS 拉 rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh && rustup default stable
# 或直接用预编译 wheel（Windows/Linux x86_64 & aarch64/macOS Apple Silicon）
pip install --only-binary headroom-ai headroom-ai

# Python 3.13 strict mode 报错（Basic Constraints not critical）：
HEADROOM_TLS_STRICT=0 headroom proxy --port 8787

十二、与 Hermes Agent 的关系

维度	分析
定位	Headroom 是"上下文压缩层"；Hermes Agent 是"通用 AI agent + Skill 生态"。两者不重叠，是互补关系。
直接集成	Hermes Agent 调外部 LLM 时，可在 SDK 层套 `withHeadroom(...)` 或在 Hermes 自己的 LLM client 上挂一个 `headroomMiddleware()`。
间接收益	Hermes 的 Skill 调用经常返回长 JSON / 日志 / 文件内容（典型的压缩场景）；Headroom 能把这些工具输出在到达上游模型前压 60–95%。
Memory 联动	Headroom 的 cross-agent memory + Hermes 的 Skills 长期记忆可以互为补充：Headroom 负责"对话内的上下文"，Hermes Skills 负责"跨会话的方法论/偏好沉淀"。
可能的整合点	(a) Hermes 启动时检测 Headroom proxy 是否在 `:8787`，自动把 LLM base_url 切过去；(b) 写一个 `headroom-stats` Skill，复用 `headroom_stats` MCP tool；(c) 利用 `headroom learn` 把 Hermes 自己失败 session 写成 `AGENTS.md` 补丁。

十三、总结

Headroom 是什么：一个成熟的、生产就绪（v0.28，3 周内 8 个稳定版本）的 LLM 上下文压缩层，覆盖 input + output token、双向（Python + TypeScript）、三种接入（library / proxy / MCP）。

为什么值得关注：

真省钱：60–95% input 节省 + 30% output 节省（estimate），对答案准确度 ±0 或更优——README 给的数据是项目最硬的卖点。
真省事：proxy 模式一行命令就能上手，零代码改造；14 个 coding agent 已支持 wrap。
真可逆：CCR 让 LLM 能取回原文——比"黑盒压缩 + 砍掉信息"路线安全得多。
真现代：Kompress-v2-base 是项目自研的 HuggingFace 模型（专门为 agentic traces 训练），CacheAligner 解决 KV cache 命中问题。
真开源：Apache 2.0；个人 / 团队 / 企业都有版本。

风险与注意：

npm 版本（0.22.4）显著落后于 PyPI（0.28.0），如走 Node 路径建议关注 release 同步
开源核心 + 闭源企业版的模式清晰，需评估团队规模是否需要 self-hosted 服务
ZSR / 真·Retrival 等高压缩比场景需测试 CCR 的延迟和成本

一句话定位：Headroom = "AI agent 的 ProxySQL" —— 模型不变、答案不变、token 砍掉大半。

调研参考：GitHub README · 官方文档 · PyPI · npm · 28 个 Releases · 20 个最新 commits · Apache 2.0

调研时间：2026-06-30（北京时间） · 数据时点：GitHub API pulled at 2026-06-30 21:55 UTC