Headroom — GitHub 仓库首页，README 首屏演示把一次 SRE 排查的 55,957 token 上下文压到 24,340 token。

Headroom GitHub 仓库首页

Headroom 是一个开源的 AI Agent 上下文压缩层。它在提示词送进大模型之前，先把工具输出、日志、RAG 片段、文件和对话历史里的冗余压掉——官方口径是编码类 Agent 省约 20% token、JSON 类负载省 60–95%，而模型拿到的答案不变。压缩全程在本机完成，提示词和文件内容不会为了压缩被上传。

它压的不是对话，是 Agent 读到的东西

用编码 Agent 跑长会话的人，token 成本往往不是花在对话本身，而是花在 Agent 一路读到的工具输出上：一次代码检索返回上百条结果、一次事故排查灌进几万 token 的日志、一次仓库探索把半个文件树读进来。这些内容高度重复，但常见的处理要么不碰它们，要么用有损摘要把关键行一起丢掉。

Headroom 的取舍是：只压冗余，不丢信息。结构化的重复内容（JSON 数组、日志行、源码）做无损或可逆压缩，已经压无可压的散文基本不动；原文缓存在本地，模型需要时可按需取回。

实测数据

官方给出四组可复现场景（指定随机种子、离线跑）：

场景	压缩前	压缩后	节省
代码检索（100 条结果）	17,199	13,597	21%
SRE 事故排查	55,957	24,340	57%
代码库探索	58,801	33,895	42%
GitHub issue 分类	46,067	32,429	30%

压缩本身的开销可以忽略：10K token 的 JSON 检索结果 p50 只有 0.21 毫秒，100K token 时 1.4 毫秒，不会出现在 Agent 的响应延迟里。

准确率方面，官方跑了一组基准：GSM8K 数学压缩前后都是 0.870；TruthfulQA 从 0.530 到 0.560（100 样本下落在置信区间内，属于「测不出差异」而非提升）；SQuAD v2 在 19% 压缩率下保持 97%，BFCL 工具调用在 32% 压缩率下保持 97%。

内部机制

请求进来后依次经过几个部件：ContentRouter 判断内容类型并选择对应的压缩器，SmartCrusher 处理 JSON（保留错误项、统计上的异常值和首尾边界），CodeCompressor 做 AST 级代码压缩（支持 Python、JS/TS、Go、Rust、Java、C/C++、Perl），Kompress-v2-base 是面向散文的开源模型。CacheAligner 只标记会破坏服务商 KV-cache 前缀的易变内容，不改写提示词；CCR 把原文存在本地，模型可以随时调用 headroom_retrieve 取回全文。

和别的方案差在哪

	覆盖范围	部署方式	本地	可逆
Headroom	全部上下文——工具、RAG、日志、文件、历史	代理 · 库 · 中间件 · MCP	是	是
托管式压缩 API	主要是文本	调用对方接口	否	否
服务商原生压缩	仅对话历史	平台内置	否	否

五种接入方式

库：Python / TypeScript 里直接 compress(messages)，嵌进自己的应用
代理：headroom proxy --port 8787，零代码改动，任何语言都能接
包裹 Agent：headroom wrap claude|codex|cursor|aider|opencode|… 一条命令套住现成的编码 Agent，headroom unwrap 撤销
MCP 服务：给任意 MCP 客户端提供 headroom_compress / headroom_retrieve / headroom_stats
框架集成：LangChain、Agno、Strands、LiteLLM、Vercel AI SDK 等都有现成挂载点

此外还有两项周边能力：跨 Agent 共享记忆（Claude、Codex、Gemini、Grok 共用一个存储并自动去重），以及 headroom learn——从失败会话里挖出教训，写回 CLAUDE.md / AGENTS.md 之类的项目文件。

适用场景

每天跑编码 Agent、想省 token 又不想改业务代码的团队
同时用多个 Agent（Claude Code、Codex、Cursor……），希望它们共享一份记忆
需要对压缩可逆——原文随时能取回，而不是被摘要永久替换

不太适合

只用对话、不产生大量工具输出的轻量场景：短对话、纯散文、已经很密的负载，压缩率很低甚至为零
只用某一家服务商的原生压缩、且不需要跨 Agent 记忆的场景
运行环境不允许本地起进程的沙箱

安装

# Python（自带 headroom CLI）
uv tool install --python 3.13 "headroom-ai[all]"
# 或
pip install "headroom-ai[all]"

# 仅 TypeScript SDK（不含 CLI）
npm install headroom-ai

装好后 headroom doctor 自检、headroom dashboard 看实时省下的 token。

下一步

仓库：https://github.com/headroomlabs-ai/headroom
文档与快速上手：https://docs.headroomlabs.ai/docs
许可证：Apache 2.0（Python 实现，仓库创建于 2026 年 1 月，当前 star 约 7.2 万）

Headroom | AI Agent 的上下文压缩层 · 同答案、少 token