headroomlabs-ai/headroom

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

解決する課題

Headroomは、LLMに送信および受信されるトークン数を削減するために設計されたコンテキスト圧縮レイヤーです。ツール出力、ログ、RAGチャンク、ファイル、会話履歴を圧縮することで、AIエージェントの高コスト化とトークン制限の問題に対処します。精度を損なうことなく、JSONでは60-95%、コーディングエージェントでは15-20%のトークン削減を実現することがよくあります。

仕組み

Headroomは、AIエージェントとLLMプロバイダーの間に位置する、ローカルファーストのプロキシ、ライブラリ、またはMCPサーバーとして動作します。ContentRouterを使用してコンテンツタイプを検出し、特定のコンプレッサーを適用します：

  • SmartCrusher: JSONデータ用。
  • CodeCompressor: 複数のプログラミング言語に対応したAST認識圧縮。
  • Kompress-v2-base: 文章/テキスト用の特化型HuggingFaceモデル。
  • CacheAligner: プロバイダーのKVキャッシュヒットを最大化するために、プレフィックスが安定するようにします。
  • CCR (Reversible Compression): オリジナルコンテンツをローカルにキャッシュし、必要に応じてLLMがツールコールを通じて完全なバージョンを取得できるようにします。

また、モデルを簡潔な回答へと誘導し、定型的なステップの推論負荷を調整することで、出力トークンも削減します。

対象ユーザー

  • コストとレイテンシを下げたいAIコーディングエージェント（Claude Code, Cursor, Aiderなど）の利用者。
  • 異なるLLM間で共有・重複排除されたメモリを必要とするマルチエージェントワークフローを構築するチーム。
  • PythonまたはTypeScript SDKを介してLLMアプリケーションを統合する開発者。

ハイライト

  • 複数のデプロイモード: ドロップインプロキシ、インラインライブラリ、またはMCPサーバーとして利用可能。
  • エージェントのラッピング: 幅広いエージェント（例：Claude Code, Copilot CLI, Grok）をワンコマンドでラッピング可能。
  • 出力削減: モデルのプリアンブルをトリミングし、推論負荷を調整して、高価な出力トークンを節約。
  • クロスエージェントメモリ: Gemini, Grok, Claudeなどの異なるプロバイダー間で動作する共有コンテキストストア。
  • 失敗のマイニング: headroom learn コマンドが失敗したセッションを分析し、エージェントの設定ファイルに修正を書き込みます。