Headroom 上下文压缩层

Headroom 是什么

Headroom 是面向 AI Agent 的上下文压缩层。它在工具输出、日志、文件内容、RAG 片段以及对话历史进入 LLM 之前先做压缩，从而在保持答案基本一致的前提下大幅减少 token 消耗。官方给出的参考数据是：编码 Agent 场景约减少 20% token，JSON 类内容可减少 60%–95%。

压缩过程完全在本地执行，提示词和文件内容不会被发送到外部服务进行压缩。

核心能力

• Library：在 Python 或 TypeScript 应用中直接调用 compress(messages)。
• Proxy：以 headroom proxy --port 8787 启动本地代理，零代码改动，任何语言均可接入。
• Agent 包装：一条命令包装 Claude、Codex、Cursor、Aider 等编码 Agent，并可用 headroom unwrap 撤销。
• MCP Server：提供 headroom_compress、headroom_retrieve、headroom_stats 等工具，供任意 MCP 客户端使用。
• 跨 Agent 记忆：在 Claude、Codex、Gemini、Grok 之间共享一个带自动去重的记忆存储。
• 可逆压缩（CCR）：原文缓存在本地，模型需要时可按需检索完整内容。

工作原理

整体流程可以概括为：

Agent / 应用
   │ 提示词 · 工具输出 · 日志 · RAG 结果 · 文件
   ▼
Headroom（本地运行）
  CacheAligner → ContentRouter → CCR
                   ├─ SmartCrusher（JSON）
                   ├─ CodeCompressor（AST）
                   └─ Kompress-v2-base（文本）
   ▼
LLM 提供商（Anthropic · OpenAI · Bedrock 等）

• ContentRouter 识别内容类型并选择合适的压缩器。
• SmartCrusher / CodeCompressor / Kompress-v2-base 分别处理 JSON、源码与自然语言文本。
• CacheAligner 标记可能破坏提供商 KV-cache 前缀的易变内容，但不会改写提示词。
• CCR 在本地保存原文，模型可通过 headroom_retrieve 取回全文。

快速上手

安装方式（注意 CLI 仅随 PyPI 包提供）：

uv tool install --python 3.13 "headroom-ai[all]"
pip install "headroom-ai[all]"
npm install headroom-ai   # 仅 TypeScript SDK，无 CLI

选择一种使用模式：

headroom deploy              # 本地部署并配置 Agent
headroom wrap claude         # 包装编码 Agent
headroom proxy --port 8787   # 本地代理，零代码改动

在 Python 中内联使用：

from headroom import compress

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

适用与注意事项

Headroom 适合需要控制 token 成本、缓解上下文窗口压力的 Agent 与 RAG 应用。使用时建议：

• 对关键任务自行验证压缩前后答案一致性；
• 注意 Agent 包装模式会额外安装 Serena 等组件；
• 关注项目迭代带来的接口变化。