headroomlabs-ai/headroom

Headroom 本地压缩 agent 上下文，四场景实测省 21%–57% tokens

Headroom 是本地运行的 LLM 上下文压缩层，在内容到达模型前压缩工具输出、日志、RAG 片段、文件和会话历史，数据不出本机。ContentRouter 按类型把 JSON 交给 SmartCrusher、代码交给 AST 感知的 CodeCompressor、文本交给 Kompress-v2-base；CacheAligner 标记会破坏前缀缓存的易变内容，CCR 本地保存原文供 headroom_retrieve 调取，输出侧另有 verbosity steering 与 effort routing 缩减写回开销。可通过 Python/TypeScript compress()、headroom proxy、headroom wrap 二十余种 agent 或 MCP 工具接入，并支持跨 agent 记忆与 headroom learn 挖掘失败会话写回 CLAUDE.md。官方四类真实 MCP 输出基准省 21%–57%，万 token 级 JSON 搜索结果的 p50 延迟 0.21 ms，GSM8K 不降分，SQuAD v2 与 BFCL 压缩下均 97%。限制是散文与已密集内容压缩有限、x86 无 AVX2 回退，企业级路由与安全需付费；项目以 Rust workspace 加 Python 扩展模块发布，支持 pip/uv/npm 安装。

1. 1本地代理，四种接入：库、wrap、proxy、MCP
2. 2GSM8K ±0.000，BFCL 达 97%（32% 压缩下）
3. 3CCR 可逆缓存原文，模型按需取回

为什么重要　不改代码即可对 Claude/Codex/Grok 等工作流统一省 token，数据留在本地；官方给出可复现基准与准确率对照。适合　跑 coding agent、想省 token 成本的智能体与工具链工程师

来源

github.com

发布

2026/10/21

作者

headroomlabs-ai