この記事ではLLM入力圧縮ツール headroom に特化して解説します。トークン最適化の全体像（RTK・Graphify・メモリ階層化など）は AIエージェントのトークン最適化｜コスト削減とコンテキスト管理の5アプローチ2026 をご覧ください。

この記事のポイント
  • headroomはツール出力・ログ・RAGチャンク・会話履歴をLLMに渡す前に60〜95%圧縮するミドルウェア（Apache 2.0、Python 76.8%＋Rust 18.4%）
  • トークンコスト削減・レイテンシ短縮・RAG精度維持を同時に狙う。ライブラリ／プロキシ／MCPサーバの3形態で既存スタックに後付けできる
  • LLMLingua系の汎用枝刈りと違い、コンテンツ種別ごとの専用圧縮器＋可逆圧縮（CCR）で構造化データに強い。約9,556★・直近で急増中

30秒で理解するheadroom

headroomは、AIエージェントが読むものすべて——ツール出力・ログ・ファイル・RAGチャンク・会話履歴——を、LLMに届く前に圧縮するミドルウェアだ。要点を先に押さえる。

・headroomはLLM入力を「60〜95% fewer tokens, same answers」を掲げて圧縮するOSS（Apache 2.0、作者 chopratejas）
・狙いはトークンコスト削減・レイテンシ短縮・RAG精度維持の三立。入力を削るだけでなく原文をローカル保持して取り戻せる
・ライブラリ（compress()）／HTTPプロキシ（コード変更ゼロ）／MCPサーバの3形態で導入できる
・JSON・コード・ログ・検索結果・散文を種別判定して別々の圧縮器に振り分けるのが設計の核
・GitHubは約9,556★・1,405コミット、構成はPython 76.8%／Rust 18.4%／TypeScript 2.7%

商用API依存のコストとレイテンシに悩むエージェント／RAG運用者に直撃する内容だ。本記事は圧縮の仕組み・精度のトレードオフ・競合との違い・実運用での置き場所を、公式READMEとドキュメントのベンダー記載値を一次ソースとして整理する。

なぜ今「LLM入力圧縮」なのか

LLM入力圧縮が2026年に注目を集める理由は3つに集約できる。

・トークンコストの爆発：エージェントは1タスクで何十回もLLMを呼び、その都度ツール出力・ログ・ファイルを丸ごと文脈に積む。入力トークンは出力より桁違いに多くなりやすく、月額API料金の主因になる
・長文脈モデルでも残る実用レイテンシ：1Mトークン級の文脈窓があっても、毎リクエストで巨大な入力を処理すれば応答は遅くなり、KVキャッシュも崩れる。窓が広いことと安く速いことは別問題だ
・エージェント時代の入力肥大：MCPツール出力やログは「干し草の山の中の針（needle in haystack）」を生み、無関係トークンが推論精度まで下げる

この文脈で、入力を減らすこと自体がコスト・速度・精度の三方向に効く。トークンを盗まれて課金を破壊される攻撃面まで含めて「入力をどう扱うか」が運用設計の中心になりつつあり、防御の観点は トークン窃取を多層で止める——セッション・AI推論・課金まで含めた防御パターン で整理した。コンテキスト供給の枠組みとしては、Microsoftが Microsoft IQの4層を読み解く——Work/Web/Foundry/FabricとMCP・RAGの関係 で示した「単発RAGを多段・権限対応に進化させる」流れとも地続きだ。headroomはその供給パイプの「入口で削る」側を担う。

入力圧縮は「文脈窓を広げる」アプローチの逆方向だ。窓を広げてコストを払うのではなく、渡す情報を絞ってコストとノイズを同時に下げる。長文脈と圧縮は競合ではなく併用できる。

headroomの仕組み

headroomの中核は、コンテンツ種別を判定して最適な圧縮器に振り分ける ContentRouter と、その前後に置かれる CacheAligner・IntelligentContext・CCR だ。公式ドキュメントは3段のパイプラインとして説明している。

flowchart TD A["入力
ツール出力 / ログ / RAGチャンク
コード / 会話履歴"] --> B["CacheAligner
プレフィクス安定化
プロバイダKVキャッシュをヒットさせる"] B --> C["ContentRouter
コンテンツ種別を自動判定"] C --> D1["SmartCrusher
JSON / 配列 / ネスト"] C --> D2["CodeCompressor
AST認識 tree-sitter"] C --> D3["Kompress
散文 ModernBERTトークン分類"] C --> D4["LogCompressor
失敗・エラーを残し成功行を捨てる"] C --> D5["SearchCompressor
クエリ関連度でランキング"] D1 --> E["IntelligentContext
文脈上限超過時に重要度スコアリング"] D2 --> E D3 --> E D4 --> E D5 --> E E --> F["CCR
原文をローカル保持
headroom_retrieve で取り戻し可能"] F --> G["LLMへ送信
圧縮済み入力"]

各コンポーネントの役割を分解する。

・CacheAligner：メッセージのプレフィクスを安定化させ、プロバイダ側のKVキャッシュが実際にヒットするようにする。圧縮で文頭が毎回変わるとキャッシュが無効化されるため、その逆を担保する層
・ContentRouter：入力のコンテンツ種別を検出し、最適な圧縮器へ振り分ける司令塔
・SmartCrusher：JSON（配列・ネスト・混在型）を統計的に解析し、エラーや異常値を保持したまま冗長部を畳む
・CodeCompressor：Python・JavaScript・Go・Rust・Java・C++をtree-sitterでAST認識し、構文構造を壊さずに圧縮
・Kompress：散文をHuggingFace学習済みのModernBERT系トークン分類で圧縮（エージェント実行トレースで学習と記載）
・LogCompressor：ビルド/テストログから失敗・エラーを残し、成功(passing)出力を落とす
・SearchCompressor：検索結果をユーザクエリへの関連度でランキングして絞る
・IntelligentContext：文脈上限を超える場合にメッセージを重要度でスコアリングして取捨選択
・CCR（Compress-Cache-Retrieve）：圧縮した原文をローカルに保存し、LLMには headroom_retrieve ツールを渡す。詳細が必要になればLLM自身がハッシュ指定で原文を取り戻せる「可逆圧縮」

この種別別ルーティングと可逆性が、単一アルゴリズムでプロンプト全体を枝刈りする方式との設計上の分岐点になる。圧縮し過ぎても原文に戻せるため、攻めた圧縮率を許容しやすい。

なぜ「種別ごとに別の圧縮器」なのかは、データ構造の違いを考えると腑に落ちる。JSONは木構造で、冗長なのはキーの繰り返しや配列要素の定型部分だから統計的に畳める。コードは構文木があるので、AST単位で意味を保ったまま空白やボイラープレートを落とせる。ログは時系列で大半が正常行、見たいのは例外だけだから「失敗を残す」フィルタが効く。これらを単一の自然言語圧縮器にかけると、構造を壊すか、構造を守って圧縮率が出ないかのどちらかになる。headroomが種別判定を最上流（ContentRouter）に置くのは、圧縮アルゴリズムの選択そのものが圧縮率と安全性を決めるからだ。

圧縮率と精度のトレードオフ

headroomが掲げる「60〜95%削減・same answers」は、実ワークロード別のベンダー記載値で裏付けられている。以下はすべて公式README／ドキュメント記載の数値で、独自実測ではない点に注意してほしい。

・コード検索（100件）：17,765 → 1,408トークン（92%削減）
・SREインシデント調査：65,694 → 5,118トークン（92%削減）
・GitHub issueトリアージ：54,174 → 14,761トークン（73%削減）
・コードベース探索：78,502 → 41,254トークン（47%削減）
・ログ100件（67番目に致命的エラー）：10,144 → 1,260トークン（87.6%削減）、設問4/4を正答維持

精度面では、圧縮を挟んでもベンチスコアが落ちないことを示している。

・GSM8K（数学）：0.870（ベースライン）→ 0.870（headroom適用）
・TruthfulQA（事実性）：0.530 → 0.560
・SQuAD v2（QA）：19%圧縮時に97%の精度を維持
・SQuAD・BFCL・CCR Needle タスクで一貫して97〜100%の精度と記載

重要なのは、圧縮率がデータの性質に強く依存する点だ。Hacker NewsのShow HNで作者は、繰り返しの多いサーバログは90%超、行が一意なコード差分（diff）は0%、密度の高い散文では約-0.3%（わずかなオーバーヘッド）と明言している。

公表ベンチの読み方にも注意がいる。GSM8K・TruthfulQA・SQuAD v2はいずれも英語の標準QA/推論タスクで、「圧縮しても正答が落ちない」ことは示せても、「あなたのドメイン固有の長文で重要な一文が消えない」ことまでは保証しない。特にTruthfulQAが0.530→0.560とわずかに上がっているのは、ノイズ除去で精度が上振れる現象（無関係トークンが減って干し草の山問題が緩和される）を示唆するが、これも英語・特定タスクの傾向だ。自社のゴールデンセットで「圧縮あり／なし」を並べて回帰確認するのが、ベンダー数値を鵜呑みにしない唯一の方法になる。

教訓：headroomは「冗長・反復・構造化されたデータ」ほど効き、「ユニークで情報密度の高い散文」では効かないか逆効果になりうる。万能圧縮ではなく、エージェントのツール出力・ログ・検索結果という"水増しされやすい入力"を狙い撃つツールだと理解するのが正しい。

競合との比較表

入力圧縮には複数の系統がある。LLMLingua系（Microsoft Research）はプロンプト文をトークン重要度で枝刈りする汎用手法、headroomはコンテンツ種別ごとの専用圧縮＋可逆性に振った実装、という違いがある。アプローチ・対応データ・統合性で整理する。

ツール アプローチ 主な対応データ 可逆性 統合形態 ライセンス
headroom コンテンツ種別判定→専用圧縮器 JSON・コード・ログ・検索・散文・画像 あり（CCR） ライブラリ／プロキシ／MCP Apache 2.0
LLMLingua 小型LMの perplexity でトークン枝刈り 主に自然言語プロンプト なし Pythonライブラリ MIT
LLMLingua-2 BERT級エンコーダのトークン分類（GPT-4蒸留） タスク非依存の自然言語 なし Pythonライブラリ MIT
SemanticCompression 意味単位での要約的圧縮 自然言語中心 なし ライブラリ 実装依存
Self-Extend 等の文脈拡張 圧縮せず窓を広げる（逆方向） 任意 該当なし モデル側手法 実装依存

ベンダー記載ベースの傾向として、LLMLinguaは最大20倍（約95%）圧縮を達成する一方で対象は自然言語が主、LLMLingua-2は2〜5倍圧縮だがタスク非依存で3〜6倍高速・GPUメモリも約2.1GBと軽い、という特性がある。headroomの差別化は「JSON/ログ/コードのような構造化・半構造化データへの種別最適化」と「原文をローカルに残してLLMが取り戻せる可逆性」だ。散文の純粋な意味圧縮率だけを比べるならLLMLingua系の方が研究実績は厚い。用途で使い分けるのが現実的で、エージェントのツール出力圧縮ならheadroom、長文プロンプトの一括圧縮ならLLMLingua、という棲み分けになる。

ユースケース別の使い方

RAGパイプラインの中段に置く

検索で取ってきたチャンクは重複や定型句が多く、上位kを丸ごと積むとノイズになる。headroomの SearchCompressor をretrieverとLLMの間に挟み、クエリ関連度でランキング・圧縮してから渡す。RAGの精度を保ちつつ入力を削れるため、kを増やして再現率を上げても文脈予算が破綻しにくい。ツリー型RAGなど検索構造側の工夫とも併用でき、検索の作り込みは PageIndex｜ベクトル不要のツリー推論RAG も参考になる。

エージェントのツール出力圧縮

エージェントの最大の水増し源はツール出力だ。lsの全結果、巨大なJSONレスポンス、MCPツールの戻り値が毎ターン文脈に積まれる。プロキシかMCPサーバ形態で挟めば、SmartCrusher がJSONの冗長部を畳み、エラーや異常値だけ残す。コード変更ゼロで効くため、Claude Code・Codex・Cursor・Aider・Copilot CLI といった既存エージェントにそのまま被せられる。

長文ログの要約前処理

ビルドログ・テストログ・SREのインシデントログは、成功行が大半で本当に見たいのは失敗箇所だけ、という構造をしている。LogCompressor は passing 出力を落として failures/errors を残すため、65,694→5,118トークン（92%）のような圧縮を実現する。要約LLMに渡す前段の前処理として置けば、要約自体のコストと取りこぼしを同時に減らせる。

ファインチューニング学習データの圧縮

エージェント実行トレースを学習データに使う場合、冗長なツール出力やログがそのまま混ざると学習効率もコストも悪化する。種別別に圧縮してから学習セットに通すことで、信号対雑音比を上げられる。headroom learn は失敗セッションを採掘して CLAUDE.md に修正を書き戻す機能も持ち、運用ループの中で文脈を洗練させる発想に寄っている。

統合パターン

導入は3形態（ライブラリ／プロキシ／MCP）から選ぶ。ここではベンダー記載のAPI形に沿って最小サンプルを3つ示す。バージョンによってAPIは変わりうるため、最終形は公式READMEで確認してほしい。

インストールは用途別のextrasを付ける。

# Python（全部入り）
pip install "headroom-ai[all]"
# 必要な分だけ: [proxy] [mcp] [ml] [agno] [langchain] [evals]

# TypeScript / Node
npm install headroom-ai

# Docker（プロキシ/MCPをコンテナで）
docker pull ghcr.io/chopratejas/headroom:latest

最小サンプル1：SDKラッパとして挟む（Anthropic / OpenAI）。クライアントを包むだけで入力圧縮が効く。

from anthropic import Anthropic
from headroom import with_headroom

client = with_headroom(Anthropic())  # 既存クライアントを包む

resp = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": huge_tool_output},  # 60〜95%圧縮されて送信
    ],
)

最小サンプル2：LangChain のチャットモデルラッパ。エージェントのLLM部分を差し替える。

from headroom.langchain import HeadroomChatModel

llm = HeadroomChatModel(your_llm)  # 既存LLMをラップ
# あとは通常のLangChainエージェントとして使う
agent = create_agent(llm=llm, tools=tools)

最小サンプル3：プロキシ形態（コード変更ゼロ）。OpenAI互換クライアントの向き先をheadroomプロキシに変えるだけ。

# プロキシを起動（ローカル）
headroom proxy --port 8787

from openai import OpenAI

# base_url をheadroomプロキシに向けるだけ
client = OpenAI(base_url="http://localhost:8787/v1", api_key="...")
# 以降の全リクエストが自動で圧縮される

この他に Vercel AI SDK（wrapLanguageModel({ middleware: headroomMiddleware() })）、LiteLLM（HeadroomCallback()）、Agno（HeadroomAgnoModel）、ASGIアプリ向けの CompressionMiddleware、AWS Strands Agents + Bedrock 連携などが用意されている。MCPサーバ形態なら、対応エージェントから圧縮とCCR取り戻しをツールとして直接叩ける。

3つの導入形態をどう選ぶか

headroomはライブラリ／プロキシ／MCPサーバの3形態を提供する。同じ圧縮エンジンを別の入口で使う形で、改修コストと制御の細かさがトレードオフになる。選定の指針を表にする。

形態 コード変更 向く対象 制御の細かさ 典型ユース
ライブラリ（compress() / ラッパ） あり（数行） 自社コードからLLMを呼ぶアプリ 高い（種別・閾値を呼び出し側で指定） RAGサーバ・自前エージェント
プロキシ（HTTP） ゼロ OpenAI互換の既存クライアント全般 中（プロキシ設定で一括） Claude Code・Codex等の被せ替え
MCPサーバ ゼロ〜小 MCP対応エージェント 中〜高（ツールとして圧縮・取り戻し） CCRを能動的に使う構成

判断の目安はこうだ。アプリのコードを触れるならライブラリが最も細かく効く。既存のエージェントCLIに後付けしたいだけならプロキシがコード変更ゼロで最短。LLMに headroom_retrieve を能動的に呼ばせてCCRを活かしたいならMCPサーバ形態が素直だ。実運用では「プロキシで全体を一括圧縮しつつ、精度が要る経路だけライブラリで細かく制御する」といった併用も成立する。

迷ったらまずプロキシで全体の圧縮率と精度をA/B計測し、効果の大きい経路だけライブラリ/MCPに置き換える、という段階導入が安全。最初から全経路をライブラリ化すると改修コストばかり先行する。

クロスエージェントメモリと headroom learn

headroomは単発の圧縮にとどまらず、エージェント運用の文脈を継続的に洗練する機能を持つ。これが「入力を削る」以上の価値になる部分だ。

・クロスエージェントメモリ：Claude・Codex・Gemini など複数エージェントをまたいだ共有ストアを持ち、自動で重複排除（auto-dedup）する。同じ事実を各エージェントが別々に文脈へ積む無駄を、ストア側で一元化して削る
・headroom learn：失敗したセッションを採掘し、修正内容を CLAUDE.md に書き戻す。エージェントが同じミスを繰り返さないよう、運用ループの中で指示文脈を更新していく発想
・local-first：これらのストアも含めてデータは利用者のマシン上に置かれる。原文・メモリを外部に出さずに圧縮と学習を完結できる

つまりheadroomは「1リクエストの入力圧縮器」であると同時に、「複数エージェント・複数セッションをまたいだ文脈管理レイヤ」としての顔も持つ。トークン最適化を単発の圧縮で終わらせず、メモリ階層化まで含めて設計したいなら、この継続学習・共有メモリの側面が効いてくる。トークン最適化全体の中での位置づけは AIエージェントのトークン最適化ガイド の分類軸（圧縮／グラフ化／メモリ階層化）に照らすと整理しやすい。

コスト試算

圧縮効果を金額に落とすと効き目が直感的になる。ここでは入力単価を仮に$3.00／百万トークンと置き、エージェントが1日10万リクエスト・平均入力2万トークンを処理する運用を想定する（単価・規模はあくまで試算用の仮定値）。

圧縮率 1リクエスト入力 月間入力トークン 月額入力コスト（$3/1M仮定） 削減額
0%（圧縮なし） 20,000 60,000M $180,000 —
47%（コードベース探索級） 10,600 31,800M $95,400 -$84,600
73%（issueトリアージ級） 5,400 16,200M $48,600 -$131,400
92%（ログ/検索級） 1,600 4,800M $14,400 -$165,600

削減率はモデルや通貨単価に依存しないため、GPT-5.5・Claude・Gemini いずれの料金体系でも「入力トークンを何%削れるか」がそのまま月額削減率になる。出力トークンは圧縮対象外なので、出力比率が高いワークロードほど総額への効きは小さくなる点だけ注意する。実額はベンダー単価と自分のワークロードの圧縮率で再計算してほしい。

試算のコツ：まず自分の代表的な入力（ツール出力・ログ・RAGチャンク）でheadroomの実圧縮率を計測し、その%を現在の月額入力コストに掛ける。散文中心なら数%、構造化データ中心なら70〜90%が現実的なレンジになる。

よくある落とし穴

導入時にハマりやすい点を4つ挙げる。可逆圧縮（CCR）があるとはいえ、設計を誤ると精度や挙動を壊す。

・圧縮率を上げ過ぎて重要情報が落ちる：攻めた圧縮は冗長データには有効だが、ユニークな事実が密な入力では肝心の一行が消えうる。CCRの headroom_retrieve をLLMが呼べる構成にして、必要時に原文へ戻せる経路を必ず残す
・構造化データのスキーマ破壊：SmartCrusherはJSON構造を保つ設計だが、後段で厳密なスキーマ検証をするパイプラインでは、圧縮後の形がバリデーションを通るか確認する。圧縮はLLM入力用と割り切り、機械処理に渡すデータは原文を使う
・ストリーミング応答との相性：圧縮は入力前処理であって出力ストリームの書き換えではない。プロキシ経由でSSEが透過するか、自分のスタックで挙動確認する（examplesの streaming_example.py が参考）
・LLM側キャッシュの無効化：圧縮で文頭が毎回変わるとプロバイダのプロンプトキャッシュが効かなくなる。headroomは CacheAligner でこれを防ぐ設計だが、自前で前後に文字列を足すとキャッシュ境界がずれる。キャッシュ前提の運用ではヒット率を計測する

これらはいずれも「圧縮を入力前処理に限定し、原文を残し、効果を実測する」という原則で回避できる。万能圧縮として無条件に挟むのではなく、効くデータに狙って当てるのが安全だ。

headroomを評価すべきチーム

導入を検討すべきケース
  • エージェント/RAGでツール出力・ログ・検索結果が文脈を水増しし、月額API入力コストが膨らんでいるチーム
  • コード変更を最小化したい（プロキシ/MCPで後付けしたい）運用
  • 圧縮はしたいが原文の取りこぼしリスクを許容できず、可逆性（CCR）が欲しい場合
  • ローカル完結で原文を外部に出さずに圧縮したいオンプレ志向
慎重に評価すべきケース
  • 入力が密度の高いユニークな散文中心で、圧縮が効きにくい（むしろオーバーヘッド）用途
  • 日本語中心で精度要件が厳しく、英語ベンチしか公表がない現状で十分な事前検証ができない場合
  • 出力トークン比率が高く、入力削減の総額インパクトが小さいワークロード

掲載した性能・精度の数値はすべて公式README／ドキュメント／Hacker Newsの作者発言に基づくベンダー記載値で、本記事の独自実測ではない。実運用での効きはデータの性質に強く依存するため、代表入力での圧縮率と精度を小さく計測してから本番投入するのが確実だ。

参照ソース