headroomlabs-ai/headroom

Headroom – AI 代理的上下文壓縮層

它是什麼 – Headroom 是一個函式庫、CLI 和代理，用於壓縮基於語言模型的代理所傳送的輸入（工具輸出、日誌、RAG 區塊、檔案、對話歷史），並可修剪模型寫回的輸出。壓縮完全在使用者機器上進行；不會有任何資料傳送到遠端服務進行處理。

為什麼重要 – 大型語言模型 (LLM) API 是按 Token 計費的。在編碼助理的工作流程中，單一請求可能包含數萬個 Token（例如長日誌轉儲或搜尋結果）。Headroom 在實際場景中可將這些 Token 數量減少 20‑60%，同時保持模型的回答不變。由於處理是在本地且快速（每 10 K‑token 負載小於 1 毫秒），延遲影響可忽略不計。

---

核心組件

組件	角色
compress(messages) (Python / TypeScript)	您可以從任何程式碼呼叫的內聯函式，以取得聊天訊息列表的壓縮版本。
headroom proxy	一個本地 HTTP 代理（預設為 --port 8787），任何相容 OpenAI 的客戶端皆可指向它，無需更改任何程式碼。
headroom wrap <agent>	針對熱門編碼代理（Claude、Codex、Grok、Cursor、Copilot 等）的一鍵封裝工具，可啟動代理、安裝選用輔助工具（例如 Serena 程式碼導航工具），並設定代理透過 Headroom 路由。
MCP server	為任何 Multi‑Component Protocol 客戶端提供 RPC 端點（headroom_compress、headroom_retrieve、headroom_stats）。
跨代理記憶體	一個共享儲存庫，可跨不同代理對壓縮的上下文進行去重，讓 Claude、Codex、Gemini 等可以重複使用相同的壓縮負載。
CCR (可逆壓縮)	原始、未壓縮的文字會在本機快取；當 LLM 需要完整內容時，可透過 headroom_retrieve 要求取回。
headroom learn	分析失敗的會話，提取修正提示詞，並將其寫入 Markdown 檔案（CLAUDE.local.md、AGENTS.md 等）以供未來執行使用。

---

運作原理（概覽）

1. ContentRouter 檢查每份資料（JSON、原始碼、純文字、影像）並選擇適當的壓縮器。
2. SmartCrusher 處理通用 JSON，CodeCompressor 處理多種程式語言的 AST，而 Kompress‑v2‑base（一個 HuggingFace 模型）則壓縮自然語言文字。
3. CacheAligner 標記會破壞供應商 KV‑cache 前綴的揮發性片段，確保壓縮永遠不會干擾快取命中。
4. 壓縮後的負載會傳送給 LLM 供應商（Anthropic、OpenAI、Bedrock 等）。如果模型稍後要求完整文字，CCR 會從本地快取中取回原始資料。
5. 模型回覆後，Headroom 也可以塑造輸出：它會在系統提示詞中加入簡潔指令，並減少模型在純延續回合中的「思考努力」，在實務上可減少約 30% 的輸出 Token。

---

快速入門 (≈60 秒)

# 安裝 (Python, CLI, 以及選用的代理擴充功能)
uv tool install --python 3.13 "headroom-ai[all]"   # 或 pip install "headroom-ai[all]"
npm install headroom-ai                               # 僅限 TypeScript SDK

# 部署本地代理並封裝代理 (範例: Claude Code)
headroom deploy               # 設定本地伺服器與設定檔
headroom wrap claude          # 啟動代理並透過它執行 Claude Code

# 驗證運作並查看節省量
headroom doctor               # 健康檢查
headroom dashboard            # 即時 Token 節省檢視 (代理必須執行中)

在程式碼中，您可以直接呼叫該函式庫：

from headroom import compress
from openai import OpenAI

msgs = [{"role": "user", "content": "Analyze these results"}]
compressed = compress(msgs, model="gpt-4o")
client = OpenAI()
resp = client.chat.completions.create(model="gpt-4o", messages=compressed.messages)
print(f"Saved {compressed.tokens_saved} tokens ({compressed.compression_ratio:.0%})")

---

代理相容性

Headroom 為許多編碼助理提供開箱即用的 wrap 指令（Claude Code、Codex、Grok CLI、Cursor、Aider、Copilot CLI、VS Code Copilot、OpenHands、Mistral Vibe、Kimi CLI、ZCode 等）。任何相容 OpenAI 的客戶端只需指向本地代理 URL 即可使用。

---

效能測量

場景	壓縮前 Token	壓縮後 Token	節省量
SRE 事件偵錯	55,957	24,340	57 %
程式碼搜尋 (100 個結果)	17,199	13,597	21 %
程式碼庫探索	58,801	33,895	42 %
GitHub 問題分類	46,067	32,429	30 %

延遲: 10 K‑token JSON 負載的 p50 為 0.21 毫秒，100 K tokens 為 1.4 毫秒 – 遠低於典型的 LLM 請求延遲。

準確度: 在 GSM8K、TruthfulQA、SQuAD v2 和工具使用套件上的基準測試顯示，模型品質沒有可測量的下降（例如 TruthfulQA 0.530 → 0.560，在信賴區間內）。

---

何時使用 / 何時跳過

適合 – 您執行的編碼代理經常攝取大量工具輸出、日誌或 RAG 區塊；您希望在不修改現有程式碼的情況下節省 Token 成本；您需要可逆壓縮或跨多個代理的共享記憶體。

跳過 – 您的工作負載已經很小（短對話回合、密集散文），或者您完全依賴供應商內建的壓縮功能，且不需要跨代理記憶體。

---

限制與注意事項

• 壓縮對於重複或結構化資料（JSON 陣列、日誌）最有效。純散文或已壓縮的負載減少幅度較小。
• 短於 min_input_words 閾值的區塊將保持不變，以保留 KV‑cache 前綴。
• 除非您保留一個保留集 (HEADROOM_OUTPUT_HOLDOUT)，否則輸出塑造僅為估計值。儀表板會報告信賴區間。
• 代理必須保持執行狀態才能封裝代理；停止它會透過 headroom unwrap 還原原始設定。

---

深入了解

• 文件與架構 – https://docs.headroomlabs.ai/docs/architecture
• 模型卡 – https://huggingface.co/chopratejas/kompress-v2-base
• 即時演示 GIF – 顯示 10 K‑token 日誌壓縮至 1.2 K tokens，同時保留 FATAL 行。
• Discord 社群 – https://discord.gg/yRmaUNpsPJ

---

總結

Headroom 是一個本地執行的開源壓縮層，可大幅減少編碼助理工作流程中傳送給 LLM 以及從 LLM 返回的 Token 數量。它作為函式庫、即插即用的 HTTP 代理或數十種熱門代理的一鍵封裝工具運作，提供 20‑60% 的 Token 節省量，且開銷小於 1 毫秒，且不會損失回答品質。