AI 代理上下文压缩层：60%-95% Token 削减，不丢失关键信息
Headroom 是一个本地运行的 AI 代理上下文压缩工具，旨在显著降低 LLM 使用成本与延迟。它在工具输出、日志、RAG 数据块及对话历史到达大模型前进行智能压缩，支持 JSON、代码和自然语言等多类内容。项目提供库、代理、MCP 服务器和代理包装器四种集成模式，通过内容路由选择最优压缩算法，并具备可逆压缩（CCR）机制确保原始数据不被丢弃。它还包含跨代理记忆共享和从失败会话中学习的 `headroom learn` 命令，适合每天高强度使用编程代理的工程师和任何需要优化 LLM Token 消耗的系统。
Headroom is a local-first context compression layer that sits between your AI agent (Claude Code, Cursor, Codex, etc.) and the LLM provider. It transparently shrinks tool outputs, logs, RAG chunks, files, and conversation history by 60–95% while preserving answer accuracy. It works as a library (compress() in Python/TypeScript), a zero-code proxy, an agent wrapper (headroom wrap), or an MCP server.
Headroom 是一个在 AI Agent（Claude Code、Cursor、Codex 等）与底层大模型之间运行的本地上下文压缩层。它透明地将工具输出、日志、RAG 分块、文件和对话历史压缩 60–95%，同时保持答案精度不变。它可以作为库（Python/TypeScript 中的 compress()）、零代码代理（proxy）、一键 Agent 封装（headroom wrap）或 MCP 服务器来使用。
AI coding agents read massive amounts of context — code search results, error logs, file contents, past conversation — all of which translates into tokens, and tokens cost money and eat into context windows. Existing approaches like prompt truncation or API-based compression either lose information, sacrifice accuracy, or send your data to third parties. Headroom solves this by running entirely locally, with a suite of content-aware compressors that understand the structure of what they're compressing, and a reversible storage layer (CCR) so the LLM can retrieve originals on demand without losing fidelity.
AI 编程 Agent 会读取海量的上下文——代码搜索结果、错误日志、文件内容、历史对话——这些都会转化为 Token，而 Token 既花钱又占用上下文窗口。现有的方案如截断提示词或使用 API 压缩，要么丢失信息、牺牲精度，要么把数据发送给第三方服务。Headroom 完全在本地运行，通过一组理解内容结构的感知压缩器（content-aware compressors）和一个可逆存储层（CCR），让大模型按需取回原始内容而不损失保真度，从而解决了上述痛点。
Headroom's core is the ContentRouter, which detects content type and dispatches to the right compressor: SmartCrusher handles arbitrary JSON (arrays of dicts, nested structures); CodeCompressor is AST-aware for Python, JS, Go, Rust, Java, and C++; Kompress-base is a HuggingFace model trained on agentic traces for free-form text. It also includes image compression via a trained ML router, and CacheAligner that stabilizes prompt prefixes so provider-side KV caches hit more often. Crucially, all original content is stored locally via CCR (Content Compression with Reversibility); the LLM can call headroom_retrieve to fetch originals if needed — no data loss.
Headroom 的核心是 ContentRouter，它检测内容类型并分发给合适的压缩器：SmartCrusher 处理任意 JSON（嵌套字典、对象数组等）；CodeCompressor 基于 AST 理解 Python、JS、Go、Rust、Java 和 C++ 的代码结构；Kompress-base 是在 HuggingFace 上的模型，专门针对 Agent 生成的自然语言文本训练。它还包含一个经过训练的 ML 路由模块用于图像压缩，以及 CacheAligner 来稳定提示前缀，使供应商侧的 KV 缓存命中率更高。最关键的，所有原始内容通过 CCR（可逆压缩） 本地存储；大模型可以调用 headroom_retrieve 取回原始内容——数据零损失。
Headroom adapts to how you use AI agents. Library mode: from headroom import compress; compressed = compress(messages) in Python or TypeScript. Proxy mode: headroom proxy --port 8787 — any tool that speaks OpenAI-compatible API automatically gets compressed context with zero code changes. Agent wrap: headroom wrap claude|codex|cursor|aider|copilot — wraps the agent's own process so all I/O goes through Headroom. MCP server: run headroom mcp install to expose headroom_compress, headroom_retrieve, headroom_stats as MCP tools that any MCP client can call. All modes support cross-agent memory — a shared store that deduplicates and compresses context across Claude, Codex, Gemini, etc.
Headroom 提供了四种运行模式来适配不同的 Agent 使用方式。库模式：在 Python 或 TypeScript 中 from headroom import compress; compressed = compress(messages)。代理模式：headroom proxy --port 8787——任何兼容 OpenAI API 的工具无需改代码即可获得压缩上下文。Agent 封装：headroom wrap claude|codex|cursor|aider|copilot——直接封装 Agent 进程，使其所有 I/O 经过 Headroom。MCP 服务器：运行 headroom mcp install 将 headroom_compress、headroom_retrieve、headroom_stats 暴露为 MCP 工具，任何 MCP 客户端都可以调用。所有模式都支持跨 Agent 记忆——一个共享存储，跨 Claude、Codex、Gemini 等去重并压缩上下文。
Install with pip install "headroom-ai[all]" or npm install headroom-ai. Then pick a mode: run headroom wrap claude to wrap Claude Code, or headroom proxy --port 8787 for a drop-in proxy. For inline use, from headroom import compress and call compress(messages). Run headroom stats to see token savings. For TypeScript, use await compress(messages, { model }). The CLI also provides headroom learn, which mines failed agent sessions and writes corrections to CLAUDE.md or AGENTS.md. The Docker image is available at ghcr.io/chopratejas/headroom:latest.
安装：pip install "headroom-ai[all]" 或 npm install headroom-ai。然后选择模式：运行 headroom wrap claude 封装 Claude Code，或 headroom proxy --port 8787 启动即插即用的代理。想在代码里直接使用：from headroom import compress 然后调用 compress(messages)。运行 headroom stats 查看 Token 节省量。TypeScript 中：await compress(messages, { model })。CLI 还提供 headroom learn 命令，它会挖掘失败的 Agent 会话，自动将修正写入 CLAUDE.md 或 AGENTS.md。Docker 镜像可以直接拉取 ghcr.io/chopratejas/headroom:latest。
On real agent workloads, Headroom demonstrates 47–92% token reduction: code search (92%), SRE incident debugging (92%), GitHub issue triage (73%), codebase exploration (47%). Standard benchmarks show no accuracy loss: GSM8K math (0.870 vs 0.870), TruthfulQA factual (0.530 vs 0.560, slight improvement), SQuAD v2 QA (97% accuracy at 19% compression), BFCL tool calling (97% accuracy at 32% compression). These results are reproducible via python -m headroom.evals suite --tier 1.
在真实的 Agent 工作负载上，Headroom 实现了 47–92% 的 Token 缩减：代码搜索（92%）、SRE 事故排查（92%）、GitHub Issue 分类（73%）、代码库探索（47%）。在标准基准测试中精度保持不变：GSM8K 数学推理（0.870 vs 0.870）、TruthfulQA 事实性（0.530 vs 0.560，略有提升）、SQuAD v2 问答（97% 准确率，19% 压缩率）、BFCL 工具调用（97% 准确率，32% 压缩率）。这些结果可以通过 python -m headroom.evals suite --tier 1 复现。
Headroom is a great fit if you run AI coding agents daily and want to cut token costs without changing code; if you work across multiple agents and want shared, deduplicated memory; or if you need reversible compression where originals are always retrievable. Skip it if you rely solely on a single provider's native compaction and don't need cross-agent memory, or if you work in a sandboxed environment where you can't run local processes.
Headroom 非常适合：日常使用 AI 编程 Agent 并希望在不改代码的前提下降低 Token 成本；跨多个 Agent 工作并需要共享、去重的上下文记忆；或者需要可逆压缩，随时可以取回原始内容。不适合：仅依赖单一供应商的原生压缩且不需要跨 Agent 记忆；或者工作在无法运行本地进程的沙箱环境中。