headroomlabs-ai / headroom

本文为原文前 6,000 字符的节选翻译，完整内容请查看原文。

Quickstart · Headroom for Teams · Install · Proof · Agents · Docs · Discord · llms.txt AI agents / LLMs: read /llms.txt here, or fetch the live index · full docs blob.

快速入门 · 团队版 Headroom · 安装 · 验证 · 智能体 · 文档 · Discord · llms.txt AI 智能体 / 大语言模型：在此阅读 /llms.txt，或获取实时索引 · 完整文档包。

Headroom compresses everything your AI agent reads — tool outputs, logs, RAG chunks, files, and conversation history — before it reaches the LLM. Same answers, fraction of the tokens. Compression runs on your machine; no prompt or file content is sent anywhere to be compressed. 10,144 → 1,260 tokens. The same FATAL found.

Headroom 会在 AI 智能体读取工具输出、日志、RAG 数据块、文件和对话历史记录并将其发送给大语言模型之前，对所有内容进行压缩。在保持答案一致的前提下，大幅减少 Token 消耗。压缩过程在本地机器上运行；没有任何提示词或文件内容会被发送到外部进行压缩。例如将 10,144 个 Token 压缩至 1,260 个，且依然能发现同样的致命错误。

MCP server — headroom_compress, headroom_retrieve, headroom_stats for any MCP client. Cross-agent memory — one shared store across Claude, Codex, Gemini and Grok, with automatic dedup. headroom learn — mines failed sessions and writes corrections to CLAUDE.local.md (default, gitignored), CLAUDE.md, AGENTS.md, GEMINI.md or GROK.md. Output token reduction — trims what the model writes back, not only what you send. See below. Reversible (CCR) — originals are cached locally and retrieved on demand.

MCP 服务器 — 为任何 MCP 客户端提供 headroom_compress、headroom_retrieve 和 headroom_stats 功能。跨智能体记忆 — 在 Claude、Codex、Gemini 和 Grok 之间共享存储，并自动去重。headroom learn — 从失败的会话中挖掘信息，并将修正建议写入 CLAUDE.local.md（默认且已加入 gitignore）、CLAUDE.md、AGENTS.md、GEMINI.md 或 GROK.md。输出 Token 缩减 — 不仅缩减发送的内容，还缩减模型返回的内容。详见下文。可逆性 (CCR) — 原始数据在本地缓存，按需检索。

How it works 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 · …)

工作原理：你的智能体/应用（Claude Code, Cursor, Codex, LangChain, Agno, Strands, 你自己的代码……）│ 提示词 · 工具输出 · 日志 · RAG 结果 · 文件 ▼ ┌────────────────────────────────────────────────────┐ │ Headroom（本地运行 — 数据保留在本地） │ │ ──────────────────────────────────────────────── │ │ CacheAligner → ContentRouter → CCR │ │ ├─ SmartCrusher (JSON) │ │ ├─ CodeCompressor (AST) │ │ └─ Kompress-v2-base (text, HF) │ │ │ │ 跨智能体记忆 · headroom learn · MCP │ └────────────────────────────────────────────────────┘ │ 压缩后的提示词 + 检索工具 ▼ LLM 提供商（Anthropic · OpenAI · Bedrock · …）

ContentRouter detects the content type and selects a compressor for it. SmartCrusher / CodeCompressor / Kompress-v2-base handle JSON, source code and prose respectively. CacheAligner flags volatile content that would bust a provider KV-cache prefix. It never rewrites prompts. CCR stores originals locally so the model can call headroom_retrieve when it needs the full text. → Architecture · CCR · Kompress-v2-base model card

ContentRouter 会检测内容类型并为其选择相应的压缩器。SmartCrusher、CodeCompressor 和 Kompress-v2-base 分别处理 JSON、源代码和文本。CacheAligner 会标记那些可能破坏提供商 KV 缓存前缀的易变内容。它从不重写提示词。CCR 将原始数据存储在本地，以便模型在需要全文时调用 headroom_retrieve。→ 架构 · CCR · Kompress-v2-base 模型卡

Get started (60 seconds) # 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

快速上手（60 秒）# 1 — 安装 uv tool install —python 3.13 “headroom-ai[all]” # 在独立环境中安装 CLI pip install “headroom-ai[all]” # Python — 包含 headroom CLI npm install headroom-ai # 仅 TypeScript SDK — 不含 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

2 — 选择模式 headroom deploy # 一键式本地部署 + 智能体配置 headroom wrap claude # 封装编码智能体 headroom proxy —port 8787 # 直接插入代理，无需更改代码 # 或：from headroom import compress # 内联库

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

3 — 检查并查看节省情况 headroom doctor # 健康检查 — 确认路由工作正常 headroom perf headroom dashboard # 实时节省统计（需运行代理）

Inline, in 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%})”)

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%})”)

Launch a wrapped agent session each time, so the setup runs. headroom wrap starts a local proxy, installs Serena for semantic code navigation, and launches the agent configured to route through Headroom. For Claude Code, Serena is registered for the wrapped project only (as a local-scope MCP server in ~/.claude.json). Use —code-memory-scope user to make it available in every project, or —code-memory none to skip it. headroom unwrap removes either registration. The headroom CLI ships only in the PyPI package. The npm headroom-ai package is the TypeScript SDK — a library you import (import { compress } from ‘headroom-ai’) — and provides no headroom command.

每次启动封装的智能体会话时，配置都会运行。headroom wrap 会启动本地代理，安装用于语义代码导航的 Serena，并启动配置为通过 Headroom 路由的智能体。对于 Claude Code，Serena 仅针对封装的项目注册（作为 ~/.claude.json 中的本地范围 MCP 服务器）。使用 —code-memory-scope user 可使其在每个项目中可用，或使用 —code-memory none 跳过此步骤。headroom unwrap 可移除上述任一注册。headroom CLI 仅随 PyPI 包提供。npm headroom-ai 包是 TypeScript SDK（即你导入的库 import { compress } from ‘headroom-ai’），不提供 headroom 命令。

Proof Four scenarios built from real MCP server output formats, measured with the provider tokenizer and the shipped compress(). Seeded and offline, so you get the same numbers we did: uv run python benchmarks/index_proof_table.py —seed 20260902

验证：基于真实 MCP 服务器输出格式构建的四个场景，使用提供商的分词器和自带的 compress() 进行测量。采用种子值且离线运行，因此你可以获得与我们相同的数据：uv run python benchmarks/index_proof_table.py —seed 20260902

Scenario Before After Saved Code search (100 results) 17,199 13,597 21% SRE incident debugging 55,957 24,340 57% Codebase exploration 58,801 33,895 42% GitHub issue triage 46,067 32,429 30%

场景 | 压缩前 | 压缩后 | 节省比例代码搜索（100 条结果）| 17,199 | 13,597 | 21% SRE 事件调试 | 55,957 | 24,340 | 57% 代码库探索 | 58,801 | 33,895 | 42% GitHub 问题分类 | 46,067 | 32,429 | 30%

Savings scale with how repetitive the payload is. Repeated JSON arrays and log lines clear 90% in benchmarks/bench_latency.py; prose and already-dense output compress very little. Run headroom savings against your own traffic for the number that applies to you. Compression costs well under a millisecond — 0.21 ms p50 on a 10K-token JSON search result, 1.4 ms at 100K tokens — so it does not show up in agent latency.

节省比例取决于负载的重复程度。在 benchmarks/bench_latency.py 中，重复的 JSON 数组和日志行可节省 90% 以上；而散文和本身就很密集的内容压缩效果较差。针对你自己的流量运行 headroom savings 以获取适用于你的数据。压缩耗时远低于一毫秒 — 10K Token 的 JSON 搜索结果 p50 耗时 0.21 毫秒，100K Token 时为 1.4 毫秒 — 因此不会影响智能体的延迟。

Accuracy. python -m headroom.evals suite —tier 1: Benchmark Category N Baseline Headroom Delta GSM8K Math 100 0.870 0.870 ±0.000 TruthfulQA Factual 100 0.530 0.560 +0.030 SQuAD v2 QA 100 — 97% at 19% compression BFCL Tools 100 — 97% at 32% compression At N=100 a delta of ±0.03 falls inside the confidence interval, so TruthfulQA shows no detectable difference rather than an improvement. Methodology →

准确性。python -m headroom.evals suite —tier 1：基准测试 | 类别 | N | 基准值 | Headroom | 差值 GSM8K | 数学 | 100 | 0.870 | 0.870 | ±0.000 TruthfulQA | 事实 | 100 | 0.530 | 0.560 | +0.030 SQuAD v2 | 问答 | 100 | — | 19% 压缩下 97% | — BFCL | 工具 | 100 | — | 32% 压缩下 97% | — 在 N=100 时，±0.03 的差值处于置信区间内，因此 TruthfulQA 显示没有可检测到的差异，而非性能提升。方法论 →

Output token reduction Everything above shrinks the prompt you send. You also pay for every token the model writes back, and on Opus-class models output costs 5× input. Much of that output is ceremony: “Great, let me…” preambles, code re-printed straight back at you, and deep reasoning spent on routine steps like reading a file. Headroom trims it from the proxy, with no change to your code: Verbosity steering appends a short “be terse, don’t restate context” note to the end of the system prompt, so your prompt cache still hits. Effort routing dials thinking effort down when a turn is only the model resuming after a tool result — a file read, a passing test. New questions

输出 Token 缩减：以上所有内容都是为了缩减你发送的提示词。你还需要为模型返回的每一个 Token 付费，而在 Opus 级模型中，输出成本是输入的 5 倍。其中大部分输出是冗余的：如“太好了，让我……”之类的开场白、直接原样打印回给你的代码，以及在读取文件等常规步骤上花费的深度推理。Headroom 通过代理将其修剪掉，且无需更改你的代码：冗长控制会在系统提示词末尾附加一条简短的“简洁明了，不要重述上下文”的注释，从而确保你的提示词缓存依然有效。努力程度路由会在模型仅在工具结果（如文件读取、测试通过）后恢复时，降低其思考强度。新问题