Substrate

Substrate Memory プラグイン

Claude、ChatGPT、Codex、Hermes の間で引き継がれるメモリを、エージェントに提供します。

チームのための AI メモリ。編集可能で、権限を設定でき、所有権を持てます。

trysubstrate.co：チームとエージェントのためのコンテキストレイヤーです。

• Gemini CLI：gemini extensions install https://github.com/Substrate-memory/Substrate-memory-plugins（最新リリースを使用します。--ref v<version> で特定のバージョンに固定できます）
• MCP レジストリ名：co.trysubstrate/memory（リモートサーバー https://app.trysubstrate.co/mcp）

Substrate は、決定、好み、人々、プロジェクトを記憶します。一度接続するだけで、サポート対象のすべてのエージェントが各ターンの前に重要なことを思い出し、ターンの後に重要なことを保存します。接続画面は一つ、確認手順は一つ、承認は一度だけです。API キーは不要です。貼り付けるトークンもありません。管理するシークレットもありません。

利用できる機能

• 毎ターン前に記憶を呼び出します。 エージェントが回答する前に、関連する記憶がコンテキストとして挿入されます。
• 完了したすべてのターンを自動的に記録します。 ユーザーメッセージ、アシスタントの回答、範囲を限定して秘匿情報を削除したツール呼び出しとその結果が保存されます。
• セッションの境界を記録します。 セッションの開始、再開、リセット、圧縮、終了が記録されるため、記憶は適切なセッションに紐付けられます。
• サブエージェントの作業を記録します。 サブエージェントが行った作業は、親セッションに送られます。
• 確実に配信します。 同じ内容が二重に保存されることはありません。Hermes はプロファイルごとの書き込み先行ログスプールを使用します。Claude と Codex はホストのトランスクリプトをスプールとして扱います。サーバーが不足しているターンを報告し、プラグインの同期処理が決定的な ID を使って再インポートします。
• 明示的に記憶・削除できます。 「これを覚えておいて」と伝えると、事実を保持します。証拠の記録を削除せずに、個別の事実を撤回できます。
• 証拠を確認できます。 思い出された事実に頼る前に、その出典を確認できます。
• 過去の会話をインポートできます。 接続後、一度だけ確認されます。インポートは確認した場合に限られます。

仕組み

Claude (Cowork, Claude Code) --> plugins/substrate-claude --\
ChatGPT (Work, Codex app, Codex CLI) --> plugins/substrate-codex --\
Hermes --> plugins/substrate-hermes --------------------------------+--> one server-side
Other MCP-capable agent --> plugins/substrate-mcp (fallback only) --/    MCP contract (v2)
                                                                              |
                                                                              v
                                                              recall + capture + memory store

各パッケージは薄いクライアントです。ストレージ、ランキング、秘匿情報の削除チェック、メモリの契約はサーバーが担います。すべてのホストが同じ契約（docs/mcp-contract.md、バージョン 2）を使用します。memory_turn_context はターンを開始して記憶を返し、memory_capture_tool はツールの使用を記録し、memory_capture_turn はターンを終了し、memory_session_boundary はライフサイクルのイベントを記録し、memory_import は見逃したターンや過去のターンを再生します。また、memory_search、memory_expand、memory_evidence、memory_remember、memory_forget を使ってメモリを読み書きします。移行期間中も、旧 Hermes の /api/v1 ワイヤーはサーバーでサポートされます。

インストール

接続したいエージェントに、次の内容を貼り付けます。

Install Substrate memory in this agent by following https://trysubstrate.co/install.md

エージェントは docs/install.md（このリンク先で提供される同じファイル）に従います。ホストを特定し、適切なパッケージをインストールします。このリポジトリからも、同じ依頼を実行できます。

Install the memory plug-in at https://github.com/Substrate-memory/Substrate-memory-plugins
``` The flow is the same everywhere: **Install → Sign in → Review → Approve connection → Connected to Substrate.** Only report **Connected to Substrate.** after an authenticated memory smoke test (`memory_search`) succeeds. The browser's **Connection approved** state is consent only; it is not proof that the agent finished connecting. Never paste or request API keys, manual tokens, or client secrets.

| Your host | Package the agent installs | Guide |
|---|---|---|
| Claude Cowork, Claude Code | `plugins/substrate-claude` | [substrate-claude README](plugins/substrate-claude/README.md) |
| ChatGPT Work, Codex app, Codex CLI | `plugins/substrate-codex` | [substrate-codex README](plugins/substrate-codex/README.md) |
| Hermes | `plugins/substrate-hermes` | [substrate-hermes README](plugins/substrate-hermes/README.md) |
| OpenClaw | no package: generic MCP server | [OpenClaw guide](docs/openclaw.md) |
| Grok | no package: generic MCP server through the Grok CLI | [Grok guide](docs/grok.md) |
| Any other MCP-capable agent | no package: generic MCP server (`plugins/substrate-mcp` is the thin fallback) | [substrate-mcp README](plugins/substrate-mcp/README.md) |

**Hermes in one command** (the repository root is a Hermes plugin that loads `plugins/substrate-hermes`; it passes the Hermes install scan with no override):

```sh
hermes plugins install https://github.com/Substrate-memory/Substrate-memory-plugins --enable

その後、表示された手順に従います。エージェントに一度だけ使用する承認リンクとコードが表示されるので、ブラウザーで承認すると、エージェントが Connected to Substrate as [email protected].（あなたのアカウント）と確認します。

Cowork で手動インストールが必要な場合は、Cowork tab → Customize → Plugins → Personal plugins → + → Add marketplace → Add from a repository (GitHub URL) を使用し、パッケージを参照してインストールします。クライアントが求める権限ダイアログは、引き続きユーザーが操作する必要があります。単一のインストールと復旧ガイドに従ってください。

何が記録され、どこに送信されるか

フックプラグイン（Claude Code、Cowork、Codex、Hermes）を使用すると、各プロンプト、完了した各ターン、および上限を設けたツール呼び出しと結果が、app.trysubstrate.co にあるお客様専用の Substrate テナントに送信されます。保存前にサーバー側でシークレットがマスキングされます。また、同期スクリプトとインポートスクリプトでもクライアント側でマスキングされます。他の場所には何も送信されません。ただし、Hermes パッケージは更新通知を表示するため、1 日に 1 回だけ github.com にあるこのリポジトリの VERSION ファイルも読み取ります（何も送信されません）。Claude Code プラグインと Codex プラグインは、バンドルされた単一のローカルスクリプト scripts/substrate_sync.py を実行します。このスクリプトは、このエージェント自身の会話ファイルのみを読み取り（選択したインポートと追いつき同期に使用）、https://app.trysubstrate.co/mcp にのみ送信します。それ以外のホストは拒否されます。取り扱う認証情報は、Substrate 独自の有効期間が短いインポートチケットのみです。このチケットは、単回使用のクレームによって Substrate サーバーから取得するか、エージェントが書き込んだ一時ファイルから取得し、読み取り後に削除されます。Claude Code や Codex のサインインファイル、キーチェーン、SSH キー、クラウドキーを読み取ることはなく、コードをダウンロードすることも、ダウンロードしたコードを実行することもありません。更新はプラグインマーケットプレイス経由でのみ行われます。フックを使わない場合（通常の MCP、Gemini CLI）、保存されるのはエージェントが明示的に保存した内容のみです。すべての行を確認、編集、削除できます。アカウントを削除すると、30 日以内にデータが消去されます。

セキュリティとプライバシー

• ブラウザーでのみ承認。 ブラウザーでサインインし、エージェントを Substrate に接続を選択します。エージェントは正確なリンクを表示し、ユーザーに代わって承認することはありません。
• 管理するキーは不要。 この製品がユーザーに API キーを発行することはなく、貼り付けたトークンやクライアントシークレットを求めることもありません。
• 送信前後のマスキング。 送信前にクライアント側でシークレットをマスキングし、取り込み時にサーバー側でも再度マスキングします。記録されるツール引数には上限（4096 バイト）があり、ツール結果は抜粋（8192 バイトとダイジェスト）として保存されます。
• テナントの分離。 すべての認証情報はテナントにスコープされています。アカウントの識別情報はサーバーが管理し、クライアントがテナント ID やアカウント ID を送信することはありません。
• 保存されるもの。 マスキングされたターンの内容、セッションの境界、ユーザーが確認した明示的なメモリ、およびその根拠とともに記録された取り消し情報です。
• 保存されないもの。 パスワード、API キー、トークン、その他のシークレットは、保存前にマスキングされます。会話履歴のインポートは、ユーザーが選択した後にのみ実行されます。

SECURITY.md と docs/threat-model.md を参照してください。

過去の会話をインポートする

Connected to Substrate. の直後、同じ返信の中で、エージェントはこのコンピューターで見つかった内容を示して、1 回だけ提案します。

このコンピューターで過去の会話が 87 件見つかりました（1,204 ターン、2026 年 3 月 3 日から 10 月 7 日まで）。Substrate にインポートしますか？ すべてインポート / 選択する / 今はしない

• すべてインポートを選ぶと、現在の会話（リアルタイムですでに記録済み）を除く、ローカルのすべての会話がインポートされます。インポートはバックグラウンドで実行されます。エージェントは、ユーザーを待たずに進行状況と最終結果（インポートした会話の件数と、Substrate が現在その会話を読み取っていること）を報告します。
• 選択するを選ぶと、会話が日付とタイトル別に一覧表示され、選択したものだけがインポートされます。
• 今はしないを選ぶと、その選択が記憶され、再度尋ねられることはありません。いつでも「過去の会話をインポートして」と頼めます。
• インポート状態はアカウントごとではなく、コンピューターごとに保持されます。同じコンピューターで後から別の Substrate アカウントに接続すると、エージェントはそのアカウントを確認し、以前の会話をそのアカウントにインポートするかどうかを提案します。

Claude Code と Codex は、有効期間が短くインポート専用のチケット（memory_import_ticket）を使ってパッケージスクリプトから直接アップロードするため、会話履歴がチャットを経由することはありません。Hermes は独自のプロファイル履歴を読み取り、スプール経由で送信します。Cowork のクラウドセッションにはローカルの会話履歴がないため、この提案は省略されます。インポート時にはクライアント側とサーバー側の両方でマスキングされ、重複したインポートは無視されます。

対応ホストとバージョン

リリース	Hermes	Claude Code	Cowork	Codex / ChatGPT Work	その他の MCP クライアント	ステータス
v0.10.0	plugins/substrate-hermes（Hermes 0.21.0 以降でテスト済み）	plugins/substrate-claude	plugins/substrate-claude	plugins/substrate-codex	plugins/substrate-mcp フォールバック	リリース候補

すべてのパッケージは、どのホストバージョンにもインストールできます。テスト済みの範囲外では、エージェント（および Hermes プラグイン自体）は拒否する代わりに、わかりやすいメッセージを表示します。Hermes 0.21.0 以降でテスト済みです。現在のバージョンは X です。動作するはずですが、問題があればお知らせください。 それより新しい Hermes バージョンではメッセージは表示されません。COMPATIBILITY.md をご覧ください。

既知の制限事項を正直にお伝えします。

• Codex にはセッション終了フックがないため、サーバーは30分間アイドル状態のセッションを閉じます。
• Claude Code では SessionStart 時に MCP ツールフックを使用できないため、最初のターンがセッション境界を示します。
• Cowork のクラウドセッションが Substrate に接続できない状態で終了し、その後一度も再開されない場合、最後のターンは復元されません。
• Codex では Substrate のフックを一度承認する必要があります。Codex アプリではフック設定から、ターミナルでは /hooks から承認してください。
• Cowork では、インストール後に新しいセッションを開始するまでツールが表示されません。
• サインアウト中またはサインインを解除した後、Claude Code に赤字で「MCP server not connected」または「Unauthorized」のフックエラーが表示されることがあります。Claude Code はこれらをプラグインのキャプチャフックから報告するため、プラグイン側で非表示にはできません。/substrate-claude:substrate-connect で再接続してください。

全体の互換性一覧と履歴については、COMPATIBILITY.md をご覧ください。

よくある質問

API キーは必要ですか？ いいえ。ブラウザーでサインインして承認してください。コピーや貼り付けは必要ありません。

エージェントにはどのパッケージをインストールすればよいですか？ Claude Cowork と Claude Code では plugins/substrate-claude を使用します。ChatGPT Work、Codex アプリ、Codex CLI では plugins/substrate-codex を使用します。Hermes では plugins/substrate-hermes を使用します。OpenClaw、Grok、その他の MCP 対応エージェントは汎用 MCP サーバーに接続します。独自のパッケージがないシステムでは、これがデフォルトです。plugins/substrate-mcp は軽量なフォールバックパッケージです。

接続されているかどうかは、どうすればわかりますか？ エージェントが認証済みのメモリースモークテストを実行します。memory_search に合格した場合にのみ、Substrate に接続済みとなります。

Substrate には具体的に何が送信されますか？ 完了した各ターンについて、メッセージ、エージェントの回答、範囲を限定したツール呼び出しとその結果が送信されます。送信前とサーバー上で、いずれも機密情報が削除されます。履歴のインポートでは、すべてインポートを選択するか、セッションを選んだ後に限り、同じ形式で機密情報を削除したターン内容が送信されます。

古い、2026年8月の API キープラグインはどうなりますか？ これらのプラグイン（substrate_capture、ローカルのスプールパス、SUBSTRATE_API_KEY の設定）は非推奨です。アンインストールして、ブラウザーフローから接続してください。ローカルのスプールは移行されません。

ロールバックできますか？ はい。変更されない v0.5.0 タグと v0.6.0 タグをロールバック用に引き続き利用できます。

開発とリリース

UV_PROJECT_ENVIRONMENT=$PWD/.venv uv sync --project tooling --frozen --extra dev
.venv/bin/ruff check .
.venv/bin/python -m pytest -q
python3 scripts/check_public_hygiene.py --root .
.venv/bin/python scripts/build_release.py
.venv/bin/python scripts/build_release.py --check

リリースは段階的に進められ、ゲートで管理されます。レビュー用ブランチからタグ付けや公開が行われることはありません。docs/releasing.md をご覧ください。

リンク

• インストールと復旧ガイド
• アーキテクチャ
• 信頼できる情報源の境界
• 互換性
• セキュリティ
• 変更履歴
• MCP コントラクト v2（メモリーツールの唯一の信頼できる情報源）