😎

Hermes AgentにHeadroomを使わせたら平均30%ぐらいトークンを節約できた話

に公開
AI
token
Hermes
llm
headroom
tech

はじめに

最近流行りのパーソナルエージェントの「Hermes Agent」にこれまた最近流行りのトークン節約ツールの「headroom」を組み合わせたところ、そこそこトークン使用量が節約できたので実例を交えて解説します。

  • この記事で伝えたいこと
    • Hermes Agent × headroom の組み合わせで実測どれだけトークン削減できたか
  • 対象の読者
    • AIエージェントを日常的に使っている方、トークン消費量に悩んでいる方

そもそも... Hermes Agentとは

  • Nous Research製のOSSのAIエージェントフレームワーク
  • 以下のようなツールを統合している
    • ファイル操作
    • ターミナル
    • ブラウザ
    • GitHub
    • Notion
  • スキルシステムでワークフローを再利用可能
    • 自立して育つAIエージェント

色々なタスクを任せられる便利なAIエージェントですが、以下のような欠点も存在します。

  • ツールの出力が巨大になりがち（ファイル読み込み、Webスクレイピング、検索結果 etc.）
    • 具体例
      • 1回のread_fileやterminalで数千〜数万トークンがコンテキストに流れ込む
  • 特に長いセッションだと不要なコンテキストが積み重なってコスト増＋性能劣化
    • AIエージェントに限った話ではなく、LLM自体がそう

headroomとは

  • AIエージェントに送るコンテキストを圧縮してトークン消費量を削減するOSS
  • コンテキスト圧縮の仕組み
    • LLMに流す前にツール出力を圧縮、MCPを利用することでLLMが必要としたときに展開できる
      • 詳細が必要なときだけhashキーで元データを取得
    • ツール出力 → headroom Proxy が透過的に圧縮 → 圧縮済みテキストのみがLLMのコンテキストに入る
    • コンテキストは全部保持しているけど、LLMに渡すときだけは要約だけを実現
  • AIエージェントはmemoryやツールの入力など、出力よりも入力に多く、そこにコストがかかっている
  • 対応プロバイダ: OpenRouter / Anthropic / OpenAI など主要どころをカバー

詳細に解説してくれている記事が存在するので、詳しくは他の解説記事や公式ドキュメントを参照してください。

実際に使ってみる

セットアップ

  • 必要なもの
    • Hermes Agent
    • npm/uv
  • 設定手順
    1. uv tool install headroom-aiでheadroomをインストール
    2. Hermes Agentのconfig.yamlでheadroomのMCPを有効化する
      # ~/.hermes/config.yaml
mcp_servers:
  headroom:
    command: /home/<ユーザ名>/.local/bin/headroom
    args: ["mcp", "serve"]
    3. コンテキスト圧縮プロキシを有効化する
      # ~/.hermes/config.yaml
model:
   default: <任意のモデル>
   provider: <任意のプロバイダ (OpenAI互換)>
   base_url: http://127.0.0.1:8787/v1 <- headroomに向ける
   api_mode: chat_completions

実測データ 導入前 vs 導入後

環境

  • モデル: deepseek-v4-pro
  • 導入後期間: 約4日間

使用用途

  • Web情報調査・比較
  • コーディング
  • 雑用（グラフ作成など）

圧縮率

  • headroomにはstatsを取れるAPIがあるのでそこからサマリを取得しました。
指標 数値
圧縮されたAPIリクエスト数 2,574 / 3,249（約79%）
平均圧縮率 33.8%
ベスト圧縮率 75.2%（87,586 → 21,758 tokens）
累計削減トークン数 約8,165万トークン
  • LLM生成のグラフ
    LLM生成のグラフ

体感

  • 長いセッションでもコンテキストが詰まりにくくなった
  • retrieveの手間はほとんど意識しないレベル
    • 自動で圧縮されて、必要な場合はLLMが勝手に解凍してくれる
  • 使用しているプロバイダのトークン制限に引っかかりにくくなった。

注意点・デメリット

  • 圧縮されたデータの鮮度問題（TTLで古くなると取れなくなる）
    • 会話を始めてから時間が経って次の会話を始める際に前の会話を解凍しようとしてもTTLが古くなると解凍ができなくなる
  • 完全な元データが必要な場面ではretrieveの一手間が増える
    • このような場合にLLMが解凍を諦めてしまうパターンがあった -> 知識ベースで答えてしまい精度が低下？
  • 圧縮率は出力の種類に依存する

まとめ

  • Hermes Agentにheadroomを入れたら累計8,165万トークン以上削減できた
  • 実装コストほぼゼロに対してリターンがデカい
    • 長期間ヘビーに使う人ほど恩恵が大きい
  • 精度低下もほとんどないので導入はかなりアリ

参考リンク

Discussion