AI Agent 的 context 压缩层。压缩 LLM 读取的一切——工具输出、日志、RAG chunk、文件、对话历史——压缩前送入模型。相同答案，极少 token。48.6k stars。
核心定位
- 口号：60–95% fewer tokens · library · proxy · MCP · 6 algorithms · local-first · reversible
- 本质：在 Agent/App 与 LLM provider 之间插入本地压缩层，拦截并压缩所有 prompt 内容
- 设计原则：本地运行（数据不出境）、可逆（CCR 原始数据可随时检索）、通用（覆盖所有内容类型）
使用模式
| 模式 | 命令/调用 | 适用场景 |
|---|---|---|
| Library | compress(messages) | Python/TypeScript 内联，精细控制 |
| Proxy | headroom proxy --port 8787 | 零代码修改，任意语言任意 Agent |
| Agent wrap | headroom wrap claude|codex|cursor|aider | 一条命令包裹 Coding Agent |
| MCP server | headroom mcp install | MCP 原生客户端 |
压缩管道架构
Your Agent / App
│
▼
┌─────────────────────────────────────────────┐
│ Headroom (本地运行) │
│ CacheAligner → ContentRouter → CCR │
│ ├─ SmartCrusher (JSON) │
│ ├─ CodeCompressor (AST) │
│ └─ Kompress-base (text, HF)│
│ Cross-agent memory · headroom learn · MCP │
└─────────────────────────────────────────────┘
│
▼
LLM provider (Anthropic · OpenAI · Bedrock…)
核心组件：
- ContentRouter：检测内容类型，选择对应压缩器
- SmartCrusher：通用 JSON 压缩（数组/嵌套对象/混合类型）
- CodeCompressor：AST 感知，支持 Python/JS/Go/Rust/Java/C++
- Kompress-base：HuggingFace 模型，在 agentic traces 上训练
- CacheAligner：稳定 prefix，让 provider KV cache 真正命中
- CCR：可逆压缩，原始内容本地缓存，LLM 可按需检索
- IntelligentContext：基于重要性评分的上下文 fitting
实测压缩率
| 工作负载 | 压缩前 | 压缩后 | 节省 |
|---|---|---|---|
| 代码搜索（100 结果） | 17,765 | 1,408 | 92% |
| SRE 事故调试 | 65,694 | 5,118 | 92% |
| GitHub issue 分类 | 54,174 | 14,761 | 73% |
| 代码库探索 | 78,502 | 41,254 | 47% |
精度保持（标准 benchmark）：
- GSM8K：0.870 → 0.870（±0.000）
- TruthfulQA：0.530 → 0.560（+0.030）
- SQuAD v2：97%（19% 压缩）
- BFCL（工具调用）：97%（32% 压缩）
Output Token 缩减
不仅压缩发送的 prompt，也压缩模型写回的 output（Opus 级模型 output 成本是 input 的 5×）：
- Verbosity steering：在 system prompt 末尾追加”简洁”指令（不破坏 cache）
- Effort routing：tool result 续接时降低 thinking effort，新问题/错误保持全力
- headroom learn —verbosity：自动从历史会话学习用户偏好的简洁程度
export HEADROOM_OUTPUT_SHAPER=1
headroom proxy --port 8787跨 Agent 记忆
- SharedContext：多 Agent 工作流之间传递压缩上下文
- Cross-agent memory：Claude/Codex/Gemini 共享存储，自动去重，带 agent provenance
- headroom learn：挖掘失败会话，自动写修正到
CLAUDE.md/AGENTS.md/GEMINI.md
Agent 兼容性
| Agent | wrap 支持 | 备注 |
|---|---|---|
| Claude Code | ✅ | --memory · --code-graph |
| Codex | ✅ | 共享 memory |
| Cursor | ✅ | 打印配置粘贴一次 |
| Aider | ✅ | 启动 proxy + 启动 Agent |
| OpenClaw | ✅ | 以 ContextEngine plugin 安装 |
| OpenCode | ✅ | 注入配置 + 启动 |
框架集成
| 框架 | 接入方式 |
|---|---|
| Anthropic/OpenAI SDK | withHeadroom(new Anthropic()) |
| Vercel AI SDK | wrapLanguageModel({ model, middleware: headroomMiddleware() }) |
| LangChain | HeadroomChatModel(your_llm) |
| Agno | HeadroomAgnoModel(your_model) |
| LiteLLM | litellm.callbacks = [HeadroomCallback()] |
| ASGI | app.add_middleware(CompressionMiddleware) |
安装
# Python
pip install "headroom-ai[all]"
# Node / TypeScript
npm install headroom-ai
# Docker
docker pull ghcr.io/chopratejas/headroom:latest可选 extras：[proxy] [mcp] [ml]（Kompress-base）[code] [memory] [image] [langchain] [agno]
与同类工具对比
| 覆盖范围 | 部署方式 | 本地 | 可逆 | |
|---|---|---|---|---|
| Headroom | 所有 context — tools/RAG/logs/文件/历史 | Proxy·library·middleware·MCP | ✅ | ✅ |
| RTK | CLI 命令输出 | CLI wrapper | ✅ | ❌ |
| lean-ctx | CLI+MCP tools+editor rules | CLI·MCP | ✅ | ❌ |
| OpenAI Compaction | 对话历史 | Provider 原生 | ❌ | ❌ |
注：Headroom 内置 RTK 二进制做 shell 输出重写，两者互补而非竞争。
关联
- tokenjuice — 类似定位的确定性 output 压缩工具
- agentmemory — 跨会话记忆持久化
- mempalace — 本地优先记忆系统