Headroom: AI Agent Context 壓縮代理層

headroomlabs-ai/headroom · Python/Rust · MIT
Context 優化層，透過多階段壓縮 pipeline + 可逆 CCR 架構，為 AI Agent 節省 60-95%% token。

不是另一個 Agent 框架，而是插在 Agent 和 LLM 之間的透明壓縮代理層。SmartCrusher 壓縮 tool output + CCR 可逆快取，讓 LLM 在需要時回溯原始內容。

核心架構

階段	功能	token 節省
CacheAligner	提取 system prompt 動態內容（日期/UUID），穩定 prefix 提高 KV cache 命中	間接 (cache hit)
SmartCrusher	統計方法壓縮 JSON array tool output，保留 errors/anomalies	主要來源
ContentRouter	依內容型別路由到 SmartCrusher(JSON) / CodeCompressor(AST) / Kompress-base(ML prose)	路由決策
ContextManager	Rolling Window 或 Intelligent Context (recency+semantic+TOIN 加權評分)	最終適配

CCR (Compress-Cache-Retrieve) 可逆架構

與論文 2606.10209 的單向 pruning 不同，Headroom 的 CCR 是可逆的：壓縮後的內容被快取，LLM 需要細節時可回溯取回原始內容。這解決了 pruning 的最大風險 — 丟掉後才發現需要。

面向	論文 2606.10209	Headroom
層級	語義層（整對 tool call 的留/丟/摘要）	Token 層（JSON/程式碼/散文壓縮）
可逆性	不可逆（pruned = 永久丟棄）	可逆（CCR cache 可回溯）
部署	研究原型	生產級 proxy
Provider	GPT-5 only	OpenAI/Anthropic/Gemini/Cohere + 100+ via LiteLLM

Provider 支援

方式	支援
Native SDK	OpenAI (GPT-4o), Anthropic (Claude), Google Gemini, Cohere Command
OpenAI-compatible	Ollama, vLLM, Together, Groq, Fireworks, LM Studio
LiteLLM callback	100+ providers (Bedrock, Azure, Vertex AI, Mistral)
Framework	LangChain, Agno, Strands, LiteLLM, OpenClaw plugin

智能模組

模組	功能
TOIN (Tool Output Intelligence Network)	學習壓縮模式，根據 LLM 回溯頻率調整策略
headroom wrap	Ephemeral agent proxying — 臨時包裝任何 agent 指令
headroom init	Persistent agent 設定 — 持續代理配置
headroom learn	Session 分析與失敗學習
RTK (Rust Token Killer)	Rust 原生高效 token 削減 + output shaping

對 Hermes 的整合評估

高價值：SmartCrusher 處理 tool output bloat
web_extract 和 browser_snapshot 常回傳數千 tokens HTML/JSON，大量是 noise。SmartCrusher 的統計壓縮直接命中這痛點。

中價值：CacheAligner 優化 KV cache
我們的 system prompt 含大量靜態指令。CacheAligner 穩定 prefix 可提高 provider 端 cache 命中率，降低延遲與成本。

低摩擦整合：LiteLLM callback
我們已有 litellm-model-proxy skill。Headroom 透過 LiteLLM callback 可無縫插入壓縮層，不需改 agent 程式碼。

風險
Rust core (headroom-proxy) 需在 ARM64 驗證編譯。CCR caching 的 latency overhead 需實測。Python-Rust bridge 的穩定性需評估。

與論文的互補定位