Hermes エージェント☤ 入門 : 永続メモリ

Posted on by Masashi Okumura

Hermes Agent は、セッション間で永続化される、制約付き、整理された (curatd) メモリを備えています。これにより、ユーザーの設定、プロジェクト、環境、そして学習した内容を記憶することができます。

Hermes エージェント☤ 入門 : 機能 – コア : 永続メモリ

作成 : Masashi Okumura (@classcat.com)
作成日時 : 08/05/2026
バージョン : Hermes Agent v0.20.0 (2026.8.3)

* 本記事は hermes-agent.nousresearch.com/docs の以下のページを参考にしています :

* サンプルコードの動作確認はしておりますが、必要な場合には適宜、追加改変しています。

 

 

Hermes エージェント☤ 入門 : 機能 – コア : 永続メモリ

Hermes Agent は、セッション間で永続化される、制約付き、整理された (curatd) メモリを備えています。これにより、ユーザーの設定、プロジェクト、環境、そして学習した内容を記憶することができます。

 

How It Works

エージェントのメモリは、以下の 2 つのファイルで構成されています :

  • (ファイル – 目的 – 文字数制限)

  • MEMORY.md – エージェントの専用メモ ― 環境に関するファクト、慣習、学んだこと – 2,200 文字 (~800 トークン)

  • USER.md – ユーザプロファイル – ユーザ設定、コミュニケーション・スタイル、要望 – 1,375 文字 (~500 トークン)

どちらも ~/.hermes/memories/ に保存され、セッション開始時に凍結されたスナップショットとしてシステムプロンプトに注入されます。エージェントは memroy ツールを使用して自身のメモリを管理します – エントリの追加、置換、削除を行うことができます。

 

システムプロンプトでメモリがどのように配置されるか

すべてのセッションの開始時に、メモリエントリはディスクからロードされ、frozen ブロックとしてシステムプロンプトにレンダリングされます :

══════════════════════════════════════════════
MEMORY (your personal notes) [67% — 1,474/2,200 chars]
══════════════════════════════════════════════
User's project is a Rust web service at ~/code/myapi using Axum + SQLx
§
This machine runs Ubuntu 22.04, has Docker and Podman installed
§
User prefers concise responses, dislikes verbose explanations

フォーマットには以下の内容が含まれます :

  • どのストア (MEMORY または USER PROFILE) かを示すヘッダ

  • 使用率と文字数、エージェントが容量を把握するため

  • § (セクション記号) で区切られた個々のエントリ

  • エントリは複数行にすることができます

凍結スナップショットパターン : システムプロンプト注入はセッション開始時に一度だけキャプチャされ、セッションの途中で変更されることはありません。これは意図的なものです – LLM のプレフィックスキャッシュをパフォーマンスのために保持します。エージェントがセッション中にメモリエントリを追加/削除すると、変更は直ちにディスクに永続化されますが、次のセッションが開始されるまでシステムプロンプトには配置されません。ツールの応答は常に最新の状態を示します。

 

メモリツールのアクション

エージェントは、以下のアクションでメモリツールを使用します :

  • add (追加) — 新しいメモリエントリを追加します

  • replace (置換) — 既存のエントリを更新されたコンテンツに置き換えます (old_text による部分文字列マッチングを使用)

  • remove (削除) — もはや関係がないエントリを削除します (old_text による部分文字列マッチングを使用)

read (読み取り) 操作は不要です – メモリの内容はセッション開始時にシステムプロンプトに自動的に注入されます。エージェントはそのメモリを会話コンテキストの一部として認識します。

 

部分文字列マッチング

replace と remove アクションでは、短い一意の部分文字列マッチングを使用します – エントリのテキスト全体は必要ありません。old_text パラメータには、正確に 1 つのエントリを識別する、一意の部分文字列である必要があります :

# If memory contains "User prefers dark mode in all editors"
memory(action="replace", target="memory",
       old_text="dark mode",
       content="User prefers light mode in VS Code, dark mode in terminal")

部分文字列が複数のエントリにマッチする場合、より具体的な一致条件を求めるエラーが返されます。

 

2 つのターゲットの説明

memory – エージェントのパーソナルメモ

環境、ワークフロー、および学習したレッスンについて、エージェントが覚えておく必要がある情報 :

  • 環境情報 (OS、ツール、プロジェクト構造)

  • プロジェクトの慣習と設定

  • 検出したツールの癖 (quirks) と回避策

  • 完了したタスク日誌のエントリ

  • 機能したスキルとテクニック

 

user — ユーザープロフィール

ユーザーのアイデンティティ、好み、コミュニケーション・スタイルに関する情報 :

  • 名前、役割、タイムゾーン

  • コミュニケーションの好み (簡潔 vs 詳細か、フォーマットの好み)

  • 個人的にイライラすること (Pet peeves) や避けたいこと

  • ワークフローの習慣

  • 技術スキルレベル

 

What to Save vs Skip

(積極的に) 保存すべき項目

エージェントは自動的に保存します – ユーザーが指示する必要はありません。エージェントは以下を学習した際に保存します :

  • ユーザー設定 : “I prefer TypeScript over JavaScript” → user に保存

  • 環境情報 : “This server runs Debian 12 with PostgreSQL 16” → memory に保存

  • 修正事項 : “Don’t use sudo for Docker commands, user is in docker group” → memory に保存

  • 規約 : “Project uses tabs, 120-char line width, Google-style docstrings” → memory に保存

  • 完了したワーク : “Migrated database from MySQL to PostgreSQL on 2026-01-15” → memory に保存

  • 明示的なリクエスト : Remember that my API key rotation happens monthly” → memory に保存

 

スキップすべき情報

  • 自明な/明白な情報 : “User asked about Python” — 曖昧すぎて役に立たない

  • 簡単に再発見できる事実 : “Python 3.12 supports f-string nesting” – これは Web 検索できます

  • 生データダンプ : 大きなコードブロック、ログファイル、データテーブル – メモリ容量を超えます

  • セッション固有の一時的な情報 : 一時ファイルパス、単発のデバッグコンテキスト

  • コンテキストファイルに既に含まれている情報 : SOUL.md と AGENTS.md の内容

 

容量管理

メモリは、システムプロンプトを束縛し続けるために、厳格な文字数制限が設けられています :

  • (ストア – 制限 – 一般的なエントリ数)

  • memory – 2,200 文字　- 8-15 エントリ

  • user – 1,375 文字 – 5-10 エントリ

 

What Happens When Memory is Full

制限を超えるエントリを追加しようとすると、ツールはエラーを返します :

{
  "success": false,
  "error": "Memory at 2,100/2,200 chars. Adding this entry (250 chars) would exceed the limit. Consolidate now: use 'replace' to merge overlapping entries into shorter ones or 'remove' stale or less important entries (see current_entries below), then retry this add — all in this turn.",
  "current_entries": ["..."],
  "usage": "2,100/2,200"
}

エージェントは次に以下の手順を実行します :

  1. (エラー応答に示される) 現在のエントリを読み込む

  2. 削除または統合可能なエントリを特定する

  3. 置換機能を使用して、関連するエントリをより短いバージョンにマージする

  4. そして、新しいエントリを追加する

ベストプラクティス : メモリ使用率が 80% を超えた場合 (システムプロンプトのヘッダーに表示されます)、新しいエントリを追加する前に既存のエントリを統合してください。例えば、”project uses X” という 3 つの別々のエントリを 1 つの包括的なプロジェクト説明エントリに統合します。

 

良いメモリ・エントリの具体例

簡潔で情報密度の高いエントリが最善に機能します :

# Good: Packs multiple related facts
User runs macOS 14 Sonoma, uses Homebrew, has Docker Desktop and Podman. Shell: zsh with oh-my-zsh. Editor: VS Code with Vim keybindings.

# Good: Specific, actionable convention
Project ~/code/api uses Go 1.22, sqlc for DB queries, chi router. Run tests with 'make test'. CI via GitHub Actions.

# Good: Lesson learned with context
The staging server (10.0.1.50) needs SSH port 2222, not 22. Key is at ~/.ssh/staging_ed25519.

# Bad: Too vague
User has a project.

# Bad: Too verbose
On January 5th, 2026, the user asked me to look at their project which is
located at ~/code/api. I discovered it uses Go version 1.22 and...

 

重複防止

メモリシステムは、完全に重複するエントリを自動的に拒否します。既に存在するコンテンツを追加しようとすると、”no duplicate added” メッセージとともに成功が返されます。

 

セキュリティスキャン

メモリエントリはシステムプロンプトに注入されるため、受け入れられる前にインジェクション (攻撃) およびエクスフィルトレーション (exfiltration, 情報漏洩) パターンがスキャンされます。脅威パターン (プロンプトインジェクション、認証情報エクスフィルトレーション、SSH バックドア) にマッチするコンテンツや、不可視の Unicode 文字を含むコンテンツはブロックされます。

 

セッション検索

MEMORY.md と USER.md以外にも、エージェントは session_search ツールを使用して過去の会話を検索できます。

すべての CLI およびメッセージング・セッションは、FTS5 全文検索を備えた SQLite（~/.hermes/state.db) に保存されます。検索クエリは、データベースから実際のメッセージを返します – LLM による要約や切り捨て (truncation) は行われません。エージェントは、アクティブメモリに存在しない場合でも、数週間前に議論した内容を見つけられます。また、エージェントは、見つけたセッション内で前後にスクロールすることもできます。

hermes sessions list    # Browse past sessions

3 つの呼び出し形状 (発見/スクロール/ブラウズ）と応答形式については、Session Search Tool を参照してください。

 

session_search vs メモリ

機能 永続メモリ セッション検索
容量 総計 約1,300トークン 無制限 (全セッション)
速度 即時 (システムプロンプト内) FTS5クエリ 約20ms、スクロール 約1ms
コスト 全プロンプトでトークンコスト 無料 – LLM 呼び出しなし
ユースケース 重要な情報が常時利用可能 過去の特定の会話を検索
管理 エージェントが手動でキュレーション 自動 – 全セッションを保存
トークンコスト セッションごとに固定 (約1,300トークン) オンデマンド (必要な時に検索)

メモリ は、常にコンテキストの中で参照されるべき重要なファクトを記憶するためのものです。セッション検索 は、”did we discuss X last week?” といった、エージェントが過去の会話から具体的な内容を思い出す必要があるクエリに対応するためのものです。

 

学習の軌跡（/journey）

学習の軌跡 (learning journey) は、Hermes が学んだすべてのことを時系列で表示するものです – 保存されたスキルや記憶のエントリが時間とともにプロットされ (古いものが一番上、新しいものが一番下)、ビルドアップ (学習の過程) を再生可能な「星座状グラフ」のシークバーも備えています。同じグラフデータに基づいて、以下の 3 つの UI が駆動されます :

  • 従来の CLI / スタンドアロン — `hermes journey`（エイリアス: `hermes learning`, `hermes memory-graph`) は、ターミナルにタイムラインを表示します。フラグ: –play はビルドアップをアニメーション表示し (–fpsで調整可能)、–width/–height はレンダリングサイズをオーバーライド、–no-color は色を無効、–json は生のグラフ・ペイロードをダンプします。

  • TUI — /journey (別名：/learning, /memory-graph) は、タイムラインをオーバーレイ (重ね合わせ表示) として開きます。

  • デスクトップ・アプリ — /journey は、スターマップ / memory-graph パネルを開きます。これは、同じノードをインタラクティブに視覚化したものです。

表示するだけでなく、journey はエルメスが学んだことを 切り捨て、修正する 場でもあります :

  • (コマンド – What it does)

  • `hermes journey list` – ノード ID の一覧 — スキル名とメモリチャンクの memory:<source>:<index>

  • `hermes journey delete <node> [-y]` – ノードを削除します。スキルはアーカイブされ (復元可能)、メモリチャンクは削除されます。-y を指定すると確認がスキップされます。

  • `hermes journey edit <node>` – $EDITOR でノードのコンテンツ（スキルの SKILL.md またはメモリチャンク）を開きます。

 

設定

# In ~/.hermes/config.yaml
memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200   # ~800 tokens
  user_char_limit: 1375     # ~500 tokens
  write_approval: false     # false = write freely (default) | true = require approval

 

以上