Headroom：在本地压缩 AI Agent 上下文的工具概览

工具定位

Headroom 面向 AI Agent 的上下文处理：在内容送达 LLM 之前，压缩工具输出、日志、RAG 检索片段、文件以及对话历史。按原文说明，压缩在本地机器运行，提示词和文件内容不会被发送到外部做压缩。

接入形态

原文列出多种使用方式：

• 库：Python 或 TypeScript 中调用 compress(messages)，内嵌到应用中。
• 代理：headroom proxy --port 8787，无需改代码，任何 OpenAI 兼容客户端可接入。
• Agent 包装：headroom wrap <tool> 为 Claude、Codex、Cursor、Aider 等提供一键配置，headroom unwrap 可撤销。
• MCP 服务：提供 headroom_compress、headroom_retrieve、headroom_stats 三个接口。
• 跨 Agent 记忆：Claude、Codex、Gemini、Grok 共用一份存储并自动去重。

注意：headroom 命令行只随 PyPI 包提供；npm 的 headroom-ai 仅为 TypeScript SDK，不含 CLI。

内部机制

请求经 CacheAligner、ContentRouter 分流：JSON 交给 SmartCrusher，源码交给基于 AST 的 CodeCompressor，散文交给 HuggingFace 上的 Kompress-v2-base 模型。CacheAligner 只标记可能击穿供应商 KV-cache 前缀的易变内容，不改写提示词。CCR 在本地缓存原文，模型需要时可调用检索取回全文，因此压缩是可逆的。压缩只作用于新增字节（“live zone”），已冻结的前缀保持字节不变，历史不被丢弃。

效果数据与边界

原文给出的四组基准由真实 MCP 输出格式构造、离线可复现：代码搜索 17,199→13,597（21%）、SRE 排障 55,957→24,340（57%）、代码库探索 58,801→33,895（42%）、GitHub issue 分诊 46,067→32,429（30%）。压缩延迟在 10K token JSON 上 p50 为 0.21 ms，100K token 为 1.4 ms（原文测试条件）。

节省幅度取决于内容重复度：重复的 JSON 数组和日志行可超过 90%，而散文和本身密集的输出压缩很少；短对话、已密集负载收益很小，低于 min_input_words 的块按原样返回。

准确性方面，GSM8K（N=100）从 0.870 到 0.870，TruthfulQA 从 0.530 到 0.560；原文指出 N=100 时 ±0.03 落在置信区间内，因此 TruthfulQA 视为无可检测差异，而非提升。SQuAD v2 在 19% 压缩率下为 97%，BFCL 在 32% 压缩率下为 97%。

适用与不适用

适合每天用编码 Agent、希望不改代码获得节省、或多 Agent 共用记忆且需要可逆压缩的用户。若只依赖单一供应商原生压缩、不需要跨 Agent 记忆，或运行环境无法启动本地进程，原文建议跳过。

安装与限制

原文给出 uv tool install --python 3.13 "headroom-ai[all]"、pip install "headroom-ai[all]"、npm install headroom-ai 和 Docker 镜像等安装方式，要求 Python 3.10+。[all] 不含框架适配器（LangChain、Agno、Strands 等需单独安装），[vector] 的 HNSW 后端需要 C++ 工具链且不在 [all] 内。原文内容在此处截断，Docker 标签、服务化等细节未完整呈现。