Headroom 是一個專為 AI Agent 與大型語言模型應用打造的開源上下文壓縮工具，主要目標是在不影響回答品質的前提下，大幅降低送入 LLM 的 Token 數量。它能夠在資料真正傳送至模型之前，先對工具輸出、日誌、RAG 檢索內容、檔案以及對話歷史進行壓縮，藉此減少 API 成本、提升推論效率，同時保留必要資訊。
相較於傳統的摘要工具或單純截斷上下文的方式，Headroom 更強調「在維持相同答案的情況下，用更少的 Token 完成任務」。官方展示案例中，原本超過一萬個 Token 的內容經過處理後，可以壓縮至約一千多個 Token，同時仍能找出相同的錯誤資訊。對於需要處理大量上下文的 AI Agent、RAG 系統以及程式碼助手來說，這種能力能有效降低模型使用成本。
Headroom 的設計並非取代現有模型，而是作為 AI 應用與 LLM 之間的一層中介。它能夠分析不同類型的資料，並自動選擇最適合的壓縮方式，再將處理後的內容送往 OpenAI、Anthropic 或其他模型服務。
主要功能包括：
- 對話歷史與上下文壓縮
- Tool Output 與日誌資料壓縮
- RAG 檢索內容最佳化
- Python 與 TypeScript 函式庫支援
- Proxy 模式，無需修改程式碼
- Claude、Codex、Cursor、Aider 等 Agent 整合
- MCP Server 支援
- 跨 Agent 共用記憶體
- 自動學習失敗案例並更新知識文件
- 可逆式壓縮（CCR）
其中較特別的是可逆式壓縮（CCR，Compression with Content Retrieval）機制。Headroom 不會直接刪除原始內容，而是將完整資料保留於本地端，當模型需要更多細節時，再透過 headroom_retrieve 動態取回。這種做法能兼顧 Token 效率與資訊完整性，避免因過度摘要而遺失重要內容。
在內部架構方面，Headroom 透過 ContentRouter 自動判斷內容類型，再交由不同模組進行處理。例如 SmartCrusher 專門壓縮 JSON 結構資料、CodeCompressor 利用 AST 分析程式碼，而 Kompress-base 則負責一般文字內容。另一個 CacheAligner 元件則會穩定上下文前綴，提高模型供應商 KV Cache 的命中率，進一步提升效能。
除了壓縮功能之外，Headroom 也提供 Cross-Agent Memory 機制，讓 Claude、Codex、Gemini 等不同 Agent 能共用記憶體並自動去除重複資訊。此外，headroom learn 功能還能分析失敗案例，並將修正建議寫入 CLAUDE.md 或 AGENTS.md，協助 Agent 持續累積知識。
從使用情境來看，Headroom 特別適合：
- AI Agent 開發者
- RAG 系統建置者
- LangChain 與 Agent Framework 使用者
- 大型程式碼助手應用
- 高 Token 成本的 LLM 工作流程
- 多 Agent 協作環境
與傳統記憶管理工具相比，Headroom 最大的差異在於它並非單純儲存對話歷史，而是建立一套智慧型上下文壓縮與檢索機制。它試圖解決大型語言模型面臨的上下文成本問題，讓 AI Agent 能夠在保留完整資訊的同時，以更少的 Token 執行任務。
整體而言，Headroom 更像是一個位於 AI Agent 與 LLM 之間的「上下文優化層」。透過智慧壓縮、跨 Agent 記憶體與可逆式內容檢索機制，它讓開發者能夠在不犧牲回答品質的情況下，降低模型成本並提升整體效率。對於正在建置 AI Agent、RAG 或多模型工作流程的開發者而言，Headroom 提供了一套相當值得關注的基礎設施方案。
