headroomlabs-ai/headroom

解決的問題

Headroom 透過減少送至與從大型語言模型（LLM）接收的 token 數量，降低 AI 代理的成本並減少延遲。它特別針對工具輸出、日誌、RAG 區塊和對話歷史中常見的「儀式性」與重複資料，這些資料經常導致代理提示膨脹。

工作原理

Headroom 作為位於 AI 代理與 LLM 提供者之間的本地壓縮層。它使用 ContentRouter 檢測資料類型並應用適當的壓縮方法：

• SmartCrusher：利用統計變異處理 JSON 資料，保留關鍵資訊的同時去除冗餘。
• CodeCompressor：利用抽象語法樹（AST）感知能力，壓縮多種語言的原始碼。
• CodeCompressor：使用在代理軌跡上訓練的專用 HuggingFace 模型（Kompress-v2-base）壓縮文字。
• CCR（可逆壓縮）：將原始內容本地儲存，必要時可透過工具呼叫取得完整文字。
• CacheAligner：確保易變內容不會破壞提供方的 KV 快取前綴，維持快取命中率。

可作為程式庫（Python/TypeScript）、無需程式碼變更的即插即用代理，或用於流行代理（如 Claude Code、Cursor、Aider）的包裝器部署。

適用對象

每天使用程式碼代理的開發者與進階使用者，跨多個不同 AI 代理工作並希望擁有共享記憶體儲存的使用者，以及希望在不犧牲準確性的前提下降低 LLM API 成本的任何人。

主要亮點

• 多模態壓縮：針對 JSON、程式碼與文字的專用壓縮器。
• 代理包裝：透過單一指令 headroom wrap 快速設定大量 AI 代理與 IDE 延伸模組。
• 輸出 token 減少：透過引導模型減少冗餘表達並調整常規任務的推理努力，縮短模型回應。
• 跨代理記憶：在不同 LLM 提供方之間共享、去重的上下文儲存。
• headroom learn：分析失敗會話，自動將修正寫入代理設定檔。
• 本地執行：所有壓縮均在使用者裝置上完成；壓縮過程中不會將資料傳送至外部伺服器。