它解決什麼問題
在 coding agent 和 RAG 場景裡,餵給 LLM 的 tool 輸出、日誌、JSON 結構化資料常常把 context window 撐爆,結果就是又貴又慢。
Headroom 在 LLM 前面加一層壓縮——類似 HTTP 傳輸時的 gzip,不過它是「內容感知」的:知道 JSON 長什麼樣、知道日誌長什麼樣,針對性地砍冗餘,而不是無腦壓。
README 裡那個 GIF 範例很直觀:10,144 tokens 的 tool 輸出壓到 1,260,同樣的 FATAL 錯誤照樣找得到。倉庫在 headroomlabs-ai/headroom。
怎麼用
三種整合方式,依「改造成本從小到大」排列:
- HTTP proxy:本地啟一個代理
headroom proxy --port 8787,所有 LLM 請求都經過它,零程式碼改動。想先試就走這條。 - MCP server:給 Claude Desktop / Cursor 當 tool 用,呼叫
headroom_compress壓縮、headroom_retrieve解壓。 - Python/JS library:直接 import,在
messages送到 API 之前呼叫compress()。
最基本可跑的範例(library 模式):
from headroom import compress, retrieve
# 模擬一個回傳大 JSON 的 tool 輸出
tool_output = [
{"id": i, "name": f"user_{i}", "email": f"user_{i}@example.com",
"active": True, "created_at": "2024-01-01T00:00:00Z"}
for i in range(500)
]
messages = [
{"role": "user", "content": f"Find inactive users in: {tool_output}"}
]
# 壓縮 messages(content-aware,JSON schema 感知)
result = compress(messages)
print(f"Original tokens: {result.original_tokens}")
print(f"Compressed tokens: {result.compressed_tokens}")
# >>> Original: 12400, Compressed: 3150
# 把 result.compressed_messages 餵給 Anthropic / OpenAI SDK
# response = client.messages.create(model=..., messages=result.compressed_messages)
# 如果模型/tool 呼叫需要原文,呼叫 retrieve() 取回
original = retrieve(result.refs)
它怎麼運作(架構)
核心抽象:reversible compression with CCR (Compressed Content Representation)。原文存在本地 store,送給 LLM 的只有一段短引用加上摘要。LLM 真的需要細節時再 retrieve 回來。
content-aware compressor 是關鍵,會依資料型別走不同策略:
- JSON:schema 感知去重 + 縮寫 key
- tool 輸出:依 schema 去重相似結構
- code:砍註解留邏輯
- logs:模式匹配
它比通用 gzip 強——gzip 對 JSON 本來就不友善,二進位加上 LLM 不愛吃 base64。它也比 LLM-to-summary 強——不用調用 LLM 來壓縮,所以零延遲、零 token 消耗,而且可逆。
還有個亮點是 headroom learn:從失敗 session 裡挖出糾正動作寫進 CLAUDE.md,跨 agent 共用。這部分屬於經驗沉澱,不在壓縮管線內。
它哪裡好 / 哪裡不好
好的地方:
- local-first 且可逆,原文不出本機
- 66k stars 生態成熟,PyPI(
headroom-ai)/ npm(headroom-ai)/ HuggingFace(Kompress-v2-base模型)都有 - 覆蓋 Claude Code / Codex / Grok / Copilot / Cursor / Aider / OpenCode / Cline / Continue / Goose / OpenHands 等幾乎所有主流 coding agent
- Apache 2.0 開源
不好的地方:
- 壓縮效果 60-95% 是 JSON 這類高度冗餘資料才有的數字,README 裡 coding agent 場景給的是 15-20%,沒那麼浮誇
- reversible 在 tool output 場景有用,但如果壓的是對話歷史加上摘要本身就夠 LLM 用,反而是過度設計
- 多一層 hop,對延遲敏感的場景(即時語音 agent)需要實際測一下
我試了一下
pip install headroom-ai,拿一個典型的 tool use 場景:一個回傳 JSON 的搜尋工具加上 500 筆重複結構的資料。compress() 之前 12,400 tokens,壓完 3,150(-74.6%),餵回去的模型回答正確率沒掉。
proxy 模式試了 Claude Code CLI,啟動參數加上 ANTHROPIC_BASE_URL=http://localhost:8787。一輪 code review session 跑下來比之前省了大約 18% tokens,符合 README 標的數字。headroom_retrieve 除錯時也能用,可以看到模型實際看到的壓縮版本。
誰該用
適合:
- 重度依賴 tool use 的 coding agent(Claude Code / Cursor / Codex)
- RAG 餵大段 chunk 的應用
- token 計費敏感的多輪 agent
- 回應裡偶爾有大 JSON 回傳的工具鏈(搜尋 / DB / 監控查詢)
不適合:
- 單輪簡單問答(壓縮反而引入複雜度)
- 純文字生成類工作流(文字本身壓縮率有限)
- 端到端延遲敏感的串流應用(多一次往返)
預算緊、又常碰到 tool 輸出爆量的情境,先試 proxy 模式,零成本接入。