Hermes Agent を読み解く — 全体像と読み方
連載「Hermes Agent を読み解く」第1回。
連載「Hermes Agent を読み解く」全10回
- [第1回 全体像と読み方]（本記事）
- [第2回 コアの会話ループ]
- [第3回 状態管理とコンパクション]
- [第4回 記憶アーキテクチャと人格]
- [第5回 ツールシステム]
- [第6回 マルチエージェント並列]
- [第7回 Kanban 永続タスクボード]
- [第8回 接続層とインタフェース総覧]
- [第9回 拡張運用]
- [第10回 セキュリティと安全運用]
はじめに — なぜ自分のエージェントの中身を読むのか
私は手元の Mac Studio でローカル LLM を回し、Obsidian の vault と自前のエージェント基盤をつないで日々の生産性を支えている。そうやって「自分のエージェント」を運用していると、ある時点で必ずこう思う——この箱の中で、いったい何が起きているのか。
プロンプトを投げ、ツールが走り、答えが返る。その滑らかな体験の裏には、会話ループ・状態管理・コンパクション・記憶の再注入・並列実行・承認ゲートといった、地味だが本質的な機構が積み重なっている。エージェントを「使う」段階から「設計を理解して運用する」段階へ進むには、誰かが書いた実装を一度きちんと読み解くのが近道だ。
題材に選んだのは Nous Research の Hermes Agent。ツール呼び出し型・マルチサーフェスの汎用 AI エージェントで、OpenAI SDK 互換を軸に据えつつ、28 のモデルプロバイダ、tools/ 直下 82 ファイル（うちレジストリ登録ツールは 71）、プラグイン／スキルの拡張機構を持つ。MIT ライセンスでソースが読める。「実用に足る規模を持ちながら、一人で全体を追える」境界線上の好例だ。
この連載は全 10 回。ソースを章ごとに読み、設計判断の意図を言葉にしていく。
一貫して掲げるテーゼは 人格 = 知能 × 記憶 ——詳しくは第4回（山場）で扱う。
1. Hermes Agent とは
- ツール呼び出し型・マルチサーフェスの汎用 AI エージェント（Nous Research / MIT ライセンス）
- OpenAI SDK 互換を軸に 28 モデルプロバイダ（
plugins/model-providers/直下のディレクトリ実測） -
tools/直下 82 ファイルだが、レジストリに実登録されるツールは 71（残りは承認・URL 安全チェックなどの非ツールモジュール） - プラグイン／スキル／フック／プロファイルによる拡張機構
「82 ツール」と書くと不正確になる点に注意してほしい。82 は tools/ 直下の .py ファイル数であって、ツールの数ではない。実際にエージェントが呼べるツールは、起動時に registry.register(...) で登録される 71 件だ。この区別は第5回で全 71 件のカタログを並べて検証する。
2. レイヤ構造（俯瞰図）
Hermes は大きく 5 層に分かれる。上から、ユーザーが触れるサーフェス（CLI / TUI / Web / 各種チャット）、それらを束ねるコネクティビティ（Gateway / ACP / MCP）、心臓部のコア・ランタイム（会話ループ・状態・記憶）、能力を与えるツール&拡張、そして最下層のモデルプロバイダだ。
※ 図ソース:
01-architecture.mmd
この「1 つのコアを多面に露出する」設計思想が Hermes 全体を貫く。同じ会話ループを、エディタからは ACP で、Claude Code からは MCP で、外部アプリからは OpenAI 互換 API で——同時に叩ける。第8回で詳しく追う。
3. ファイル構成ツリー
hermes-agent/
├── run_agent.py # エントリ：1 ターンを駆動
├── hermes_state.py # SQLite + FTS5 セッションストア（4,125 行）
├── cli.py # 旧 CLI（15,994 行）
├── agent/ # コア：conversation_loop.py（4,836 行）, memory_*, context_compressor
├── hermes_cli/ # 新 CLI / main.py（15,674 行）/ kanban*.py
├── tools/ # ツール群（直下 82 ファイル / 再帰 99 / 登録 71）
├── gateway/ # 接続層：run.py（19,741 行）, platforms/
├── plugins/ # 拡張：model-providers/（28）, platforms/（8）, memory/
└── skills/ # 宣言的スキル
UI は Python の外に独立している（ui-tui / web / apps / website）。コアは API を出すだけで、見た目は別レイヤが担う、という分離だ。
テストは 1,353 本（test*.py / *_test.py の実測。tests/ 配下の全 .py は 1,401 だが、テスト関数を持つファイル基準では 1,353）。この規模のエージェントとしては手厚い。
4. ~/.hermes/ に何が置かれるか
ランタイムの状態はすべてホーム配下の ~/.hermes/ に集約される。
-
state.db— セッション・メッセージの SQLite ストア -
config.yaml— 設定 -
.env/auth.json— 平文の資格情報（第10回で扱う最大のリスク） -
cron/skills/memories/logs
.env と auth.json が平文である点は、運用上もっとも気をつけるべき箇所だ。chmod 600 の徹底は第10回のチェックリストに含めた。
5. 小ネタ：バージョンとローリング main
混乱しやすいので最初に整理しておく。Hermes の「版数」は三層ある。
| 層 | 値 | 取得元 |
|---|---|---|
| 公式サイト表示 | v0.15.2 |
hermes-agent.nousresearch.com（2026-06-04 時点） |
| 手元の自己申告版数 | v0.15.1 |
hermes --version（pyproject.toml / hermes_cli/__init__.py） |
| 手元の実体 | v2026.5.29-697-gaeec88c77 |
git describe --tags |
手元の main は、直近タグ v2026.5.29 から 697 コミット先行している（git rev-list --count v2026.5.29..HEAD = 697）。0.15.2 は別タグ v2026.5.29.2 として切られているが、版数 bump はタグ側だけで main のコード（pyproject.toml）には反映されていない。だから「公式サイトは 0.15.2 なのに手元は 0.15.1 と名乗る」という一見矛盾した状態が生まれる。
つまり手元のコードは「0.15.2 より新しいが、自分を 0.15.1 と呼ぶ」。rolling main を読むときの典型的な落とし穴なので、本連載の行番号も hermes update のたびにずれうる点を各記事末尾に注記する。
次回は心臓部、run_agent.py と agent/conversation_loop.py（4,836 行）の会話ループを 1 ターン分解剖する。
対応マップ章: §0, §1, ファイルツリー / 行番号は hermes update でずれうる
クイックイタレート株式会社
IoT / 電力監視 / AI / 衛星・無線通信 / システムインテグレーション/
ローカル LLM・エージェント基盤に関するお問い合わせはお気軽にどうぞ。