headroom

英文原文正文为项目原始 README（英文），本站后续会翻译为中文，当前仅剔除图片与无关章节并统一排版。

Headroom 在你的 AI 代理读取之前会压缩所有内容——工具输出、日志、RAG 块、文件和对话历史——然后才发送到大型语言模型。答案相同，但所用的标记数只有一小部分。压缩在你的设备上运行；没有任何提示或文件内容会被发送到其他地方进行压缩。

它的作用

• 库 — 在 Python 或 TypeScript 中使用 compress(messages)，可在任何应用中内联使用。
• 代理 — headroom proxy --port 8787，无需更改代码，适用于任何语言。
• 代理封装 — 使用一条命令 headroom wrap claude|codex|grok|copilot|cursor|aider|opencode|cline|continue|goose|openhands|openclaw|vibe|omp|zcode；使用 headroom unwrap <tool> 可撤销。
• MCP 服务器 — 适用于任何 MCP 客户端的 headroom_compress、headroom_retrieve、headroom_stats。
• 跨代理内存 — 在 Claude、Codex、Gemini 和 Grok 之间共享一个存储，并自动去重。
• headroom learn — 挖掘失败的会话并将更正写入 CLAUDE.local.md（默认，git忽略）、CLAUDE.md、AGENTS.md、GEMINI.md 或 GROK.md。
• 输出令牌减少 — 修剪模型返回的内容，而不仅是你发送的内容。详见下文。
• 可逆（CCR） — 原始内容本地缓存，并按需检索。

它的工作原理

 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-v2-base (text, HF)  │
    │                                                    │
    │  Cross-agent memory  ·  headroom learn  ·  MCP     │
    └────────────────────────────────────────────────────┘
        │   compressed prompt  +  retrieval tool
        ▼
 LLM provider  (Anthropic · OpenAI · Bedrock · …)

• ContentRouter 检测内容类型并为其选择一个压缩器。
• SmartCrusher / CodeCompressor / Kompress-v2-base 分别处理 JSON、源代码和散文。
• CacheAligner 标记可能破坏提供者 KV 缓存前缀的易变内容。它从不重写提示。
• CCR 本地存储原始内容，以便模型在需要完整文本时可以调用 headroom_retrieve。

→ 架构 · CCR · Kompress-v2-base 模型卡

开始使用（60秒）

# 1 — Install
uv tool install --python 3.13 "headroom-ai[all]"  # CLI in a self-contained env
pip install "headroom-ai[all]"                    # Python — ships the `headroom` CLI
npm install headroom-ai                           # TypeScript SDK only — no CLI

# 2 — Pick a mode
headroom deploy                         # turnkey local deployment + agent config
headroom wrap claude                    # wrap a coding agent
headroom proxy --port 8787              # drop-in proxy, zero code changes
# or: from headroom import compress     # inline library

# 3 — Check it and watch the savings
headroom doctor                         # health check — confirms routing works
headroom perf
headroom dashboard                      # live savings (proxy must be running)

在 Python 中，内联:

from headroom import compress
from openai import OpenAI

messages = [{"role": "user", "content": "Analyze these results"}]
result = compress(messages, model="gpt-4o")

client = OpenAI()
response = client.chat.completions.create(model="gpt-4o", messages=result.messages)
print(f"Saved {result.tokens_saved} tokens ({result.compression_ratio:.0%})")

每次启动时都启动一个封装的代理会话，以便运行设置。headroom wrap 启动本地代理，安装 Serena 用于语义代码导航，并启动配置为通过 Headroom 路由的代理。Serena 在用户范围内注册（对于 Claude Code，在 ~/.claude.json 中），因此在你运行 headroom unwrap 之前，它会在你的其他项目中保持可用。使用 --code-memory none 可跳过它。

headroom CLI 仅随 PyPI 包提供。npm 的 headroom-ai 包是 TypeScript SDK —— 一个你可以导入的库（import { compress } from 'headroom-ai'）—— 并不提供 headroom 命令。

证明

四种场景基于真实的 MCP 服务器输出格式构建，使用提供者的分词器和附带的 compress() 测量。已设定种子并离线，因此你会得到与我们相同的数值：

uv run python benchmarks/index_proof_table.py --seed 20260902

节省取决于载荷的重复程度。重复的 JSON 数组和日志行在 benchmarks/bench_latency.py 中可清除 90%；而散文和已密集的输出几乎无法压缩。针对您的流量运行 headroom savings 可获得适用于您的具体数值。

压缩成本远低于一毫秒 — 10K 令牌 JSON 搜索结果的 p50 为 0.21 毫秒，100K 令牌为 1.4 毫秒 — 因此不会影响代理延迟。

准确性。 python -m headroom.evals suite --tier 1：

在N=100时，±0.03的差值位于置信区间内，因此TruthfulQA显示没有可检测到的差异，而不是改进。 方法论 →

输出令牌减少

以上所有内容都会缩小你发送的提示。你还需要为模型回复的每一个令牌付费，在Opus类模型中，输出的费用是输入的5倍。大部分输出都是仪式性内容：“好的，让我来……”，代码直接原样返回给你，以及用于例行步骤（如读取文件）的深度推理。

Headroom 从代理端进行裁剪，而不改变你的代码：

• 冗长度引导在系统提示的末尾附加简短的“保持简洁，不要重复上下文”说明，因此你的提示缓存仍然生效。
• 努力路由在仅仅是模型在工具结果后继续响应（例如读取文件、通过测试）的情况下降低思考努力。新问题和错误仍保持全力处理。

两者都适用于Anthropic的/v1/messages以及兼容OpenAI的/v1/chat/completions和/v1/responses。努力路由在OpenAI上使用reasoning_effort，在Anthropic上使用thinking.budget_tokens / output_config.effort，并在两条路径上保持相同的仅限钳制不变性和相同的output_shaper:*标签。

export HEADROOM_OUTPUT_SHAPER=1     # off by default
headroom proxy --port 8787

已经在运行代理？ 这些开关会在每次请求时实时读取，因此一个 headroom wrap 重用 而不是新启动的代理，将看不到你之后导出的值——它的环境在启动时已经被快照。headroom wrap 会通过回环接口将你当前的设置热同步到运行中的代理
POST /admin/runtime-env，所以它们可以在不重启且不丢失请求的情况下生效。在共享代理上，这些覆盖是全局的；最后的显式设置生效。

无需配置的简洁性。 人们很少明确说明他们希望答案有多简洁——他们通过打断长回复或在可能还未读完时就继续前进来展示这一点。headroom learn --verbosity 会读取过去的会话并选择级别：

headroom learn --verbosity            # dry run — preview what it found
headroom learn --verbosity --apply    # save it; the proxy picks it up

测量它。 输出节省是反事实的——我们从未真正看到模型本可能写出的内容——因此 Headroom 会报告一个带有置信区间的估算值，并将其标记为以下之一：

headroom output-savings
# Reduction: 31.7%  (95% CI 27.7% … 35.7%)   [estimated]

对于测量得出的数字，请将 10% 的对话作为未经过形状化的对照保存：export HEADROOM_OUTPUT_HOLDOUT=0.1。仪表板的 Output Tokens Saved 卡片随后会显示为 measured 而非 estimated，并带有带状显示。

→ 输出令牌减少

代理兼容性

任何与 OpenAI 兼容的客户端都可以通过 headroom proxy 工作。MCP 原生客户端：headroom mcp install。使用 headroom unwrap <tool> (claude、copilot、codex、grok、kimi、omp、opencode、openclaw、zcode) 撤销持久化封装。注册表作者应使用标准 server.json，而不是从文本中重建 headroom mcp serve 协议。

headroom copilot-auth 登录
headroom wrap copilot --subscription -- --model gpt-4o

导出 GITHUB_COPILOT_ENTERPRISE_DOMAIN=ghe.example.com
export GITHUB_COPILOT_ENTERPRISE_URL=https://ghe.example.com

headroom copilot-auth 登录
headroom 包装 vscode

pip 安装 "headroom-ai[proxy]"
headroom 包装 vscode-claude

何时使用 · 何时跳过

适合的情况 如果你每天运行编码代理，并希望在不修改代码的情况下节省资源；需要在多个代理之间工作并共享一个内存；或者需要可逆压缩——原始数据可以通过 CCR 在设置的 TTL 内检索。

不适合的情况 如果你仅使用一个提供商的原生压缩功能，并且不需要跨代理内存；或者在沙箱环境中工作，本地进程无法运行。

Headroom 在代理会话时间长且工具输出量大的情况下效果明显。短对话交流、散文和已经密集的数据几乎不会减少，且小于 min_input_words 的数据块会以字节相同的形式返回。完整列表请参见 限制。

安装

uv tool install --python 3.13 "headroom-ai[all]"  # CLI, isolated app env
pip install "headroom-ai[all]"                    # Python, everything — includes the CLI
npm install headroom-ai                           # TypeScript SDK (library only)
docker pull ghcr.io/headroomlabs-ai/headroom:latest

细粒度额外功能：[proxy]、[mcp]、[ml]（Kompress-v2-base）、[code]、[memory]、[vector]（可选 HNSW 后端 — 需要 C 工具链，不包含在 [all] 中）、[relevance]、[image]、[agno]、[langchain]、[evals]、[pytorch-mps]（Apple GPU 内存嵌入卸载 — 设置 HEADROOM_EMBEDDER_RUNTIME=pytorch_mps）。需要 Python 3.10。

[all] 涵盖核心堆栈，但不包括框架适配器。请单独安装它们：pip install "headroom-ai[langchain]"，[agno] 也是如此，
[strands]、[anyllm]、[bedrock]。

→ 安装指南 — Docker 标签、持久服务、PowerShell、开发容器。

brew install  python@3.13   # 如果 3.13 尚未可用
uv 工具安装 --python 3.13 "headroom-ai[all]"
uv 工具 update-shell      # 如果 ~/.local/bin 不在 PATH 中 headroom --version

[mcp_servers.headroom]
command = "/Users/you/.local/bin/headroom"
args = ["mcp", "serve"]

pipx 安装 --python python3.13 "headroom-ai[all]"

headroom update          # 检测 pip / pipx / uv 工具并进行原地升级
headroom update --check  # 报告最新版本但不升级 headroom update --pre  # 包含预发布版本

# macOS / Linux
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh && rustup default stable
# 窗口
winget 安装 Rustlang.Rustup  &  &  rustup 默认 stable

brew 安装 onnxruntime
ORT_STRATEGY=system "}
ORT_LIB_LOCATION="$(brew --prefix onnxruntime)/lib" \
ORT_PREFER_DYNAMIC_LINK=1 \ pip 安装 "headroom-ai[all]"

# ORT 也在运行时通过 dlopen 加载：
export ORT_DYLIB_PATH="$(brew --prefix onnxruntime)/lib/libonnxruntime.dylib"

[SSL：证书验证失败] 证书验证失败：
CA 证书的基本约束未标记为关键
然后企业 CA 被找到并被信任，将它添加到 CA 捆绑包不会改变任何东西。Python 3.13 配合 OpenSSL 3.x 默认启用 VERIFY_X509_STRICT，这会强制执行 RFC 5280 §4.2.1.9：CA 证书的 basicConstraints 必须标记为关键。像 Zscaler 这样的检查根将 CA:TRUE 设置为非关键位，因此该链被拒绝。
HEADROOM_TLS_STRICT=0 仅清除严格标志，从 Headroom 控制的每个 TLS 上下文 —— 代理的 httpx 上游客户端和用于模型下载的 urllib3/huggingface_hub 路径。链验证、签名、过期和主机名检查都保持开启。
HEADROOM_TLS_STRICT=0 headroom 代理 --port 8787
Rust 核心的 ONNX 下载使用了一个独立的 TLS 堆栈（rustls / 操作系统信任存储），不会受到 HEADROOM_TLS_STRICT 的影响。在 Windows 上，公司根证书必须位于 计算机证书存储中——浏览器在那里已经信任它——或者预先使用 ORT_STRATEGY=system 为 ONNX Runtime 提供配置以跳过下载。

git clone https://github.com/headroomlabs-ai/headroom.git && cd headroom
uv sync --extra dev && uv run pytest