Headroom：6.8 万星的 AI Agent 上下文压缩层，token 省一半答案不变

本文介绍 headroomlabs 开源的 Headroom（6.8 万 stars，Apache-2.0）——AI agent 的上下文压缩层：在工具输出、日志、文件、RAG 片段进入 LLM 之前先把它们压一遍，JSON 数据省 60–95% token，coding agent 省 15–20%，答案质量不变，账单明显变薄。

项目简介

agent 跑得越久，上下文里的垃圾越多：一次全量测试输出几万 token、一个日志文件塞满重复行、RAG 检索回来的大段原文——模型真正需要的往往只有那行 FATAL。Headroom 官方给的实测例子很直观：10,144 token 的工具输出压到 1,260 token，同样的 FATAL 错误照样被找到。

它本地运行、数据不出机器，而且可逆：压缩前的原文有缓存（CCR），需要时按需取回——这是它和"直接截断"类方案的本质区别。

核心特性

四种接入形态：
- 库：Python/TypeScript 里一行 compress(messages)
- 代理：headroom proxy --port 8787，零代码改动适配任何语言
- 包装：headroom wrap claude|codex|cursor|aider|... 一条命令包住主流 agent，unwrap 撤销
- MCP 服务器：headroom_compress/retrieve/stats 三个工具给任意 MCP 客户端
内容感知压缩管线：SmartCrusher 处理 JSON、CodeCompressor 走 AST、文本走 Kompress-v2-base 模型（HuggingFace 开源），按内容类型路由
输出 token 也砍：不只压"发进去的"，还修剪模型"写回来的"——去掉仪式性复述和例行步骤的深度思考
跨 agent 记忆：Claude、Codex、Gemini、Grok 共享一个记忆库，自动去重
headroom learn：挖掘失败会话，把纠正写进 CLAUDE.local.md（默认 gitignore）或 AGENTS.md/GEMINI.md 等

快速开始

bash

pip install headroom-ai        # Python
npm install -g headroom-ai     # 或 Node

# 包装现有 agent（例：Claude Code）
headroom wrap claude

# 或起本地代理，零改动接入
headroom proxy --port 8787

适用场景

coding agent 重度用户：15–20% 的 token 节省直接反映在订阅/API 账单上
长 agent 会话：工具输出累积是上下文爆炸的主因，压缩层让会话活得更快、更久
RAG 应用：检索片段先压后进模型，成本与延迟双降

注意事项

JSON 类数据压缩率最高（60–95%），代码与自然文本幅度不同，别拿单一场景外推
压缩有损：关键细节依赖 CCR 取回机制，工作流里要留好 retrieve 的入口
与部分 agent 的 wrap 集成依赖版本，升级 agent 后如异常先 unwrap 验证

项目链接

GitHub 仓库：https://github.com/headroomlabs-ai/headroom
在线文档：https://headroom-docs.vercel.app/docs
PyPI：https://pypi.org/project/headroom-ai/