Headroom：あなたのAIエージェントが切実に必要としているコンテキスト圧縮層

トークン問題は本物であり——悪化し続けている

本番環境でAIエージェントを構築、あるいは運用したことがある人なら、あの感覚を知っているだろう。エージェントが検索ツールを呼び出し、500件の結果が返ってくる。ログファイルを読み込み、10,000行が返ってくる。データベースに問い合わせると、小説一冊分もあるJSONのかたまりが返ってくる。そのすべてがLLMのコンテキストウィンドウに詰め込まれる——そしてあなたは、トークン数が爆発し、レイテンシが膨れ上がり、APIの請求額がひそかに制御不能になっていくのを目にする。

これはニッチな例外的ケースではない。2025～2026年におけるエージェント型AIのデフォルトの現実だ。ツールの出力は冗長だ。ログはノイズが多い。RAGの検索は不正確だ。そしてLLMは、その優秀さにもかかわらず、無関係な情報を無視するのが驚くほど苦手だ——与えられたものはすべて読んでしまう。重要かどうかに関わらず。

GitHub上のchopratejas/headroomにある、Tejas Chopraによるオープンソースプロジェクト、Headroomは、まさにこれを修正するために構築された。そしてその方法は、技術的に洗練されていながら、驚くほど実用的だ。

---

Headroomとは何か？

Headroomは自らを「AIエージェントのためのコンテキスト圧縮層」と称している。平易に言えば：アプリケーションとLLMプロバイダーの間に位置し、モデルのコンテキストウィンドウに流れ込むすべてのコンテンツを傍受し、それをインテリジェントに圧縮し、より軽量でクリーンなプロンプトを転送する。LLMは同じ意味を得る——ただ、はるかに少ないトークンで。

見出しとなる数字は印象的だ：

そして重要なのは——精度が保たれることだ。GSM8Kのような標準ベンチマークにおいて、Headroomで圧縮されたプロンプトは、非圧縮のものと同じ正しい答えを生成する。

---

実際の仕組み

ここがHeadroomの本当に興味深い部分だ。単に「空白を削り、重複を除去する」だけではない。圧縮パイプラインは多段階で、コンテンツを認識するものだ。

ステージ1：CacheAligner

圧縮が行われる前に、まずHeadroomはシステムプロンプトを安定化させる。タイムスタンプ、セッショントークン、UUIDといった動的なコンテンツを検知し、それらをプロンプトの中間に埋め込むのではなく末尾に移動させる。なぜか？AnthropicやOpenAIのようなLLMプロバイダーはプレフィックスキャッシュを使用している——呼び出しごとにプロンプトの先頭が同一であれば、プロバイダーはキャッシュされたKV計算を再利用でき、料金を大幅に下げられる。システムプロンプトの中に埋め込まれた1つの回転するタイムスタンプが、呼び出しごとにあなたのキャッシュヒット率をひそかに壊していたのだ。CacheAlignerはミリ秒未満のオーバーヘッドでこれを修正する。

ステージ2：SmartCrusher

これが主力だ。エージェントが1,000件のログエントリを含むJSON配列を返すとき、SmartCrusherは単にランダムに20件を抽出するわけではない。すべてのフィールドにわたって分散、一意性、変化点を測定するフィールドレベルの統計分析を実行する。バイグラムの網羅率にKneedleアルゴリズムを使用して、代表的な部分集合を選択する。そして重要なことに、エラー、異常値、分布の境界——LLMが問題を診断するために必要な項目そのもの——を無条件に保持する。

項目の保持戦略は思慮深い：配列の先頭から30%（スキーマ理解のため）、末尾から15%（最新性のため）、計算された重要度スコアによって55%。エラー項目は予算に関わらず常に生き残る。

コードに対してはAST認識型の圧縮を使用し——関数のシグネチャを保持し、本体を折りたたむ。HTMLに対しては記事抽出を使用する。ログに対してはパターンクラスタリングを使用する。各コンテンツ種別に適切なツールが割り当てられる。

ステージ3：コンテキストマネージャー

コンテキストウィンドウを超えるリスクのある長い複数ターンの対話に対して、Headroomは2つのモードを提供する。デフォルトのRolling Windowは最も古いメッセージを最初に削除する（システムプロンプトと最近のターンは維持する）。高度なIntelligent Contextモードは、最新性、セマンティック類似度、エラー指標、前方参照、トークン密度、そしてTOINと呼ばれる学習型の重要度信号という6つの次元にわたって各メッセージを評価し、最も低いスコアのメッセージから削除していく。

---

決定的な機能：CCR（Compress-Cache-Retrieve）

Headroomの中で哲学的に最も興味深い部分は、明白な反論への答えだ：「LLMが圧縮で消えたデータを必要としたらどうするのか？」

その答えがCCR——Compress-Cache-Retrieve（圧縮・キャッシュ・取得）だ。Headroomが何かを圧縮するたびに、元のデータをローカルのSQLiteベースのキャッシュに保存し、圧縮された出力に取得マーカーを注入する：

[1000 items compressed to 20. Retrieve more: hash=abc123]

また、LLMの利用可能なツールにheadroom_retrieveツールを注入する。モデルが完全なデータが必要だと判断した場合、そのハッシュでこのツールを呼び出すだけでよく——約1ミリ秒で元のデータを取り戻せる。クライアントアプリケーションはこれが起こっていることに全く気づかない；すべて透過的に処理される。

さらに賢いのは：LLMはすべてを取得する必要がない。オプションのクエリパラメータを渡すことができ、Headroomはキャッシュされた項目に対してBM25検索を実行し、関連する部分集合だけを返す。圧縮は単に積極的であるだけでなく、真に可逆的で照会可能なものになる。

これは、古典的な圧縮のトレードオフを優雅に解消する。「トークンを節約する」ことと「情報を保持する」ことのどちらかを選ぶ必要はない。両方を実現できる。

---

つの使用方法

Headroomは、あなたがいる場所に合わせて設計されている：

• ライブラリモード — PythonまたはTypeScriptでインラインにcompress(messages)を呼び出す。わずか2行のコード。
• プロキシモード — headroom proxy --port 8787。コード変更ゼロ。既存のLLMクライアントを別のベースURLに向けるだけ。
• エージェントラップ — headroom wrap claudeやheadroom wrap cursor。1つのコマンドでコーディングエージェント全体をラップする。
• MCPサーバー — headroom_compress、headroom_retrieve、headroom_statsをMCP互換の任意のクライアント向けのMCPツールとして公開する。

また、LangChain、Agno、Strands、LiteLLM、Vercel AI SDKにもネイティブに統合されている。

---

なぜこれが重要なのか

Headroomの意義は、単にAPI費用を節約すること（73～92%のトークン削減で、その節約は非常に実質的だが）にとどまらない。このプロジェクトが重要である理由は、3つのより深いものがある：

エージェントをより信頼できるものにする

ノイズが多く肥大化したコンテキストは、LLMの推論エラーの主な原因の一つだ。65,000トークンのログをモデルに与え、そのうち500トークンだけが重要な場合、それは干し草の山から針を見つけろと頼んでいるようなものだ。Headroomはその針を直接手渡す。

実効的なコンテキストの上限を引き上げる

128Kのコンテキストウィンドウは、エージェントが実際の作業を始めるまでは膨大に思える。90%の圧縮を実現すれば、同じウィンドウは実質的に128万トークンのウィンドウとして機能する。エージェントはより長いタスク、より深いコードベース、より豊富な履歴を扱えるようになる。

ローカルファーストで、プライバシーを尊重する

すべての圧縮とキャッシュはあなたのマシン上で行われる。あなたのデータは、LLMに向かう途中でインフラの外に出ることはない——圧縮された出力だけが送られる。データの機密性が重要な企業向けの使用ケースにおいて、これは大きな意味を持つ。

---

最後に

Headroomは、あまりにも根本的な問題を解決していて、なぜこれほど長くこの世に存在しなかったのかと不思議に思うようなプロジェクトの一つだ。コンテキストウィンドウは無料ではない——1トークンごとに時間、金銭、そして注意力のコストがかかる。Headroomは、それを統計的手法、AST解析、学習されたパターン、可逆キャッシュを使って厳密に解決すべきエンジニアリング上の問題として扱っている——単なる正規表現の経験則ではない。

GitHubで23,400以上のスターを獲得し、さらに増え続けているのを見れば、コミュニティが明らかにこれに注目していることがわかる。2026年にAIエージェントを使った何かを構築しているなら、Headroomは真剣に検討する価値がある。