setup

GBrain メモリをセットアップする

すでにユーザーが利用しているエージェントに、信頼できるメモリを追加します。エージェントのアイデンティティ、ネイティブメモリ、既存の指示、無関係な設定は維持してください。まずはキー不要のストレージとキーワード検索から始めます。プライベートリポジトリ、アイデンティティの聞き取り、自動キャプチャ、有料 API キー、バックグラウンドサービスは前提条件ではありません。

契約

• インストール状態を調査または変更する前に、対象の脳とソースを選択します。
• 正常なインストールは再利用し、一部のみの状態や競合状態は、メモリを再初期化せずに診断します。
• 必須の検索モード一覧を伝え、運用者に選択してもらいます。
• 明示的なメモは出所情報とともに保存し、無作為に選んだ内容を書き込んで読み戻し、検証します。
• ソフトウェアのインストール、ネイティブ指示の有効化、会話をまたいだ想起を、それぞれ分けて報告します。
• 自動キャプチャ、インポート、コネクター、スケジュール、有料の情報補強には、明示的なオプトインが必要です。

フェーズ 1：経路を選択する

ユーザーの既存のコンテキストを活用し、すでに選択済みの項目を繰り返し尋ねないでください。

意図	対応
Grok Bot 内にメモリを追加する	第一の選択肢：MCP 経由で自分のコンピューター上の脳を利用します。remote-mcp で公開し（--funnel を指定すると、Bot はベンダーのクラウドで実行されます）、その後、ホスト型ハーネスアクセスで、プライベートな引き継ぎを Bot にインストールします。常時稼働のマシンがない場合は、Grok Bot と、分離されたセットアップヘルパーに従ってください。ルート：/workspace/gbrain。データは .gbrain の下に保存されます。
Muse 内にメモリを追加する	第一の選択肢：MCP 経由で自分のコンピューター上の脳を利用します。remote-mcp で公開し（--funnel を指定）、その後、ホスト型ハーネスアクセスで、プライベートな引き継ぎを Muse にインストールします。常時稼働のマシンがない場合は、Museに従ってください。いずれの場合も、まず永続的なユーザーファイルの保存先を確定してください。MUSE.md、永続パス、ネイティブ MCP の仕組みを独自に作り出さないでください。
既存の別のエージェントにメモリを追加する	INSTALL_FOR_AGENTS.mdに従ってください。コーディングエージェントのチュートリアルでは、Claude Code と Codex を扱っています。
既存のホスト型の脳に接続する	mcp-accessとホスト型ハーネスアクセスに従ってください。対象のハーネスに合わせて、ネイティブ OAuth/PKCE またはプライベートなマシン経由の引き継ぎを選択します。
MCP 経由で他のデバイス、アプリ、クラウドエージェントから脳を利用する	remote-mcpに従ってください。gbrain mcp expose でローカルサーバーを Tailscale tailnet 上に公開します（Funnel はクラウドエージェントの場合のみ）。その後、mcp-access／ホスト型アクセスで、利用者ごとにネイティブ OAuth またはプライベートなマシン経由の引き継ぎを選択します。
アイデンティティとプライベートリポジトリを備えた新しい個人用エージェントを明示的に作成する	BOOTSTRAP_FOR_AGENTS.mdに従ってください。gbrain bootstrap は、この明示的な依頼に対して使用します。
共有アーティファクトを使う、ワークツリーごとのコードエンジンを明示的に設定する	トポロジーに従ってください。脳とソースのルーティングは、個別に設定する必要があります。

意図が不明な場合は、既存のエージェントにメモリを追加する経路を既定とします。安全な対象を選ぶために必要な情報が不足している場合に限って、どの既存の脳に接続するか、または Muse のどのディレクトリを永続的な保存先とするかを尋ねてください。

フェーズ 2：確認、インストール、または修復

既存のインストールでは、記録されている場合は絶対パスのランチャーを使用します。

gbrain engine status --json
gbrain engine status --probe

これらのコマンドはデータベースが停止していても動作します。エンジン、設定の由来、ルート、ソースを確認してください。環境に存在するデータベース／MCP 設定や作業ディレクトリのマウントは、そのデータベースを採用する権限にはなりません。 GBRAIN_HOME だけでは、すべてのルーティングは分離されません。

Grok Bot／Muse の場合は、セットアップヘルパーに選択したルートの確認と分離を任せてください。その周囲で別のグローバルな初期化を実行しないでください。ヘルパーのレシートには、状態が不在、一部のみ、形式不正、競合のいずれであるかが示されます。修復には保持された <root>/bin/gbrain-setup を使用します。採用とアップグレードには明示的なオプションが必要です。初期化エラーからの復旧のために、既存のメモリを置き換えないでください。

その他のローカルインストールでは、正規の配布物とキー不要の初期化に従う前に、競合するルーティングを解消してください。

bun install -g github:garrytan/gbrain#latest-stable
gbrain init --pglite --no-embedding

Bun がない場合は、INSTALL_FOR_AGENTS.md に従って先にインストールしてください。無関係な gbrain という名前の npm パッケージや、ユーザーの現在のプロジェクトでの bun add は使用しないでください。ローカル／シンクライアントへの変換には、明示的な意図と以前の設定の保持が必要です。

必須の検索モード選択： 初期化では非対話型の既定値が選択され、[AGENT] マーカー付きの 9 セルのコストマトリックスが表示される場合があります。続行する前に、そのマトリックスを伝え、オペレーターの選択を確認してください。INSTALL_FOR_AGENTS.md のステップ 3.5 に従い、記憶している価格ではなく、表示されたマトリックスを使用してください。参考として示されるモデル API のコストは、ハーネスのサブスクリプションとは別です。この選択によって、有料 API やキャプチャが有効になることはありません。

ユーザーが明示的に Postgres を希望する場合は、エンジン または postgres-adopt に従ってください。--prefer-postgres は任意です。ユーザーには一度だけ、Postgres ではチェックアウトがあるソースはクラシックモードで開始し、チェックアウトが信頼できる唯一の情報源となり、エージェントはコミット済みファイルとしてページを保存した後に gbrain sync を実行すること、直接保存するにはマネージドモードが必要であることを説明してください（バインドされていないソース）。Supabase では anon key ではなく、データベース接続文字列を使用します。認証情報は非公開にし、環境に存在するシークレットをファイル設定にコピーしないでください。

ホステッドの代替手段

ローカルデータベースの初期化、インポート、保守用インストールはスキップしてください。mcp-access を参照してください。対象のハーネスがネイティブ OAuth／PKCE を使用する場合は、そのネイティブの手順を使用してください。実際のリダイレクト URI と認証方式を登録し、クライアント内で OAuth を開始して、所有者のログインと同意が完了するまで保留中のリクエストを保持します。OAuth 専用のクライアントにマシン引き継ぎをインストールしないでください。

マシン経由の手順では、所有者が認証済みの管理 API を使用し、プライベートな --credentials-out ファイルを指定して gbrain mcp grant から memory-writer 権限を付与します。実際のハーネス識別子を使用してください。稼働中の PGLite サーバーでは、既存のエンジンを使用する必要があります。ライブデータベースを別プロセスで開かないでください。URL や通常の OAuth トークンは管理権限を持ちません。

引き継ぎ情報を対象のハーネスに非公開で転送し、そのハーネスでインストールしてください。

gbrain connect https://brain.example.com/mcp --harness codex \
  --credentials-file /absolute/private/agent-example.json --install

シン CLI アダプターにも、確認済みの永続的な --root が必要です。アダプターの再読み込み手順と、ホステッドガイドの全体に従ってください。利便性のためのヘルスチェックコマンドを通すだけの目的で admin を付与しないでください。委任には明示的な選択、バインドされたツール、アクティブなソース、パスのポリシーが必要です。新しい委任には支出上限がなく、同時実行数は 1 です。付与する前に、この点を説明してください。

フェーズ 3：メモリに関する指示を追加する

既存の指示ファイルはそのまま保持してください。実際のハーネスがサポートする仕組みを使って、識別可能なメモリセクションを 1 つ追加してください。Grok Bot/Muse の場合は、生成された instructions/gbrain-skill.md を使用してください。ファイルを生成しただけでは、有効化された証明にはなりません。

常設の指示には、次の内容を含めてください。

1. 個人的な質問や継続中の作業に関する質問に答える前に、関連する保存済みコンテキストを想起する。
2. 記憶するよう明示的に依頼された内容を、その出所と対象の brain/source とともに保存する。
3. 訂正する前に保存済みの記録を読み、古い事実を無効にし、訂正内容を保存して検証する。
4. アクティブなメモリから削除するには forget を使用する。履歴、ソース資料、バックアップは残る場合がある。
5. 自動的な記録にはオプトインが必要であり、有料の情報拡充と委任にはそれぞれ個別の許可が必要である。
6. 記録されている場合は絶対パスのランチャーを使用する。変更したと主張する内容はすべて、実際の呼び出しで検証する。

ソースはメモリを整理しますが、ローカルファイルや認証情報を共有するエージェントを分離するものではありません。ユーザー固有のメモリとアイデンティティを保持してください。

フェーズ 4：実際に動作することを検証する

選択したガイドのコマンドに従ってください。出所を添えて、ランダムに生成した無害な事実を保存し、返された ID を保持して、別の呼び出しで読み戻してください。その事実を訂正し、テスト用の事実を削除して、アクティブな想起結果に含まれないことを検証してください。変更処理への応答が失われた場合は、再試行する前に状態を照合してください。

診断には gbrain doctor --json を実行してください。オプションのエンベディングが未設定の場合、それは機能が構成されていないということであり、有料のキーを追加する許可ではありません。ヘルススコアやプロセスの正常終了だけでは、メモリの往復処理が成功した証明にはなりません。

ホスト型クライアントでは、非公開の認証情報ファイルを使って gbrain mcp verify を実行してください。トランスポート、認証、権限、読み書き、クリーンアップ、ワーカーの各チェックを個別に報告してください。全体の結果が partial（終了コード 2）の場合、ネイティブな証拠が不足しています。

実際のハーネスで新しい会話を開き、2 つ目のランダムなテスト用事実について、内容を繰り返さずに質問し、記録されたランチャーまたは MCP 呼び出しを確認してください。ハーネスを利用できない場合、このチェックは未検証として扱ってください。テスト用データをクリーンアップし、クリーンアップに失敗した場合は ID とともに報告してください。

オプション機能とメンテナンス

ユーザーが依頼した機能のみを実行してください。

機能	次のステップ
選択したメモまたはチャットのエクスポートをインポートする	選択したソースを確認し、ingest または会話アーカイブに従ってください。任意のディレクトリをスキャンしてインポートしてはいけません。
アカウントを接続する	チャットコネクターまたはGoogle のセットアップに従い、認証情報と同意に関する制限を守ってください。
会話を自動で記録する	オプトイン後にシグナル検出器に従ってください。これを使わなくても、記憶の呼び出しや明示的な記憶は機能します。
有料の検索またはエンリッチメント	選択した機能と予算を個別に設定してください。既存の API キーがあっても、支出が許可されているとは限りません。
スケジュールされたメンテナンス	エージェント内のインストールでは、生成されたルーチン ID と絶対パスのランチャーを再利用し、まず範囲を限定した doctor --fast --json を実行してください。ネイティブの有効化状態を確認してください。ホスト型クライアントでは、ホストの既存のスケジュールを使用します。
選択したファイルソースを同期する	ライブ同期に従ってください。キー不要の同期では --no-pull --no-embed を使用し、暗黙的に埋め込みやワーカーを追加してはいけません。
後からデータをさらにインポートする	オプションの次のステップとしてコールドスタートを案内してください。自動的に開始してはいけません。
アップグレードする	gbrain-upgradeと、インストール時に記録された修復／アップグレードポリシーに従ってください。

事実、修正、ジョブ、会計情報はデータベース内にしか存在しない場合があります。 Git クローンは完全なバックアップではありません。PGLite の場合は、 非公開のバックアップおよび復元手順を使用してください。 アーカイブ全体を機密情報として扱い、VM 外へのコピーには明示的な 保存先の指定が必要です。存在しない新しいルートに復元してから、外部ルート、 コネクター、スケジュールを明示的に再接続してください。

エラーからの復旧

失敗	次のアクション
データベースに接続できない	gbrain engine status --probe を実行し、続けて gbrain db-repair を実行します。許可された修復範囲内で安全な修正を適用してください。
エージェント内のセットアップが不完全	レシートに記載された正確な復旧コマンドを実行し、完了済みのステージとメモリを保持してください。
PGLite が使用中	使用中のプロセスが完了するまで待ってから、再試行してください。使用中のロックを削除してはいけません。
設定が不正、または競合している	競合と意図した対象を報告してください。再初期化したり、無関係な設定を上書きしたりしてはいけません。
ホストへの引き継ぎに失敗	ホスト上で配信を再開してください。アクセストークンの配信失敗とクライアントシークレットの配信失敗を区別してください。
ネイティブの指示またはルーチンを利用できない	内容は維持し、残っている有効化手順を報告してください。
オプションのヘルスチェックを利用できない	不足している機能を明示してください。権限、支出、コネクターへのアクセスを暗黙的に拡大してはいけません。

失敗した場合

gbrain のエラー code、終了コード、[AGENT] ブロック、または通知ブロックについては、エージェント運用プロトコルに従ってください。このスキル固有の内容は次のとおりです。

• gbrain init が検索モードのコストマトリクスを含む [AGENT] ブロックを出力した場合は、その内容を伝え、続行する前にオペレーターの選択を得てください。
• 初期化エラーが発生した場合、復旧のために既存のメモリを置き換えてはいけません。gbrain doctor --json を実行し、その fix に従ってください。
• gbrain mcp verify が全体の状態として partial（終了コード 2）を報告した場合、ネイティブの証拠が不足しています。動作すると断言せず、有効化を検証できていないと伝えてください。

アンチパターン

• 通常のメモリ設定時に、既存のエージェントのアイデンティティを置き換えたり、プライベートリポジトリを作成したりすること。
• 暗黙の設定、利用可能な API キー、またはプローブの成功を、データを取り込んだり費用を発生させたりする許可と見なすこと。
• ヘルススコアを改善するために、キャプチャを自動的に有効にしたり、無関係なファイルをインポートしたり、ワーカーをインストールしたりすること。
• 部分的なインストールを修復するためにメモリを再初期化したり、有効なロックを削除したり、通常の権限付与の修復時に認証情報をローテーションしたりすること。
• 実際に確認していないのに、ネイティブでの有効化や会話をまたいだ想起が完了したと宣言すること。

出力形式

実際のルート／データベース／ソースまたはホストされたエンドポイント、インストール済みバージョン、 メモリのラウンドトリップ、指示の有効化、会話をまたいだ証拠、クリーンアップを報告してください。 保留中の手順と、具体的な修復アクションを明記してください。認証情報は伏せてください。

実際に確認できた段階のみ、完了と宣言してください。CLI テスト、スケジュールファイル、 流暢な回答、HTTP レスポンス、ジョブ ID だけでは、ネイティブな体験全体を証明できません。