Headroom: 为 AI 智能体无损压缩上下文，节省 90% 的 Token

压缩 AI 智能体读取的一切内容。答案相同，Token 消耗仅为零头。

Compress everything the AI agent reads. Same answers, token consumption is just a fraction.

智能体（Agent）每次工具调用、日志输出、数据库读取、RAG 检索片段以及注入到提示词（Prompt）中的文件，大部分内容都是重复的样板信息。Headroom 能够剥离这些噪音，保留核心信号——无损、本地化运行，且不影响准确性。

Every tool call, log line, DB read, RAG chunk, and file your agent injects into a prompt is mostly boilerplate. Headroom strips the noise and keeps the signal — losslessly, locally, and without touching accuracy.

100 条日志，1 条 FATAL 错误埋在第 67 条。两种方式都找到了它。 基准测试 10,144 tokens → Headroom 1,260 tokens — 节省 87% 的 Token，答案完全相同。python examples/needle_in_haystack_test.py

100 logs. One FATAL error buried at position 67. Both runs found it. Baseline 10,144 tokens → Headroom 1,260 tokens — 87% fewer, identical answer.python examples/needle_in_haystack_test.py

快速开始

支持 Anthropic、OpenAI、Google、Bedrock、Vertex、Azure、OpenRouter 以及通过 LiteLLM 接入的 100 多种模型。

Works with Anthropic, OpenAI, Google, Bedrock, Vertex, Azure, OpenRouter, and 100+ models via LiteLLM.

一键包装你的编程智能体：

Wrap your coding agent — one command:

pip install "headroom-ai[all]"

headroom wrap claude      # Claude Code
headroom wrap codex       # Codex
headroom wrap cursor      # Cursor
headroom wrap aider       # Aider
headroom wrap copilot     # GitHub Copilot CLI

集成到你的代码中 —— Python 或 TypeScript：

Drop it into your own code — Python or TypeScript:

from headroom import compress

result = compress(messages, model="claude-sonnet-4-5")
response = client.messages.create(model="claude-sonnet-4-5", messages=result.messages)
print(f"Saved {result.tokens_saved} tokens ({result.compression_ratio:.0%})")

import { compress } from 'headroom-ai';
const result = await compress(messages, { model: 'gpt-4o' });

或作为代理服务器运行 —— 无需修改代码，支持任何语言：

Or run it as a proxy — zero code changes, any language:

headroom proxy --port 8787
ANTHROPIC_BASE_URL=http://localhost:8787 your-app
OPENAI_BASE_URL=http://localhost:8787/v1 your-app

为什么选择 Headroom

Why Headroom

• 保持准确性。 GSM8K 0.870 → 0.870 (±0.000)。TruthfulQA +0.030。SQuAD v2 和 BFCL 压缩后准确率均为 97%。基于可自行复现的公开 OSS 基准测试验证。

  Accuracy-preserving. GSM8K 0.870 → 0.870 (±0.000). TruthfulQA +0.030. SQuAD v2 and BFCL both 97% accuracy after compression. Validated on public OSS benchmarks you can rerun yourself.

• 在本地运行。 无需云端 API，无数据外泄。压缩延迟为毫秒级 —— 对于 Sonnet / Opus / GPT-4 级别的模型，端到端速度比托管服务往返更快。

  Runs on your machine. No cloud API, no data egress. Compression latency is milliseconds — faster end-to-end for Sonnet / Opus / GPT-4 class models than a hosted service round-trip.

• HuggingFace 上的 Kompress-base。 我们开源的文本压缩器，基于真实的智能体轨迹微调 —— 包括工具输出、日志、RAG 片段、代码。通过 pip install "headroom-ai[ml]" 安装。

  Kompress-base on HuggingFace. Our open-source text compressor, fine-tuned on real agentic traces — tool outputs, logs, RAG chunks, code. Install with pip install "headroom-ai[ml]".

• 跨智能体记忆与学习。 Claude Code 保存一个事实，Codex 可以读取它。headroom learn 从失败的会话中挖掘信息，并将修正直接写入 CLAUDE.md / AGENTS.md / GEMINI.md —— 可靠性随时间推移而增强。

  Cross-agent memory and learning. Claude Code saves a fact, Codex reads it back. headroom learn mines failed sessions and writes corrections straight to CLAUDE.md / AGENTS.md / GEMINI.md — reliability compounds over time.

• 可逆 (CCR)。 压缩并非删除。模型始终可以调用 headroom_retrieve 来获取原始字节。没有任何内容被丢弃。

  Reversible (CCR). Compression is not deletion. The model can always call headroom_retrieve to pull the original bytes. Nothing is thrown away.

捆绑了 RTK 二进制文件用于 shell 输出重写 —— 完整归因见下文。

Bundles the RTK binary for shell-output rewriting — full attribution below.

架构概览

How it fits

 Your agent / app
   (Claude Code, Cursor, Codex, LangChain, Agno, Strands, your own code…)
        │   prompts · tool outputs · logs · RAG results · files
        ▼
    ┌────────────────────────────────────────────────────┐
    │  Headroom   (runs locally — your data stays here)  │
    │  ───────────────────────────────────────────────   │
    │  CacheAligner  →  ContentRouter  →  CCR             │
    │                    ├─ SmartCrusher   (JSON)         │
    │                    ├─ CodeCompressor (AST)          │
    │                    └─ Kompress-base  (text, HF)     │
    │                                                     │
    │  Cross-agent memory  ·  headroom learn  ·  MCP      │
    └────────────────────────────────────────────────────┘
        │   compressed prompt  +  retrieval tool
        ▼
 LLM provider  (Anthropic · OpenAI · Bedrock · …)

→ 架构 · CCR 可逆压缩 · Kompress-base 模型卡片

→ Architecture · CCR reversible compression · Kompress-base model card

性能证明

Proof

真实智能体工作负载下的节省效果：

Savings on real agent workloads:

在标准基准测试上保持的准确性：

Accuracy preserved on standard benchmarks:

复现命令：

Reproduce:

python -m headroom.evals suite --tier 1

社区实时数据：

Community, live:

→ 完整基准测试与方法论

→ Full benchmarks & methodology

专为编程智能体打造

Built for coding agents

同样原生支持 MCP —— headroom mcp install 向任何 MCP 客户端暴露 headroom_compress、headroom_retrieve 和 headroom_stats 工具。

MCP-native too — headroom mcp install exposes headroom_compress, headroom_retrieve, and headroom_stats to any MCP client.

集成方案

Integrations

将 Headroom 集成到任何技术栈

Drop Headroom into any stack

核心组件

What's inside

• SmartCrusher —— 通用 JSON 压缩器：字典数组、嵌套对象、混合类型。

  SmartCrusher — universal JSON: arrays of dicts, nested objects, mixed types.

• CodeCompressor —— 基于 AST 的代码压缩器，支持 Python、JS、Go、Rust、Java、C++。

  CodeCompressor — AST-aware for Python, JS, Go, Rust, Java, C++.

• Kompress-base

常见问题（FAQ）

Headroom压缩工具真的能无损减少90%的Token使用量吗？

是的，Headroom是一款本地无损压缩工具，专为AI代理提示设计，可将令牌使用量减少高达92%同时保持准确性，基准测试显示从10,144 tokens压缩到1,260 tokens，节省87%。

Headroom支持哪些AI模型和编程智能体？

支持Anthropic、OpenAI、Google、Bedrock等主流LLM提供商，以及Claude Code、Cursor、Aider、GitHub Copilot CLI等热门编码代理，可通过Python、TypeScript集成或代理服务器方式使用。

如何快速开始使用Headroom压缩工具？

安装headroom-ai后，可通过‘headroom wrap’命令一键包装编程智能体，或在代码中调用compress函数，也可作为代理服务器运行，无需修改原有代码即可实现Token压缩。