headroomlabs-ai/headroom

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

解决的问题

Headroom 是一个上下文压缩层，旨在减少发送给 LLM 和从 LLM 接收的 Token 数量。它通过压缩工具输出、日志、RAG 分块、文件和对话历史，解决 AI Agent 高昂的成本和 Token 限制问题，在不牺牲准确性的情况下，通常可将 JSON 的 Token 使用量降低 60-95%，将编程 Agent 的使用量降低 15-20%。

工作原理

Headroom 作为一个本地优先的代理 (proxy)、库或 MCP 服务器，位于 AI Agent 和 LLM 提供商之间。它使用 ContentRouter 来检测内容类型并应用特定的压缩器：

  • SmartCrusher: 用于 JSON 数据。
  • CodeCompressor: 针对多种编程语言的 AST 感知压缩。
  • Kompress-v2-base: 用于散文/文本的专用 HuggingFace 模型。
  • CacheAligner: 确保前缀保持稳定，以最大化提供商的 KV 缓存命中率。
  • CCR (可逆压缩): 在本地缓存原始内容，允许 LLM 在需要时通过工具调用检索完整版本。

它还可以通过引导模型趋向简洁以及调整常规步骤的推理力度来减少输出 Token。

适用对象

  • 希望降低成本和延迟的 AI 编程 Agent（如 Claude Code, Cursor, Aider）开发者。
  • 需要在不同 LLM 之间实现共享、去重内存的多 Agent 工作流构建团队。
  • 通过 Python 或 TypeScript SDK 集成 LLM 应用的开发者。

亮点

  • 多种部署模式：可作为即插即用的代理、内联库或 MCP 服务器使用。
  • Agent 封装：通过单条命令即可封装多种 Agent（例如 Claude Code, Copilot CLI, Grok）。
  • 输出缩减：修剪模型前导语并调整推理力度，以节省昂贵的输出 Token。
  • 跨 Agent 内存：可在 Gemini, Grok 和 Claude 等不同提供商之间工作的共享上下文存储。
  • 失败挖掘：headroom learn 命令通过分析失败的会话来将修正写入 Agent 配置文件。