headroomlabs-ai/headroom

解決する課題

AI エージェントは、ツール出力、ログ、RAG チャンク、ファイル、会話履歴など、多くのコンテキストを読み取ります。そして、すべてのトークンはコストとレイテンシを発生させます。ツール出力が多い長時間のエージェントセッションでは、モデルが実際に必要とするよりもはるかに多くのトークンを送信し、それでも完全なプロンプトに対して支払うことになります。Headroom は、コンテキストが LLM に到達する前にそれを縮小し、重要な部分（エラー行など）を保持しながら、トークン使用量を大幅に削減します。圧縮はローカルで実行されるため、プロンプトやファイルの内容がマシンの外部に送信されることはありません。

仕組み

Headroom は、エージェント/アプリと LLM プロバイダーの間に位置します。各コンテンツチャンクを検査し、そのタイプ（JSON、ソースコード、散文、画像）を検出して、最適な圧縮器を適用します：

• ContentRouter が圧縮器を選択します。
• SmartCrusher は JSON 配列とネストされたオブジェクトを処理し、フィールドの分散に基づいて外れ値、エラー項目、境界を保持します。
• CodeCompressor は多くのプログラミング言語に対して AST を認識します。
• Kompress-v2-base は、散文用にエージェントトレースでトレーニングされた HuggingFace モデルです。
• CacheAligner は、プロバイダーの KV キャッシュプレフィックスを壊す可能性のある揮発性コンテンツをフラグ付けし、プロンプトを書き換えることなく対応します。
• CCR（Cache-and-Compress-Reversible）は元のコンテンツをローカルに保存し、モデルが headroom_retrieve を介してオンデマンドで全文を取得できるようにします。

圧縮後、より小さなプロンプトと取得ツールが LLM に送信されます。Headroom は、ライブラリ（Python/TypeScript の compress()）、ポート上のプロキシ（コード変更ゼロ）、エージェントラッパー（headroom wrap で 20 以上のエージェント）、または MCP サーバーとして統合できます。また、過去のセッションを読み取って冗長性を調整する headroom learn や、システムプロンプトに簡潔さのメモを追加してモデルが書き戻す内容を減らす出力トークン削減もあります。

対象ユーザー

毎日コーディングエージェントを実行し、コードを変更せずにトークンコストを削減したい開発者とチーム。複数のエージェント（Claude Code、Codex、Cursor など）を使用し、共有メモリストアを1つ持ちたい場合や、TTL の間元のコンテンツを取得可能に保つための可逆圧縮が必要な場合に適しています。短い会話のやり取り、散文中心のタスク、またはローカルプロセスを実行できない環境では、あまり役に立ちません。

ハイライト

• ローカル圧縮：圧縮のためにデータが外部に送信されることはありません。
• 複数の統合モード：ライブラリ、プロキシ、エージェントラッパー、MCP、クロスエージェントメモリ。
• 実証済みの削減：実際のシナリオで 30～57%（例：インシデントデバッグケースで 55,957 → 24,340 トークン）、繰り返しの JSON/ログではさらに高い削減。
• サブミリ秒のレイテンシ（10K トークン JSON で p50 0.21 ミリ秒、100K で 1.4 ミリ秒）なので、エージェントの応答性に影響しません。
• 精度の維持：ベンチマークで有意な劣化なし（例：GSM8K、TruthfulQA、SQuAD v2、BFCL）。
• CCR による可逆圧縮：モデルは必要なときに完全なコンテキストを取得できます。
• 出力トークン削減：モデルが書いたテキストをトリミングし、測定可能または推定の削減を報告します。