第 2 章アーキテクチャ全体像 — 部品の地図と ~/.hermes/｜Hermes Agent 入門

この章で分かること

Hermes を構成する部品（CLI・ゲートウェイ・AIAgent コア・ツール群・実行環境）がどう繋がっているか
GitHub のリポジトリ本体と、インストール後にできる ~/.hermes/ は別物だということ
~/.hermes/ の直下に何があり、それぞれ誰が書き、いつ読まれるか
SOUL.md / AGENTS.md / config.yaml / .env のどれに何を書けばいいかの見分け方
ユーザーの発話 1 回（1 ターン）の裏で何が起きているかの大まかな流れ

これは何か

この章に「これ 1 つを実行すれば分かる」という単一のコマンドはない。地図なので、代わりに地図を確かめる 4 つの入り口を覚えておくと後で役立つ。

ターミナルで ~/.hermes/ を直接 ls する（実行時データの実物を見る）
hermes doctor で設定・依存関係・接続性の状態を診断する
hermes config / hermes config get <key> で config.yaml の中身を覗く
GitHub の NousResearch/hermes-agent でソースそのものを読む

Hermes という 1 つのプロダクトの正体・思想については第 1 章に譲る。この章が扱うのは「その中身はどんな部品からできていて、部品同士がどう繋がっているか」という構造だけである。結論を先に言うと、Hermes は 1 つの中核（AIAgent、会話ループの心臓部）に、CLI・ゲートウェイ・cron などの複数の入り口と、ターミナル・ブラウザ・Web・メモリなどの複数の道具箱がぶら下がる形をしている。

いつ使うのか

地図そのものを毎回意識する必要はないが、次の 4 つの場面では役に立つ。

何かを変えたいとき — 「口調を変えたい」のか「モデルを変えたい」のかで、触るべきファイルが SOUL.md なのか config.yaml なのか変わる
動かないとき — CLI・ゲートウェイ・cron のどの入り口から入った処理が失敗したのかで、見るべきログや疑うべき層が変わる
複数のエージェントを使い分けたいとき — プロファイルごとに ~/.hermes/ 相当の実行時データがまるごと独立して複製される（詳しくは後述）
GitHub のソースや Issue を読みたいとき — リポジトリのどのディレクトリに何があるかが分かっていないと迷子になる

特に迷いやすいのが「どのファイルに何を書けばいいか」の切り分けである。まず次の早見表で見当をつけ、詳細は各章に進む。

したいこと	触る場所
エージェントの自己紹介・口調・性格を変えたい	`SOUL.md`
エージェントに恒久的に憶えておいてほしい事実を足したい	`MEMORY.md` / `USER.md`（第 5 章）
このプロジェクト固有のルールや構成を読ませたい	プロジェクト直下の `AGENTS.md`（または `.hermes.md`）
使うモデルやターミナルバックエンドを変えたい	`config.yaml`（第 3 章）
API キーやゲートウェイのトークンを設定したい	`.env`（第 3 章、第 7 章）
動かない原因をまず切り分けたい	`logs/errors.log` と `logs/gateway.log`

全体アーキテクチャ — 1 つの中核と複数の入り口・道具箱

Hermes には CLI・メッセージングゲートウェイ・cron・エディタ連携（ACP）・バッチ実行など複数の「入り口」があるが、そのすべてが最終的に AIAgent（run_agent.py に実装された会話ループの中核）という単一のクラスに集約される。README が挙げる「Platform-agnostic core」という設計原則そのままに、CLI 用にもゲートウェイ用にも別のエンジンは存在しない。

図 2-1　CLI・ゲートウェイ・cron のどこから来た入力も同じ AIAgent コアに集約され、ツール群とモデルプロバイダ API へ橋渡しされる。

この図の各ボックスは後続の章で個別に深掘りする。CLI と対話操作は第 4 章、ゲートウェイは第 7 章、cron は第 8 章、モデルプロバイダの設定は第 3 章、ツール実行環境（ターミナルバックエンド）は第 10 章、ブラウザ・Web ツールは第 11 章、セッション保存とメモリの詳細は第 5 章を参照。この章で覚えておくべきなのは「入り口が何であれ、中核は 1 つ」という点だけである。

もう 1 つ、公式のアーキテクチャ図で覚えておくと得なのが「主要サブシステム」の一覧である。ツールシステムだけで 70 種類以上のツールが約 28 のツールセットにまとめられ、プロバイダ解決は 18 系統以上、メッセージングゲートウェイのアダプタは 25 種類以上に及ぶ（いずれも 2026-09 時点、v0.21.0）。数の大きさそのものより、「入口・中核・道具箱」という 3 層構造だけをこの段階では持ち帰ってほしい。

2 つの「住所」— リポジトリ本体と `~/.hermes/`

初心者がまず混同しやすいのが、GitHub からクローンした（または install.sh がクローンした）リポジトリ本体と、セットアップ後に生成される ~/.hermes/ の違いである。前者はコード、後者はあなたのエージェントの実行時データであり、性質がまったく異なる。

ディレクトリ	役割
`agent/`	会話ループの内部実装（システムプロンプト組み立て・コンテキスト圧縮・プロンプトキャッシュ等）
`hermes_cli/`	`hermes` コマンド本体（サブコマンド・設定・セットアップウィザード）
`tools/`	ツール実装（1 ファイル 1 ツール。ターミナル・ファイル・Web・ブラウザ・委任など）
`gateway/`	メッセージングプラットフォーム連携の中核（配信・セッション・DM ペアリング）
`plugins/`	モデルプロバイダ・メッセージングプラットフォーム・メモリプロバイダのプラグイン集
`skills/` / `optional-skills/`	組み込みスキルと、明示インストールが要る公式オプションスキル
`cron/`	スケジューラの実装（`jobs.py`, `scheduler.py`）
`acp_adapter/`	VS Code / Zed / JetBrains 向け ACP サーバー

これは全ディレクトリの網羅ではなく、迷ったときに立ち返るための代表的なものだけを挙げている。全体は GitHub の NousResearch/hermes-agent を直接見るのが早い。ここで重要なのは「リポジトリはコードであり、1 つしかない」ということである。hermes update（内部的には git pull ベース）で更新されるのはこちら側で、あなたが日々使う SOUL.md・メモリ・設定・セッション履歴は一切含まれない。

対して ~/.hermes/ は インストール後に生成される、あなた専用の実行時データ である。しかも hermes profile create でプロファイルを増やすと、SOUL・スキル・メモリ・セッション・クレデンシャルがそれぞれ独立した状態で複数同時に存在しうる（設計原則でいう「Profile isolation」）。1 台のマシンに 1 つしかないリポジトリと、複数ありうる ~/.hermes/ という非対称性を、この章の一番の要点として持ち帰ってほしい。

~/.hermes/ の中身 — どのファイルが何をするか

~/.hermes/ の直下は、大きく 4 つの系統に分けて把握すると見通しがよい。

図 2-2　~/.hermes/ の直下は「識別・記憶」「設定・認証」「実行時データ」「拡張」の 4 系統に分けて把握すると迷わない。

とりわけ迷いやすい 5 つのファイルについて、公式ドキュメントの一覧表を要約せずに載せる。

ファイル	中身	誰が書くか	いつ読まれるか
`SOUL.md`	エージェントの一次アイデンティティ（性格・トーン・文体）	ユーザー。無ければ Hermes が起動時にファイルを自動生成し、既存ファイルは上書きしない	system prompt スロット #1、セッション開始時
`USER.md`	ユーザープロフィール（名前・役割・好み・コミュニケーションスタイル）	エージェントが `memory` ツール経由で書く（`write_approval` でゲート可）	セッション開始時に system prompt へ凍結スナップショットとして注入
`MEMORY.md`	エージェント自身のメモ（環境事実・プロジェクト規約・ツールの癖・学習内容）	エージェントが `memory` ツール経由で書く（USER.md と同じゲート）	同上
`AGENTS.md`	プロジェクトの指示・規約・アーキテクチャ	ユーザー（またはプロジェクト著者）	起動時にワーキングディレクトリから system prompt へ読み込み、サブディレクトリのネストされたコピーも段階的に発見
`.hermes.md` / `HERMES.md`	AGENTS.md 相当だが Hermes 固有かつ最優先	ユーザー	起動時に system prompt へ読み込み（AGENTS.md より優先）

プロジェクトコンテキストファイルは 1 セッションにつき 1 種類のみロードされ、優先順位は .hermes.md → AGENTS.md → CLAUDE.md → .cursorrules の「先勝ち」である。SOUL.md だけはこのチェーンと独立に常にロードされる。メモリの文字数上限・注入フォーマット・書き込み承認（write_approval）といった詳細は第 5 章に譲る。

config.yaml と .env の位置づけも、この地図の一部として押さえておきたい。設定の優先順位は「① CLI 引数 → ② config.yaml → ③ .env → ④ ハードコードされたデフォルト」で、ルールは単純に「秘密は .env、それ以外（モデル・ターミナルバックエンド・圧縮設定・メモリ上限・ツールセットなど）は config.yaml」である。auth.json は Nous Portal など OAuth 認証プロバイダの認証情報専用で、これも秘匿情報として .env 側と同じ扱いになる。実際に hermes setup でこれらを組み立てる手順は第 3 章で扱う。

1 ターンの流れ

「入り口」「中核」「道具箱」の 3 層が、実際の 1 往復の会話でどう動くかを時間軸で見ておく。

図 2-3　システムプロンプトはセッション開始時に一度だけ組み立てられ、ツール呼び出しは応答が確定するまで繰り返されうる。

ここで押さえておくべき設計原則が「Prompt stability」である。system prompt はセッション中は変化しない「凍結スナップショット」として扱われる。ミッドセッションでエージェントが memory ツールでメモを書いても、ディスクには即座に保存される一方、system prompt に反映されるのは次のセッションからになる（プロンプトキャッシュを壊さないための意図的な設計）。ツール呼び出しの中身（どんなツールがあるか、どう選ばれるか）は第 6 章や第 9 章で扱う。

つまずきポイント

リポジトリと ~/.hermes/ を混同する — GitHub からクローンしたコード側に大事な設定を書き足しても、実行時にはまったく反映されない。あなたの設定・メモリ・スキルはすべて ~/.hermes/ 側にある。hermes update はコード側だけを更新する。

プロジェクトのルールを全部 AGENTS.md に書いてしまう — プロジェクトコンテキストファイルは 1 セッションにつき 1 種類しかロードされない。.hermes.md と AGENTS.md を両方置いても、読まれるのは優先順位が高い .hermes.md だけで、もう一方は静かに無視される。

API キーを config.yaml に平文で書いてしまう — config.yaml は非秘匿設定専用で、リポジトリ共有や画面共有の際にそのまま映り込みやすい。秘密は .env に置き、hermes config set OPENROUTER_API_KEY ... のようにキーの種類ごとの自動振り分けに任せる。

ドキュメント間の数値の食い違いをそのまま信じる — たとえば公式アーキテクチャ図の注記は「ターミナル 6 backends」と書かれているが、設定ドキュメント本文は「7 backends」と明記している（Vercel Sandbox を含む数え方の違い）。バージョン依存の数値は 1 箇所だけを見て確定させず、hermes doctor や設定ドキュメント本文で裏を取る癖をつけたい。

理解度チェック

Q1. GitHub からクローンしたリポジトリ本体と ~/.hermes/ の違いは何ですか？

リポジトリ本体は Hermes のコードそのもの（1 台のマシンに通常 1 つ、hermes update で更新）。~/.hermes/ はインストール後に生成される実行時データ（SOUL.md・メモリ・設定・セッション履歴など）で、hermes profile create によりプロファイルごとに独立して複数存在しうる。

Q2. プロジェクト直下に AGENTS.md と .hermes.md の両方があると、どちらが読まれますか？

.hermes.md（または HERMES.md）が優先される。優先順位は .hermes.md → AGENTS.md → CLAUDE.md → .cursorrules で、1 セッションにつき 1 種類のみロードされる。SOUL.md はこのチェーンとは独立に常にロードされる。

Q3. OpenRouter の API キーはどこに書くのが正しいですか？

~/.hermes/.env。config.yaml は非秘匿設定（モデル・ターミナルバックエンドなど）専用で、秘密情報は .env に置く。hermes config set OPENROUTER_API_KEY sk-or-... のようにコマンドで設定すれば、キーの種類に応じて自動的に振り分けられる。

Q4. セッション中にエージェントが memory ツールで新しいメモを書いた場合、そのメモは同じセッションの system prompt にすぐ反映されますか？

されない。system prompt への注入はセッション開始時に一度だけキャプチャされる「凍結スナップショット」であり、ミッドセッションで書いたメモリはディスクには即座に保存されるが、system prompt に反映されるのは次のセッションから。プロンプトキャッシュを壊さないための意図的な設計である。

まとめ

Hermes は CLI・ゲートウェイ・cron など複数の入り口を持つが、すべて単一の AIAgent コアに集約される
GitHub のリポジトリ本体（コード）と ~/.hermes/（実行時データ）は別物で、後者はプロファイルごとに複数存在しうる
~/.hermes/ 直下は「識別・記憶」「設定・認証」「実行時データ」「拡張」の 4 系統で把握する
何を書くべきかは「口調なら SOUL.md、恒久的な事実なら MEMORY.md/USER.md、プロジェクト規約なら AGENTS.md、非秘匿設定なら config.yaml、秘密なら .env」で切り分ける
system prompt はセッション開始時の凍結スナップショットで、ミッドセッションの変更は次のセッションから反映される

次章では、この地図を実際に自分のマシンへ展開する。install.sh が具体的に何をしているか、hermes setup の 3 つのモード、4 系統のモデルプロバイダの選び方を第 3 章で扱う。

ハンズオン 2-1　~/.hermes/ を歩いて地図と照合する

すでに Hermes をインストール済みなら、ターミナルで次を実行する。まだインストールしていない場合は、第 3 章でインストールした後にこのハンズオンへ戻ってくるとよい。
ホームディレクトリ直下の .hermes の中身を一覧表示する。

ls -la ~/.hermes/

SOUL.md・config.yaml・.env・memories/・state.db・skills/・cron/・sessions/・logs/ が並んでいれば成功。図 2-2 の「識別・記憶」「設定・認証」「実行時データ」「拡張」のどの系統に属するかを 1 つずつ照合してみると、この章の地図が身体に馴染む。

ハンズオン 2-2　config.yaml の位置づけを hermes config で確かめる

現在の設定全体を表示する。
特定のキーの値だけを取得する。

hermes config
hermes config get model

1 つ目のコマンドで ~/.hermes/config.yaml に書かれている設定がまとまって表示され、2 つ目のコマンドで指定したキー（ここではモデル設定）の現在値だけが返る。どちらも読み取り専用で、実行しても状態は変わらない。API キーのような秘匿値は config.yaml ではなく .env 側にあるため、この一覧には出てこない点も併せて確認しておく。設定の変更方法や 4 系統のモデルプロバイダの選び方は第 3 章で扱う。

アーキテクチャ全体像 — 部品の地図と ~/.hermes/