Headroom 是一个 LLM 上下文压缩层，通过智能压缩 Agent 工具调用、数据库查询、RAG 结果等内容，实现 70-95% 的 Token 节省同时保持答案准确性。
Headroom
压缩你的 AI Agent 读取的所有内容。同样的答案，只需几分之一的 Token。
你的 Agent 执行的每一次工具调用、DB 查询、文件读取和 RAG 检索中，有 70-95% 都是样板代码。
Headroom 在这些内容进入模型之前将其压缩。
适用于 任何 Agent — 编码 Agent (Claude Code, Codex, Cursor, Aider)，自定义 Agent
(LangChain, LangGraph, Agno, Strands, OpenClaw)，或你自己的 Python 和 TypeScript 代码。
## Headroom 的定位
```
Your Agent / App
(coding agents, customer support bots, RAG pipelines,
data analysis agents, research agents, any LLM app)
│
│ tool calls, logs, DB reads, RAG results, file reads, API responses
▼
Headroom ← proxy, Python/TypeScript SDK, or framework integration
│
▼
LLM Provider (OpenAI, Anthropic, Google, Bedrock, 100+ via LiteLLM)
```
Headroom 位于你的应用程序和 LLM 提供商之间。它拦截请求，压缩上下文，并转发优化后的提示词。你可以将其作为透明代理（零代码修改）、Python 函数 (`compress()`) 或框架集成（LangChain, LiteLLM, Agno）使用。
### 被压缩的内容
Headroom 优化你的 Agent 注入到提示词中的任何数据：
- **Tool outputs** — Shell 命令、API 调用、搜索结果
- **Database queries** — SQL 结果、键值查找
- **RAG retrievals** — 文档块、Embedding 结果
- **File reads** — 代码、日志、配置、CSV
- **API responses** — JSON, XML, HTML
- **Conversation history** — 具有重复上下文的长 Agent 会话
## 快速开始
**Python:**
```
pip install "headroom-ai[all]"
```
**TypeScript / Node.js:**
```
npm install headroom-ai
```
### 任何 Agent — 一个函数
**Python:**
```
from headroom import compress
result = compress(messages, model="claude-sonnet-4-5-20250929")
response = client.messages.create(model="claude-sonnet-4-5-20250929", messages=result.messages)
print(f"Saved {result.tokens_saved} tokens ({result.compression_ratio:.0%})")
```
**TypeScript:**
```
import { compress } from 'headroom-ai';
const result = await compress(messages, { model: 'gpt-4o' });
const response = await openai.chat.completions.create({ model: 'gpt-4o', messages: result.messages });
console.log(`Saved ${result.tokensSaved} tokens`);
```
适用于任何 LLM 客户端 — Anthropic, OpenAI, LiteLLM, Bedrock, Vercel AI SDK, 或你自己的代码。
### 任何 Agent — 代理（零代码修改）
```
headroom proxy --port 8787
```
```
# 将任意 LLM 客户端指向 proxy
ANTHROPIC_BASE_URL=http://localhost:8787 your-app
OPENAI_BASE_URL=http://localhost:8787/v1 your-app
```
适用于任何语言、任何工具、任何框架。**[代理文档](docs/proxy.md)**
### 编码 Agent — 一条命令
```
headroom wrap claude # Starts proxy + launches Claude Code
headroom wrap codex # Starts proxy + launches OpenAI Codex CLI
headroom wrap aider # Starts proxy + launches Aider
headroom wrap cursor # Starts proxy + prints Cursor config
headroom wrap openclaw # Installs + configures OpenClaw plugin
```
Headroom 启动一个代理，将你的工具指向它，并自动压缩所有内容。
### 多 Agent — SharedContext
```
from headroom import SharedContext
ctx = SharedContext()
ctx.put("research", big_agent_output) # Agent A stores (compressed)
summary = ctx.get("research") # Agent B reads (~80% smaller)
full = ctx.get("research", full=True) # Agent B gets original if needed
```
压缩 Agent 之间传输的数据 — 任何框架。**[SharedContext 指南](docs/shared-context.md)**
### MCP Tools (Claude Code, Cursor)
```
headroom mcp install && claude
```
为你的 AI 工具提供三个 MCP 工具：`headroom_compress`, `headroom_retrieve`, `headroom_stats`。**[MCP 指南](docs/mcp.md)**
### 无缝接入现有技术栈
| 你的设置 | 添加 Headroom | 一行代码 |
|------------|-------------|-----------|
| **任何 Python 应用** | `compress()` | `result = compress(messages, model="gpt-4o")` |
| **任何 TypeScript 应用** | `compress()` | `const result = await compress(messages, { model: 'gpt-4o' })` |
| **Vercel AI SDK** | Middleware | `wrapLanguageModel({ model, middleware: headroomMiddleware() })` |
| **OpenAI Node SDK** | Wrap client | `const client = withHeadroom(new OpenAI())` |
| **Anthropic TS SDK** | Wrap client | `const client = withHeadroom(new Anthropic())` |
| **Multi-agent** | SharedContext | `ctx = SharedContext(); ctx.put("key", data)` |
| **LiteLLM** | Callback | `litellm.callbacks = [HeadroomCallback()]` |
| **Any Python proxy** | ASGI Middleware | `app.add_middleware(CompressionMiddleware)` |
| **Agno agents** | Wrap model | `HeadroomAgnoModel(your_model)` |
| **LangChain** | Wrap model | `HeadroomChatModel(your_llm)` |
| **OpenClaw** | One-command wrap | `headroom wrap openclaw` |
| **Claude Code** | Wrap | `headroom wrap claude` |
| **Codex / Aider** | Wrap | `headroom wrap codex` 或 `headroom wrap aider` |
**[完整集成指南](docs/integration-guide.md)** | **[TypeScript SDK](docs/typescript-sdk.md)**
## 演示
## 效果真的好吗？
**100 条生产日志条目。一条关键错误被掩埋在第 67 位。**
| | 基线 | Headroom |
|--|----------|----------|
| Input tokens | 10,144 | 1,260 |
| 正确答案 | **4/4** | **4/4** |
两个响应均为：*"payment-gateway, error PG-5523, fix: Increase max_connections to 500, 1,847 transactions affected."*
**Token 减少 87.6%。答案相同。** 运行命令：`python examples/needle_in_haystack_test.py`
Headroom 保留的内容
从 100 条日志条目中，SmartCrusher 保留了 6 条：前 3 条（边界）、第 67 位的 FATAL 错误（异常检测）和后 2 条（近期性）。错误被自动保留——不是通过关键词匹配，而是通过对字段方差的统计分析。
### 真实工作负载
| 场景 | 之前 | 之后 | 节省 |
|----------|--------|-------|---------|
| 代码搜索 (100 个结果) | 17,765 | 1,408 | **92%** |
| SRE 事件调试 | 65,694 | 5,118 | **92%** |
| 代码库探索 | 78,502 | 41,254 | **47%** |
| GitHub issue 分类 | 54,174 | 14,761 | **73%** |
### 准确性基准测试
压缩保留了准确性 — 在真实的 OSS 基准测试中验证。
**标准基准测试** — 基线（直接访问 API） vs Headroom（通过代理）：
| Benchmark | 类别 | N | 基线 | Headroom | 差异 |
|-----------|----------|---|----------|----------|-------|
| [GSM8K](https://huggingface.co/datasets/openai/gsm8k) | 数学 | 100 | 0.870 | 0.870 | **0.000** |
| [TruthfulQA](https://huggingface.co/datasets/truthfulqa/truthful_qa) | 事实 | 100 | 0.530 | 0.560 | **+0.030** |
**压缩基准测试** — 完整压缩栈后的准确性：
| Benchmark | 类别 | N | 准确性 | 压缩率 | 方法 |
|-----------|----------|---|----------|-------------|--------|
| [SQuAD v2](https://huggingface.co/datasets/rajpurkar/squad_v2) | QA | 100 | **97%** | 19% | Before/After |
| [BFCL](https://huggingface.co/datasets/gorilla-llm/Berkeley-Function-Calling-Leaderboard) | Tool/Function | 100 | **97%** | 32% | LLM-as-Judge |
| Tool Outputs (内置) | Agent | 8 | **100%** | 20% | Before/After |
| CCR Needle Retention | 无损 | 50 | **100%** | 77% | Exact Match |
自行运行：
```
# 快速 smoke test (8 cases, ~10s)
python -m headroom.evals quick -n 8 --provider openai --model gpt-4o-mini
# 完整 Tier 1 套件 (~$3, ~15 min)
python -m headroom.evals suite --tier 1 -o eval_results/
# CI 模式 (回归时 exit 1)
python -m headroom.evals suite --tier 1 --ci
```
完整方法论：[Benchmarks](docs/benchmarks.md) | [Evals Framework](headroom/evals/README.md)
## 核心能力
### 无损压缩
Headroom 永远不会丢弃数据。它会积极压缩，存储原件，并在需要时为 LLM 提供检索完整细节的工具。当它将 500 个项目压缩为 20 个时，它会告诉模型*省略了什么*（"87 passed, 2 failed, 1 error"），以便模型知道何时需要更多信息。
### 智能内容检测
自动检测上下文中的内容 — JSON 数组、代码、日志、纯文本 — 并将每种内容路由到最佳压缩器。JSON 进入 SmartCrusher，代码通过 AST 感知压缩，文本进入 Kompress（基于 ModernBERT，带有 `[ml]` 扩展）。
### 缓存优化
稳定消息前缀，以便你提供商的 KV cache 真正发挥作用。Claude 对缓存的前缀提供 90% 的读取折扣 — 但几乎没有任何框架利用这一点。Headroom 做到了。
### 失败学习
```
headroom learn # Analyze past Claude Code sessions, show recommendations
headroom learn --apply # Write learnings to CLAUDE.md and MEMORY.md
headroom learn --all --apply # Learn across all your projects
```
读取你的对话历史，找到每一个失败的工具调用，将其与最终成功的内容相关联，并将特定的修正写入你的项目文件。下次会话会更智能。**[Learn 文档](docs/learn.md)**
### 图像压缩
通过训练有素的 ML 路由器减少 40-90% 的 Token。自动为每张图像选择正确的尺寸/质量权衡。
所有功能
| 功能 | 作用 |
|---------|-------------|
| **Content Router** | 自动检测内容类型，路由到最佳压缩器 |
| **SmartCrusher** | 通用 JSON 压缩 — dict 数组、字符串、数字、混合类型、嵌套对象 |
| **CodeCompressor** | 针对Python, JS, Go, Rust, Java, C++ 的 AST 感知压缩 |
| **Kompress** | ModernBERT Token 压缩（取代 LLMLingua-2） |
| **CCR** | 可逆压缩 — LLM 在需要时检索原件 |
| **Compression Summaries** | 告诉 LLM 省略了什么（"3 errors, 12 failures"） |
| **CacheAligner** | 稳定前缀以实现提供商 KV cache 命中 |
| **IntelligentContext** | 基于评分的上下文管理，具有学习到的重要性 |
| **Image Compression** | 通过训练有素的 ML 路由器减少 40-90% Token |
| **Memory** | 跨对话的持久化记忆 |
| **Compression Hooks** | 使用 pre/post hooks 自定义压缩 |
| **Read Lifecycle** | 检测过时/被取代的 Read 输出，替换为 CCR 标记 |
| **`headroom learn`** | 分析过去的失败，将项目特定的学习内容写入 CLAUDE.md/MEMORY.md |
| **`headroom wrap`** | 针对 Claude Code, Codex, Aider, Cursor 的一键设置 |
| **SharedContext** | 用于多 Agent 工作流的压缩 Agent 间上下文共享 |
| **MCP Tools** | 适用于 Claude Code/Cursor 的 headroom_compress, headroom_retrieve, headroom_stats |
## Headroom 与替代方案对比
上下文压缩是一个新领域。以下是各种方法的差异：
| | 方法 | 范围 | 部署形式 | 框架集成 | 数据保留在本地？ | 可逆 |
|---|---|---|---|---|---|---|
| **Headroom** | 多算法压缩 | 所有上下文（工具输出、DB 读取、RAG、文件、日志、历史） | 代理、Python 库、ASGI 中间件或回调 | LangChain, LangGraph, Agno, Strands, LiteLLM, MCP | 是 (OSS) | 是 (CCR) |
| **[RTK](https://github.com/rtk-ai/rtk)** | CLI 命令重写器 | Shell 命令输出 | CLI 包装器 | 无 | 是 (OSS) | 否 |
| **[Compresr](https://compresr.ai)** | 云压缩 API | 发送到其 API 的文本 | API 调用 | 无 | 否 | 否 |
| **[Token Company](https://thetokencompany.ai)** | 云压缩 API | 发送到其 API 的文本 | API 调用 | 无 | 否 | 否 |
**随心所欲地使用。** Headroom 可作为独立代理（`headroom proxy`）、单函数 Python 库（`compress()`）、ASGI 中间件或 LiteLLM 回调使用。已经在使用 LiteLLM、LangChain 或 Agno？直接插入 Headroom，无需替换任何东西。
**Headroom + RTK 结合使用效果很好。** RTK 重写 CLI 命令（`git show` → `git show --short`），Headroom 压缩其他所有内容（JSON 数组、代码、日志、RAG 结果、对话历史）。两者可以并用。
**Headroom 与云 API 对比。** Compresr 和 Token Company 是托管服务 — 你将上下文发送到他们的服务器，他们压缩后返回。Headroom 在本地运行。你的数据永远不会离开你的机器。你还获得无损压缩（CCR）：LLM 可以在需要更多细节时检索完整的原件。
## 内部工作原理
```
Your prompt
│
▼
1. CacheAligner Stabilize prefix for KV cache
│
▼
2. ContentRouter Route each content type:
│ → SmartCrusher (JSON)
│ → CodeCompressor (code)
│ → Kompress (text, with [ml])
▼
3. IntelligentContext Score-based token fitting
│
▼
LLM Provider
Needs full details? LLM calls headroom_retrieve.
Originals are in the Compressed Store — nothing is thrown away.
```
**开销**：15-200ms 压缩延迟（对 Sonnet/Opus 而言是净收益）。完整数据：[Latency Benchmarks](docs/LATENCY_BENCHMARKS.md)
## 集成
| 集成 | 状态 | 文档 |
|-------------|--------|------|
| `headroom wrap claude/codex/aider/cursor` **Stable** | [Proxy Docs](docs/proxy.md) |
| `compress()` — one function | **Stable** | [Integration Guide](docs/integration-guide.md) |
| `SharedContext` — multi-agent | **Stable** | [SharedContext Guide](docs/shared-context.md) |
| LiteLLM callback | **Stable** | [Integration Guide](docs/integration-guide.md#litellm) |
| ASGI middleware | **Stable** | [Integration Guide](docs/integration-guide.md#asgi-middleware) |
| Proxy server | **Stable** | [Proxy Docs](docs/proxy.md) |
| Agno | **Stable** | [Agno Guide](docs/agno.md) |
| MCP (Claude Code, Cursor, etc.) | **Stable** | [MCP Guide](docs/mcp.md) |
| Strands | **Stable** | [Strands Guide](docs/strands.md) |
| LangChain | **Stable** | [LangChain Guide](docs/langchain.md) |
| **OpenClaw** | **Stable** | [OpenClaw plugin](#openclaw-plugin) |
## OpenClaw 插件
[`@headroom-ai/openclaw`](plugins/openclaw) 插件将 Headroom 集成为 [OpenClaw](https://github.com/openclaw/openclaw) 的 ContextEngine。它内联压缩工具输出、代码、日志和结构化数据 — 无需 LLM 调用即可节省 70-90% Token。该插件可以连接到本地或远程 Headroom 代理，并会在需要时自动启动本地代理。
### 安装
```
pip install "headroom-ai[proxy]"
openclaw plugins install --dangerously-force-unsafe-install headroom-ai/openclaw
```
安装后，在你的 OpenClaw 配置中将 Headroom 指定为上下文引擎：
```
{
"plugins": {
"entries": { "headroom": { "enabled": true } },
"slots": { "contextEngine": "headroom" }
}
}
```
该插件会自动检测并启动代理 — 无需手动管理代理。有关完整的配置选项、本地开发设置和启动器详细信息，请参阅 [插件 README](plugins/openclaw/README.md)。
## 云提供商
```
headroom proxy --backend bedrock --region us-east-1 # AWS Bedrock
headroom proxy --backend vertex_ai --region us-central1 # Google Vertex
headroom proxy --backend azure # Azure OpenAI
headroom proxy --backend openrouter # OpenRouter (400+ models)
```
## 安装
```
pip install headroom-ai # Core library
pip install "headroom-ai[all]" # Everything including evals (recommended)
pip install "headroom-ai[proxy]" # Proxy server + MCP tools
pip install "headroom-ai[mcp]" # MCP tools only (no proxy)
pip install "headroom-ai[ml]" # ML compression (Kompress, requires torch)
pip install "headroom-ai[agno]" # Agno integration
pip install "headroom-ai[langchain]" # LangChain (experimental)
pip install "headroom-ai[evals]" # Evaluation framework only
```
Python 3.10+
## 文档
| | |
|---|---|
| [集成指南](docs/integration-guide.md) | LiteLLM, ASGI, compress(), proxy |
| [Proxy Docs](docs/proxy.md) | 代理服务器配置 |
| [Architecture](docs/ARCHITECTURE.md) | 管道如何工作 |
| [CCR Guide](docs/ccr.md) | 可逆压缩 |
| [Benchmarks](docs/benchmarks.md) | 准确性验证 |
| [Latency Benchmarks](docs/LATENCY_BENCHMARKS.md) | 压缩开销与成本效益分析 |
| [Limitations](docs/LIMITATIONS.md) | 压缩何时有帮助，何时没有 |
| [Evals Framework](headroom/evals/README.md) | 证明压缩保留了准确性 |
| [Memory](docs/memory.md) | 持久化记忆 |
| [Agno](docs/agno.md) | Agno agent framework |
| [MCP](docs/mcp.md) | 上下文工程工具包 (compress, retrieve, stats) |
| [SharedContext](docs/shared-context.md) | 压缩的 Agent 间上下文共享 |
| [Learn](docs/learn.md) | 编码 Agent 的离线失败学习 |
| [Configuration](docs/configuration.md) | 所有选项 |
## 社区
有问题、反馈或只是想关注动态？**[加入我们的 Discord](https://discord.gg/yRmaUNpsPJ)**
## 贡献
```
git clone https://github.com/chopratejas/headroom.git && cd headroom
pip install -e ".[dev]" && pytest
```
## 许可证
Apache License 2.0 — 详见 [LICENSE](LICENSE)。