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 設定檔。