Headroom：给 AI Agent 的上下文压缩层

一句话定位

Headroom 是一个面向 AI Agent 和 LLM 应用的上下文压缩层，用来在工具输出、日志、文件、RAG 片段进入模型之前先做压缩，从而减少 token 消耗，同时尽量保持回答质量。

基础信息卡片

解决什么问题

AI Agent 真正跑起来后，最容易失控的不是单次 prompt，而是上下文不断膨胀。

一次代码搜索可能返回几十上百条结果；一次线上故障排查会产生大量日志；一个 RAG 应用会把多段文档塞进上下文；一个长期运行的 coding agent 还会不断积累工具调用、文件内容和历史对话。

这些内容直接进入 LLM，会带来几个明显问题：

• token 成本上升，尤其是多轮 Agent 工作流；
• 上下文窗口被日志、重复内容和低价值片段占满；
• 模型更容易被噪声干扰，关键错误或关键证据反而被淹没；
• 不同 Agent、不同工具之间很难共享压缩后的上下文和历史信息；
• 想接入压缩能力时，往往需要改应用代码或重做调用链。

Headroom 的思路是把“上下文压缩”变成一个独立层：工具输出、日志、文件、RAG chunks、对话历史先经过 Headroom，再进入模型。这样既可以降低 token 压力，也能让 Agent 保留更多真正有用的信息。

核心功能

多种接入方式

Headroom 不只是一段压缩函数，而是提供了几种接入模式：

• Library：在 Python 或 TypeScript 应用里直接调用 compress(messages)；
• Proxy：通过 headroom proxy --port 8787 作为 OpenAI-compatible 代理接入；
• Agent wrap：用 headroom wrap claude|codex|cursor|aider|copilot 包装常见 coding agent；
• MCP Server：提供 headroom_compress、headroom_retrieve、headroom_stats 等 MCP 工具。

这意味着它既适合开发者在应用里集成，也适合直接接到现有 Agent 工作流前面。

面向不同内容的压缩策略

Headroom README 里提到，它会根据内容类型选择不同压缩方式：

• JSON 输出可以走 SmartCrusher；
• 代码内容可以走 CodeCompressor / AST 相关压缩；
• 普通文本可以走 Kompress-base；
• 通过 ContentRouter 判断内容类型并分发到合适路径。

这点很重要，因为日志、JSON、源码、文档并不适合同一种压缩方式。对 Agent 场景来说，压缩不是简单截断，而是要尽量保留后续推理需要的线索。

可逆压缩与按需取回

Headroom 强调 reversible / CCR 机制：原始内容会在本地缓存，压缩后的上下文进入模型；如果模型后续需要更完整的信息，可以再通过 headroom_retrieve 取回原文。

这个设计比“一刀切摘要”更适合 Agent。因为很多时候模型一开始不需要全部细节，但在定位 bug、核对日志、查看某个文件片段时，又需要能回到原始内容。

Agent 兼容和跨 Agent 记忆

项目直接面向 Claude Code、Codex、Cursor、Aider、Copilot CLI 等工具，同时也支持 OpenAI-compatible proxy 和 MCP-native 客户端。

它还提供 cross-agent memory，让不同 Agent 可以共享本地存储的上下文和纠错信息。对于同时使用多个 coding agent 的团队来说，这个方向很值得关注。

效果验证

README 中给出的样例显示，在真实 Agent workload 上，Headroom 可以把部分任务的 token 使用量压缩 60–95%。例如代码搜索、SRE incident debugging、GitHub issue triage 等场景，都属于典型的高上下文、高噪声任务。

更关键的是，它不是只追求“压得更短”，而是强调 same answers / accuracy preserved，也就是压缩后仍要保持回答质量。

适合谁

Headroom 适合这些团队和开发者优先看看：

• 正在做 AI Agent、coding agent、RAG 应用或自动化工作流的开发者；
• 经常把日志、搜索结果、代码片段、长文档塞进模型上下文的团队；
• 希望降低 LLM token 成本，但不想牺牲太多回答质量的应用；
• 使用 Claude Code、Codex、Cursor、Aider、Copilot CLI 等工具做复杂任务的人；
• 想通过 MCP 给 Agent 增加上下文压缩和检索能力的用户；
• 正在研究 context engineering、context window 管理、Agent 记忆机制的技术团队。

快速上手

如果使用 Python，可以直接安装：

pip install "headroom-ai[all]"

如果使用 Node / TypeScript：

npm install headroom-ai

常见使用方式有三种。

第一种是包装现有 Agent：

headroom wrap claude

第二种是启动代理，接到现有 OpenAI-compatible 调用链前面：

headroom proxy --port 8787

第三种是在应用代码里直接使用压缩能力：

from headroom import compress

compressed = compress(messages)

安装后也可以先跑一次性能测试，看看在当前环境下能节省多少上下文：

headroom perf

结论

Headroom 值得推荐的地方在于，它抓住了 AI Agent 应用里一个越来越实际的问题：上下文不是越多越好，关键是如何把有用信息留给模型，把重复和噪声压下去。

如果你只是偶尔和 ChatGPT 对话，可能暂时用不上它。但如果你已经在构建 Agent、RAG、代码助手、自动化排障工具，或者每天都在让模型读取大量文件、日志和工具输出，Headroom 这种上下文压缩层就很有价值。

它不是替代 LLM，也不是替代 Agent 框架，而是更像一层基础设施：放在模型前面，帮你节省 token、延长可用上下文，并让 Agent 更稳定地处理长任务。对于正在做 AI 工程化和 Agent 工具链的人来说，这个项目值得收藏和试用。