上下文压缩headroom

1. Headroom 是什么？

Headroom 是一个给 AI Agent / LLM 应用使用的上下文压缩层 。它的目标不是替换模型，也不是替换 RAG，而是在内容进入大模型之前，先把工具输出、日志、文件内容、RAG 片段、JSON、对话历史等"喂给模型的上下文"压缩掉冗余部分。官方描述是：压缩 AI Agent 读取的一切内容，在尽量保持答案不变的前提下减少 token。(github.com)

一句话理解：

Headroom = 放在 Agent 和 LLM API 之间的本地上下文瘦身器。

它适合 Claude Code、Codex、Cursor、Aider 这类 coding agent，也适合自研 Agent、RAG 应用、日志分析、JSON/API 响应分析等场景。PyPI 页面显示它支持 library、proxy、MCP、agent wrap 等多种形态，并标注 JSON 场景可减少 60--95% token、coding agent 场景约减少 15--20% token。(pypi.org)

---

2. 它解决什么问题？

Agent 执行任务时，经常会把很多"高噪声内容"塞进上下文，例如：

• grep / rg 搜索结果；
• 测试日志；
• API 返回的大 JSON；
• RAG 检索片段；
• 文件读取结果；
• 多轮对话历史；
• 工具调用返回的大段文本。

这些内容里常见问题是：

1. 重复信息很多；
2. 格式字段很多，但真正有价值的信息很少；
3. 错误、异常、关键代码被淹没在大量上下文里；
4. 上下文窗口被快速填满；
5. 输入 token 成本和延迟升高。

Headroom 做的事就是：在不让模型直接看到完整原始噪声的情况下，尽量保留能回答问题的关键信息。

---

3. 核心原理

3.1 插在 Agent 和模型之间

Headroom 通常位于：

Agent / 应用
   ↓
Headroom 压缩层
   ↓
OpenAI / Anthropic / Gemini / 其他 LLM Provider

它可以作为：

• SDK：你在代码里主动调用压缩函数；
• Proxy：让请求先打到本地 Headroom，再由 Headroom 转发给模型；
• Agent wrapper：直接包一层 Claude Code、Codex、Cursor 等工具；
• MCP server：给 MCP 客户端提供压缩、检索、统计工具。(pypi.org)

---

3.2 只压缩"活跃噪声区"，尽量保留稳定前缀

从官方 wiki 的 transforms 说明看，Headroom 不做简单的"按位置丢弃历史消息"或"只保留 top-k 消息"的上下文管理，而是更倾向于压缩最新的用户消息、工具结果、工具输出等内容块。(github.com)

可以简单理解为它区分两类内容：

Frozen Prefix：稳定前缀
- system prompt
- 历史稳定上下文
- 不希望频繁改动的内容

Live Zone：活跃区
- 最新工具输出
- 最新日志
- 最新 JSON
- 最新文件片段
- 最新 RAG 结果

这样做的目的有两个：

1. 减少 Live Zone 的 token 浪费；
2. 尽量不破坏模型服务商的 prompt cache / KV cache 命中率。

不过需要注意，GitHub issue 中也有人反馈过 Claude Code + Anthropic 后端下，代理模式可能导致 prompt cache 命中变差、反而增加成本的情况，所以实际接入时最好看自己的账单和统计数据验证。(github.com)

---

3.3 ContentRouter：先判断内容类型，再选择压缩器

Headroom 不是对所有文本用同一种摘要算法，而是更像一个内容路由器：

输入内容
   ↓
识别内容类型
   ↓
选择对应压缩策略
   ↓
生成压缩后的上下文

不同内容会走不同策略，例如：

• JSON / API 响应：走 SmartCrusher；
• 代码：走代码结构感知压缩；
• 普通文本 / 日志 / RAG：走文本压缩或相关性压缩；
• 对话 / 工具输出：结合缓存和可检索压缩机制。

---

3.4 SmartCrusher：针对 JSON 的统计压缩

SmartCrusher 是 Headroom 中比较核心的 JSON 压缩器。官方文档描述它会分析 JSON 数组，并保留重要元素，例如首尾元素、错误项、异常值、与用户问题相关的项、变化点等。(github.com)

它不是简单截断前 N 条，而是尽量保留：

• 错误项 ：例如 error、failed、异常状态；
• 异常值：统计上明显偏离的记录；
• 相关项：和用户 query 更相关的记录；
• 首尾项：保留分页、时间顺序、边界上下文；
• 变化点：数据发生明显变化的地方。

比如原始工具输出可能是：

{
  "results": [
    "... 1000 条搜索结果 ..."
  ]
}

压缩后可能只保留几十条关键结果，同时附带摘要信息。官方示例中提到可从 45,000 tokens 降到约 4,500 tokens，约 90% reduction。(github.com)

---

3.5 代码压缩：保留结构，减少细节噪声

对于代码内容，Headroom 的思路通常不是把代码随便摘要成自然语言，而是尽量保留结构信息，例如：

• 文件路径；
• 类 / 函数 / 方法签名；
• import / export；
• 关键分支；
• 错误附近代码；
• 与当前问题相关的代码块。

这类压缩更适合 coding agent，因为模型通常不需要每次都读完整文件，但需要知道"有哪些结构、哪里可能相关"。

---

3.6 CCR：可逆压缩 / 原文可检索

Headroom 还有一个重要概念是 CCR，可以理解为：

Compress → Cache → Retrieve
压缩 → 本地缓存原文 → 需要时再检索回来

核心思想是：

1. 先把长内容压缩成短内容；
2. 原始内容不直接丢弃，而是存在本地缓存；
3. 如果模型发现压缩内容不够，可以通过 retrieval 工具请求取回原始片段。

这让它不只是"一次性摘要"，而是更接近可回溯的上下文压缩系统 。PyPI 页面也把它描述为 local-first、reversible，并提供 headroom_retrieve 这类 MCP 工具。(pypi.org)

---

4. 怎么使用？

方式一：作为 CLI / Agent wrapper 使用

如果你主要是想给 Claude Code、Codex、Cursor、Aider 这类工具省 token，这是最轻量的方式。

安装：

pip install headroom-ai

如果需要更完整能力，可以安装 extras，例如：

pip install "headroom-ai[all]"

当前 PyPI 包名是 headroom-ai ，PyPI 页面显示当前版本为 0.32.0，发布日期是 2026 年 7 月 16 日，并要求 Python >= 3.10。(pypi.org)

包裹 Codex：

headroom wrap codex

包裹 Claude Code：

headroom wrap claude

撤销：

headroom unwrap codex

PyPI 和仓库说明里列出的 wrapper 包括 claude、codex、cursor、aider、opencode、cline、continue、goose 等。(pypi.org)

---

方式二：作为本地 Proxy 使用

适合你不想改业务代码，只想让现有应用通过 OpenAI-compatible / Anthropic-compatible 接口走一层代理。

启动本地代理：

headroom proxy --port 8787

然后把你的应用或 Agent 的 base URL 指向：

http://127.0.0.1:8787

官方说明中也把 proxy 模式定位为"zero code changes, any language"。(pypi.org)

适用场景：

• 自研 Agent；
• LangChain / LangGraph 应用；
• 已经支持自定义 OpenAI base URL 的工具；
• 公司内部统一代理层。

---

方式三：作为 Python / TypeScript Library 使用

如果你在写自己的 Agent，可以直接在代码里调用压缩逻辑。

概念上类似：

from headroom import compress

compressed_messages = compress(messages)

具体 API 需要以当前版本文档为准，但官方说明明确支持 Python 和 TypeScript library 方式。(pypi.org)

注意：PyPI 页面特别说明，CLI 来自 Python 包 headroom-ai；npm 的 headroom-ai 是 TypeScript SDK，不提供 headroom 命令 。(pypi.org)

---

方式四：作为 MCP Server 使用

如果你的客户端支持 MCP，可以通过 Headroom 提供的 MCP 工具进行压缩和检索，例如：

• headroom_compress
• headroom_retrieve
• headroom_stats

这适合把 Headroom 当成一个 Agent 工具，而不是透明代理。(pypi.org)

---

5. 使用建议

我会按场景这样选：

场景	推荐方式
你只是想给 Codex / Claude Code / Cursor 省 token	headroom wrap codex / headroom wrap claude
你有自研 Agent，但不想改代码	headroom proxy --port 8787
你在写 Python / TS Agent，需要精细控制	Library 模式
你用 MCP 生态，希望压缩能力作为工具出现	MCP Server
你主要处理 JSON、API 响应、日志	Headroom 比较适合
你处理的是审计、合规、精确法律文本	谨慎使用，先验证是否丢关键细节

---

6. 优点和风险

优点

• 减少 token 成本：尤其是 JSON、日志、工具输出场景；
• 减轻上下文窗口压力；
• 对 coding agent 友好；
• 支持本地运行；
• 支持代理、SDK、MCP、wrapper 多种接入方式；
• 可逆压缩思路比普通摘要更安全一些 。(pypi.org)

风险 / 注意事项

• 压缩不是无损理解：即使有 CCR，也可能影响模型第一轮判断；
• 关键长尾信息可能被压缩掉；
• 不同模型、不同 Agent 的收益差异很大；
• 代理层可能影响 provider prompt cache，尤其要看实际账单和缓存命中；
• 不要只看官方压缩率，要用自己的任务集验证；
• headroom learn 这类能力可能写入 CLAUDE.md、AGENTS.md 等文件，项目中使用前应确认是否符合团队规范 。PyPI 页面提到 headroom learn 可将失败会话中的修正写入 CLAUDE.local.md、CLAUDE.md、AGENTS.md 等文件。(pypi.org)

---

7. 总结

Headroom 的核心原理是：在 Agent 输出内容进入 LLM 之前，通过内容类型识别、专用压缩器、本地缓存和可检索机制，把高噪声上下文压缩成低 token、高信息密度的上下文。

它最适合：

• coding agent；
• 日志分析；
• 大 JSON 分析；
• RAG 输出压缩；
• 工具调用密集型 Agent；
• 想降低 LLM 输入 token 成本的应用。

如果你只是想体验，最简单路径是：

pip install headroom-ai
headroom wrap codex

如果你想更稳妥地评估，建议先在一个小项目中跑几天，对比：

• 总输入 token；
• 输出质量；
• prompt cache 命中；
• 平均延迟；
• 是否漏掉关键错误信息。