headroomlabs-ai/headroom

它解决的问题

AI 代理会读取大量上下文——工具输出、日志、RAG 块、文件和对话历史——而每个 token 都会带来成本和延迟。长时间运行的代理会话，尤其是工具输出量大的场景，通常会发送远超模型实际需要的 token，却仍然为完整提示词付费。Headroom 在上下文到达 LLM 之前将其压缩，保留重要部分（如错误行），同时显著减少 token 使用量。压缩在本地进行，因此提示词或文件内容不会离开你的机器。

工作原理

Headroom 位于你的代理/应用和 LLM 提供商之间。它检查每个内容块，检测其类型（JSON、源代码、散文、图像），并应用最佳压缩器：

• ContentRouter 选择压缩器。
• SmartCrusher 处理 JSON 数组和嵌套对象，根据字段方差保留异常值、错误项和边界。
• CodeCompressor 对多种编程语言具有 AST 感知能力。
• Kompress-v2-base 是一个 HuggingFace 模型，针对代理轨迹的散文进行了训练。
• CacheAligner 标记易变内容，这些内容会破坏提供商的 KV 缓存前缀，而无需重写提示词。
• CCR（缓存与压缩可逆）在本地存储原始内容，以便模型可以通过 headroom_retrieve 按需检索完整文本。

压缩后，较小的提示词加上检索工具会发送给 LLM。你可以将 Headroom 作为库集成（Python/TypeScript 中的 compress()），作为端口上的代理（零代码更改），作为代理包装器（headroom wrap 支持 20 多种代理），或作为 MCP 服务器。还有 headroom learn，它读取过去的会话以调整详细程度，以及输出 token 减少功能，该系统提示词中附加简洁性说明，以减少模型写回的内容。

适用人群

适合日常运行编码代理并希望在不更改代码的情况下降低 token 成本的开发者和团队。如果你使用多个代理（Claude Code、Codex、Cursor 等）并希望共享一个内存存储，或者你需要可逆压缩以便在 TTL 内保留原始内容，那么它非常合适。对于短对话交流、散文密集型任务或无法运行本地进程的环境，它的用处较小。

亮点

• 本地压缩：压缩过程中不会将任何数据发送到任何地方。
• 多种集成模式：库、代理、代理包装器、MCP 和跨代理内存。
• 已验证的节省：在真实场景中节省 30–57%（例如，事件调试案例中 55,957 → 24,340 个 token），在重复的 JSON/日志上节省更多。
• 亚毫秒级延迟（10K token JSON 的 p50 为 0.21 毫秒，100K 时为 1.4 毫秒），因此不会影响代理响应速度。
• 保持准确性：基准测试显示没有显著退化（例如 GSM8K、TruthfulQA、SQuAD v2、BFCL）。
• 通过 CCR 实现可逆压缩：模型可以在需要时检索完整上下文。
• 输出 token 减少：修剪模型编写的文本，并提供可测量或估计的节省报告。