Headroom：在本地压缩 Agent 上下文并按需取回原始内容
一分钟看懂
Headroom 是一个面向 AI Agent 和大模型应用的上下文压缩工具。它在工具输出、日志、文件、RAG 检索片段和对话历史进入模型前进行本地压缩，并缓存原始内容供模型按需取回，目标是减少令牌用量而不改变主要答案。
你可以用它做什么
- 压缩编程 Agent 读取的搜索结果、日志、JSON、源代码和长文件。
- 作为 Python 或 TypeScript 库嵌入应用，在发送请求前处理消息。
- 运行本地代理，让兼容 OpenAI 或 Anthropic 接口的客户端无需大改代码即可接入。
- 通过 MCP 服务向客户端提供压缩、取回和统计工具。
- 在 Claude Code、Codex、Cursor、OpenCode 等多个 Agent 之间共享本地记忆。
- 查看不同内容类型和会话的令牌节省情况。
主要能力
Headroom 会先识别内容类型，再分别使用针对 JSON、源代码和普通文本的压缩方式。原始内容保存在本地缓存中，模型可以通过检索工具恢复完整片段。项目同时提供命令行包装器、本地代理、Python 与 TypeScript SDK、MCP 服务、共享记忆和会话学习功能。官方还提供可复现的基准脚本，用于衡量不同场景的压缩比例和答案变化。
适合哪些人
- 经常让编程 Agent 读取大量日志、搜索结果和代码的开发者。
- 构建 RAG、工具调用或长上下文应用的 AI 工程团队。
- 希望在多个 Agent 工具之间共享记忆和纠错经验的用户。
- 需要控制模型输入成本，并愿意用真实流量验证压缩效果的团队。
怎么开始使用
Python 用户可以安装 headroom-ai[all]，然后运行 headroom deploy 完成本地部署，或使用 headroom wrap claude、headroom wrap codex 等命令启动经过代理的 Agent。也可以运行 headroom proxy --port 8787 作为兼容接口代理，或直接在代码中调用 compress(messages)。TypeScript 的 npm 包只提供 SDK，不包含命令行工具。安装后可用 headroom doctor 检查配置，并通过性能和仪表盘命令观察效果。
使用前需要知道
项目采用 Apache License 2.0，压缩过程和缓存默认在本机运行。官方展示的节省比例来自特定基准，不同数据的重复程度和结构差异很大，普通文本或已经紧凑的内容可能几乎无法压缩，生产环境应基于自己的请求评测准确率和成本。代理模式会处理发送给模型的提示词、工具输出和文件内容，部署时需要审查监听地址、访问权限、日志和缓存位置，避免共享机器上的敏感数据暴露。自动包装会修改部分 Agent 配置，停止使用时应通过对应的 unwrap 命令恢复。