Headroom完全ガイド：AIエージェントのトークン消費を60〜95%削減するコンテキスト圧縮ミドルウェア
なぜ今、コンテキスト圧縮が必要なのか
Claude Code を週末放置したら $400 の API 請求書が届いた。RAG パイプラインが月 $2,000 を消費していたが、そのうち 80% は「構造的なノイズ」——JSON の冗長なキー、テストログの合格行、git diff の未変更部分——だった。
LLM のコンテキストウィンドウが 100 万トークンに拡大した 2025〜2026 年、開発者が直面する最大の課題は コンテキスト膨張（Context Inflation） です。マルチターン会話では毎回全履歴が再送信され、コストは O(n²) で増大します。
Headroom は、この問題を解決するオープンソースのコンテキスト圧縮ミドルウェアです。ツール出力、ログ、RAGチャンク、ファイル、会話履歴——AIエージェントが読むすべてを、LLM に届く前にローカルで圧縮します。
実証デモでは 10,144 → 1,260 トークン（同じ FATAL エラーを検出）。
Headroom の全体像
| 項目 | 内容 |
|---|---|
| リポジトリ | headroomlabs-ai/headroom |
| インストール |
pip install "headroom-ai[all]" / npm install headroom-ai
|
| 対応言語 | Python, TypeScript, プロキシ経由で全言語 |
| 圧縮率 | 60〜95%（コンテンツタイプにより変動） |
| ライセンス | オープンソース |
4つのデプロイモード
1. プロキシ — headroom proxy --port 8787（コード変更不要）
2. エージェントラップ — headroom wrap claude（1コマンドで完了）
3. ライブラリ — compress(messages)（Python/TypeScriptにインライン）
4. MCPサーバー — headroom mcp install（MCP対応クライアント全般）
6つの圧縮エンジン詳解
Headroom は単一の圧縮アルゴリズムではなく、6つの専門エンジンをコンテンツタイプに応じて自動ルーティングします。
1. SmartCrusher — JSON 圧縮
エージェントが最も頻繁に扱う JSON（APIレスポンス、ツール出力の辞書配列）を対象に、冗長キーの除去・空白の正規化・繰り返し構造の折りたたみを行います。
2. CodeCompressor — AST ベースのコード圧縮
Python、JavaScript、Go、Rust、Java、C++ のコードを抽象構文木（AST）レベルで解析。コメントの除去、クエリと無関係な関数本体の折りたたみ、インターフェースと型シグネチャの保持を実行します。
3. Kompress-base — MLモデルによる圧縮
エージェントのトレースデータで学習した HuggingFace モデル。汎用テキスト要約と異なり、ツールコールパターン・エラースタックトレース・エージェント推論チェインの構造を理解しています。
4. 画像圧縮
学習済み ML ルーターにより、ビジョン対応モデルに渡される画像を 40〜90% 削減。LLM の推論に必要な情報は劣化させません。
5. CacheAligner — キャッシュ対応プレフィックス安定化
最も見落とされがちな機能。プロンプトを圧縮するとテキストが変わるため、Anthropic/OpenAI の KV キャッシュ（プロンプトキャッシュ）がヒットしなくなります。CacheAligner は圧縮後もプレフィックスを安定させ、圧縮による節約 + キャッシュヒット割引の二重節約を実現します。
6. IntelligentContext — スコアベースのコンテキスト最適化
会話がコンテキストウィンドウを超えた場合、学習済みの重要度スコアで各メッセージを評価し、利用可能なトークン予算内に最高価値のコンテンツを収めます。
CCR（可逆圧縮）
従来のプロンプト圧縮は不可逆でした。Headroom の CCR（Compressed Context Recovery） はオリジナルをローカルストアに保持。LLM がより詳細な情報を必要とした場合、headroom_retrieve ツールを呼び出してオンデマンドで特定セクションを復元できます。
統合ガイド（コード例付き）
方法1：ゼロコード・プロキシ（最も簡単）
pip install "headroom-ai[all]"
headroom proxy --port 8787
# AI ツールの API Base URL を http://localhost:8787/v1 に設定するだけ
方法2：1コマンド・エージェントラップ
headroom wrap claude # Claude Code をラップ
headroom wrap cursor # Cursor をラップ
headroom wrap aider # Aider をラップ
方法3：SDK統合（Python）
from headroom import withHeadroom
from anthropic import Anthropic
# SDK をラップするだけで全呼び出しが自動圧縮
client = withHeadroom(Anthropic())
response = client.messages.create(
model="claude-sonnet-4-20250514",
messages=[{"role": "user", "content": "コードをレビューして"}]
)
方法4：MCPサーバー
headroom mcp install
# headroom_compress, headroom_retrieve, headroom_stats の3ツールが利用可能に
フレームワーク別統合一覧
| フレームワーク | 統合方法 |
|---|---|
| Anthropic / OpenAI SDK | withHeadroom(client) |
| LangChain | HeadroomChatModel(your_llm) |
| Vercel AI SDK | wrapLanguageModel({ middleware: headroomMiddleware() }) |
| LiteLLM | litellm.callbacks = [HeadroomCallback()] |
| Agno | HeadroomAgnoModel(your_model) |
競合ツールとの比較
| 機能 | Headroom | RTK | lean-ctx | 手動トリミング |
|---|---|---|---|---|
| 対象範囲 | 全コンテキスト | CLI出力のみ | CLI+MCPルール | 会話のみ |
| デプロイ | プロキシ/ライブラリ/MCP | CLIラッパー | CLIラッパー | コード変更 |
| ローカル実行 | ✅ | ✅ | ✅ | N/A |
| 可逆圧縮 | ✅（CCR） | ❌ | ❌ | ❌ |
| ML圧縮 | ✅（Kompress） | ❌ | ❌ | ❌ |
| キャッシュ対応 | ✅（CacheAligner） | ❌ | ❌ | ❌ |
導入すべきケース・見送るべきケース
こんな場合は導入推奨
- AI コーディングエージェント（Claude Code, Cursor, Aider）を日常的に使用
- RAG パイプラインで大量のチャンクを検索・送信している
- 複数エージェント間で共有メモリが必要
- 圧縮しても元データを復元できる安全性が欲しい
こんな場合はスキップ
- 短いプロンプトの単一ターン完了のみ
- ローカルプロセスが実行できないサンドボックス環境
- 月額 API 支出が $20 未満
まとめ
コンテキスト圧縮は、HTTP における gzip のように、2026 年の AI エージェントスタックにおける標準レイヤーになりつつあります。Headroom はその最も包括的なオープンソース実装です。月額 $50 以上の LLM API を使用しているなら、導入の ROI は即座に現れるでしょう。
Headroom を含む 710 以上の AI エージェントツール・MCP サーバー・インフラストラクチャを AgDex.ai でチェックしてみてください。