chopratejas/headroom 是一個給 AI Agent 做上下文壓縮的工具。它解決的問題很現實：Agent 一邊跑命令、一邊讀日誌、一邊搜尋程式碼、一邊塞 RAG 片段，很快就會把上下文視窗填滿，成本和延遲一起上來。
Headroom 的想法是：在內容進入 LLM 之前，先把工具輸出、日誌、檔案、RAG 片段和會話歷史壓縮一次。 README 裡寫的目標很直接：減少 60-95% token，同時盡量保持回答品質。
它解決什麼問題
現在很多 Agent 工具不是模型不夠聰明，而是上下文太髒：
grep、rg、日誌查詢一次回傳幾百上千行；- RAG 檢索片段重複、冗餘、格式混亂；
- JSON、stack trace、SQL 結果裡有大量低價值欄位；
- 多輪調試後，舊輸出佔上下文不走；
- Claude Code、Codex、Cursor、Aider 等工具各自維護上下文，難以共享記憶。
Headroom 做的是「進入模型前的清潔工」。它不取代 LLM，也不取代 RAG，而是在 LLM 前面加上一層壓縮、路由、快取和可回溯檢索。
核心能力
從 README 看，Headroom 主要有幾種使用型態：
- Library：在 Python 或 TypeScript 裡直接呼叫
compress(messages)； - Proxy：透過
headroom proxy --port 8787做 OpenAI-compatible 代理程式； - Agent wrap：用
headroom wrap claude|codex|cursor|aider|copilot包一層現有 Agent； - MCP Server：提供
headroom_compress、headroom_retrieve、headroom_stats給 MCP 用戶端使用； - Cross-agent memory：讓 Claude、Codex、Gemini 等工具分享本地記憶並自動去重；
headroom learn：從失敗會話挖礦經驗，寫入CLAUDE.md或AGENTS.md；- Reversible compression：原文不刪除，需要時可透過檢索工具取回。
這幾個形態很關鍵。它不是只能嵌入程式碼裡的 SDK，也不是只能當代理。你可以從最輕的 wrap 模式開始試，再決定要不要接到自己的應用程式。
它怎麼壓縮
Headroom 的架構有幾個關鍵字：
- ContentRouter：識別內容類型，選擇對應壓縮器；
- SmartCrusher：偏向處理 JSON 等結構化內容；
- CodeCompressor：偏向處理程式碼和 AST；
- Kompress-base：用於文字壓縮；
- CacheAligner：讓 prompt 前綴更穩定，提高提供者 KV cache 命中率；
- CCR：儲存原文，需要時再透過 retrieve 找回來。
換成人話說，它不是把所有內容都粗暴摘要成一段話，而是先判斷內容類型，再選不同壓縮策略。程式碼、JSON、普通文字、日誌和 RAG 片段，壓縮方式不應該一樣。
快速安裝
README 給出的安裝方式很直接：
|
|
Python 側需要 Python 3.10+。安裝後可以先試試這幾個指令：
|
|
如果你用的是 MCP 客戶端，可以走：
|
|
如果你只是想驗證效果，最簡單的是先跑 headroom perf，看它對典型工作負載能省多少 token。確認可用後，再把它接到 Claude Code、Codex、Cursor 或自己的 OpenAI-compatible 用戶端。
和普通摘要有什麼區別
普通摘要最大的問題是不可逆。日誌被總結成“資料庫連線失敗”，你就看不到原始錯誤碼、時間戳記、呼叫棧和上下文了。 Agent 後面如果需要細節，只能重新檢查。
Headroom 的一個重點是 reversible：原始內容保存在本地，壓縮後傳給模型；如果模型需要原文，再透過 headroom_retrieve 取回。這個設計更適合調試、程式碼搜尋和生產日誌分析，因為這些場景經常需要回到細節。
當然，這也意味著你要管理本地儲存和隱私邊界。雖然 README 強調 local-first，但只要你把壓縮後的內容發給雲端模型，還是要依照自己的資料安全要求處理。
適合哪些場景
我覺得 Headroom 最適合這些場景：
- Claude Code、Codex、Cursor 常常因為工具輸出太長而變慢；
- 用 Agent 分析大倉庫，搜尋結果和文件片段很容易爆上下文；
- SRE 排障時要把日誌、trace、設定和指令輸出交給模型看；
- 做 RAG 應用，檢索結果冗餘嚴重；
- 想在多個 Agent 工具之間分享本地記憶；
- 想把 MCP 工具連接到已有 AI 工作流程。
如果你只是偶爾問幾句聊天，或者 prompt 很短，就不一定需要它。 Headroom 的價值主要在「Agent 真正在工作」的時候出現。
使用時要注意什麼
上下文壓縮不是魔法。它能省 token，但也可能帶來新問題：
- 壓縮策略不合適時，模型可能拿不到關鍵細節；
- 程式碼和日誌場景要測試 retrieve 是否可靠；
- 接代理模式時，要確認請求到底經過哪些本地端和雲端環節；
- 團隊使用時，要定義好本機快取、會話記錄和敏感資料保留策略；
- 不要只看 token savings，也要看任務完成率和誤判率。
我的建議是用真實任務測試，而不是只看 demo。例如拿一組歷史 bug、CI 日誌、RAG 查詢和程式碼搜尋任務，分別比較「直接餵模型」和「經過 Headroom」後的成本、速度和答案品質。
Claude Code 原生 Token 與快取最佳化
Prompt Cache 快取的不是文字本身
Prompt Cache 不是簡單地把提示詞字串存起來。對 Transformer 模型來說，更關鍵的是前綴上下文經過注意力層計算後的 Key/Value 狀態，也就是常說的 KV cache。
這意味著兩個事實：
- 同一段上下文，只要前綴保持穩定，就可以在後續請求中複用一部分計算結果。
- 如果模型、工具定義、系統提示詞或前綴訊息發生變化，之前的快取就可能無法複用。
Anthropic 官方文件也把失效層級概括為 tools -> system -> messages。工具定義變化會影響整段快取，系統層變化會影響 system 和 messages，messages 層變化則主要影響訊息快取。
Claude Code 裡還會額外涉及 CLAUDE.md、Skills、MCP、外掛和子代理等上下文，所以實際使用時更容易踩到快取失效點。
快取殺手一：中途切換模型
切模型是影響最大的操作。
Prompt Cache 是按模型隔離的。Opus、Sonnet、Haiku 這類模型的結構和權重不同，同一段文字算出來的 KV cache 也不同。你在 Opus 裡跑了很長上下文，再切到 Sonnet，並不能讓 Sonnet 複用 Opus 的快取。
這會帶來一個反直覺結果：中途為了省錢切模型，可能反而讓前面已經累積的快取全部失效。原本可以按 cache read 價格讀取的上下文，需要重新寫入和計算。
更穩妥的做法是：
- 主對話盡量固定一個模型。
- 需要便宜模型處理支線任務時，用 subagent 隔離出去。
- 讓支線代理完成搜尋、探索、整理，再把結果摘要交回主對話。
這樣主對話的長上下文盡量不動，快取命中率更穩定。
快取殺手二：中途新增 MCP 或重載外掛
MCP 會向 Claude Code 提供工具。新增 MCP 伺服器後，工具列表會變化，而工具定義處在上下文鏈條最左側。
從 Prompt Cache 的角度看，工具列表一變，後面的 system 和 messages 都可能需要重新計算。尤其是 MCP 很多時，工具定義本身就可能占用大量 Token，快取失效的代價會很明顯。
不過有一個細節：Claude Code 通常在會話啟動時讀取 MCP 配置。你中途改了配置，當前 session 不一定立刻受影響。真正需要小心的是觸發重新載入的動作，例如重啟、恢復會話、重新載入外掛或讓工具列表重新組裝。
建議是：
- 開始長任務前，一次性裝好需要的 MCP。
- 不要做一半才發現缺工具，再安裝並重載。
- 對大型 MCP 工具集，優先考慮按需載入或減少預設啟用數量。
- 不常用的 MCP 不要長期掛在預設配置裡。
如果工具定義穩定，Prompt Cache 才有長期命中的基礎。
快取殺手三：中途修改 CLAUDE.md
CLAUDE.md 是 Claude Code 的專案記憶文件，適合放構建命令、測試命令、架構約定、程式碼風格和專案注意事項。
它對 Claude Code 很有用，但也會進入上下文。官方說明指出，CLAUDE.md 會在 session 開始時讀取，並作為使用者訊息提供給 Claude；它也會使用 Anthropic 的 Prompt Cache。首次請求會按完整輸入計費，後續請求如果在快取有效期內命中，就按更低的 cache read 成本處理。
問題在於：CLAUDE.md 是內容定址的。你一改文件內容，舊快取就對不上了。
所以不要在長任務中途頻繁改 CLAUDE.md。更好的方式是：
- 任務開始前先檢查
CLAUDE.md是否夠用。 - 把穩定規則寫進去，把臨時指令放在目前對話裡。
- 如果只是一次性任務，不要為了臨時需求修改長期記憶文件。
- 如果必須改，最好在一個階段結束後再開始新 session。
CLAUDE.md 應該是穩定的專案說明，而不是每輪任務都改的便條。
快取殺手四：中途安裝或更新 Skills
Skills 也是上下文的一部分。安裝新 Skill、更新 Skill，或者讓 Skill 列表發生變化，都會讓注入到會話裡的上下文不同。
這類變化通常不會在目前 session 裡立刻完整生效，而是在重新載入、恢復會話或新開會話時體現出來。問題是，一旦重新組裝 messages，舊快取就可能命中不了。
建議和 MCP 類似：
- 開始任務前先確認需要哪些 Skills。
- 同一類任務盡量固定 Skill 集合。
- 不要在一個長任務中途邊做邊裝 Skill。
- 如果安裝了新 Skill，最好把它當成新階段的開始。
對經常做內容生產、程式碼審查、部署、翻譯的工作流，可以把常用 Skills 固定下來，讓上下文結構盡量穩定。
快取殺手五：空閒時間超過 TTL
Prompt Cache 不是永久保存。常見預設有效期是幾分鐘級別，Anthropic 文件和 Claude Code 相關說明裡都提到過 5 分鐘左右的快取窗口。超過 TTL 後，即使你發送完全一樣的請求，服務端也可能已經清掉快取。
這也是很多長任務使用者的體感來源：剛才還很省，去喝杯咖啡回來，再發下一步，Token 又突然漲上去了。
長任務尤其容易遇到這個問題。你可能要看 Claude Code 的輸出、檢查文件、跑測試、思考下一步，這些操作一不小心就超過 5 分鐘。
如果你的使用環境支援，可以在長任務前啟用 1 小時 Prompt Cache TTL：
|
|
在 Windows PowerShell 裡可以寫成：
|
|
需要注意的是，1 小時快取寫入成本通常會高於 5 分鐘快取寫入成本。它不適合所有短任務，但對大型程式碼庫、長對話、複雜多步驟開發任務，往往比頻繁快取過期更划算。
怎麼安排一次更省 Token 的 Claude Code 長任務
比較穩的流程可以這樣做：
- 任務開始前選定模型，不要中途頻繁切換。
- 提前啟用需要的 MCP，不用的 MCP 先關掉。
- 檢查
CLAUDE.md，只保留穩定、關鍵、長期有效的規則。 - 提前準備好本次任務需要的 Skills。
- 如果是複雜任務，考慮啟用 1 小時 TTL。
- 把大任務拆成幾個階段，但每個階段內部盡量保持上下文結構穩定。
- 需要探索支線問題時，用 subagent 或單獨 session，不要污染主對話。
這套做法的目標不是絕對不讓快取失效，而是避免那些代價最高、最容易被忽略的失效。
一個簡單判斷標準
你可以用一句話判斷某個操作是否危險：
這個操作會不會改變模型、工具定義、系統上下文或會話開頭的固定訊息？
如果答案是會，那它大概率會影響 Prompt Cache。越靠近上下文鏈條左側，影響越大。
常見操作可以這樣理解：
- 切模型：高風險，模型快取隔離。
- 新增 MCP 或重載外掛：高風險，工具列表變化。
- 修改
CLAUDE.md：中高風險，專案記憶變化。 - 安裝 Skills：中高風險，注入上下文變化。
- 普通對話繼續追問：低風險，主要追加 messages。
- 空閒超過 TTL：高風險，服務端快取過期。
小結
Claude Code 的 Prompt Cache 優化，關鍵不是背參數，而是讓會話前綴穩定。
模型不要隨便切，MCP 和 Skills 不要邊做邊裝，CLAUDE.md 不要當臨時草稿頻繁改，複雜任務盡量延長 TTL。只要這些基礎動作穩定下來，Claude Code 在長任務裡的 Token 成本和回應速度都會更可控。
最實用的一句話是：開始前配好，開始後少動。
小結
Headroom 是一個很典型的「上下文工程」工具。它不追求再造一個 Agent，而是站在 Agent 和 LLM 中間，把進入模型的內容壓乾淨、壓短，並保留取回原文的能力。
它適合已經在使用 Claude Code、Codex、Cursor、Aider、Copilot CLI 或 MCP 工具的人。如果你的痛點是“模型上下文經常被日誌和工具輸出撐爆”，Headroom 值得試；如果你的問題只是模型能力不夠，單純壓縮上下文就不一定能解決。
常見問題
這個專案是什麼？
它是本文介紹的一個 AI 工具專案，重點在於它能做什麼、怎麼使用，以及什麼情況下值得嘗試。
適合誰使用？
主要適合希望把專案接入真實工作流，而不是只閱讀 README 的開發者和 AI 工具使用者。
使用前應該檢查什麼？
先確認安裝方式、支援工具、資料與權限邊界，以及專案是否仍在快速變化。
適合直接用在生產環境嗎？
建議先小範圍測試。確認行為穩定後，再考慮用於敏感或生產任務。