# 再開とエージェントハンドオフ

明示的なセッションチェックポイントを記録し、プロジェクトコンテキストを復元し、決定やブロッカーをソース付きで追跡して、スコープクリープなしでエージェント間で作業を引き継ぎます。

- Canonical: https://docs.xmemo.dev/ja/docs/guides/resume-and-handoff
- Locale: ja-JP
- Content-Locale: ja-JP
- Canonical-Content-Digest: f7f1e02f35c3c797c1b7fcc4aee1048fa1f409ef7ed79ecaf362c4d2d5f7b15a
- Edition-Digest: d44e747fe71765390a93ee84bc35c4de93defe5ef28567deaa271e6f44c77d12
- Source-Revision: sha256:dacab21c9fc471e388ff6bbe4a84e7266ffca6eed88baebabcf7f68ee9957d6a

## ユーザーの目標とワークフローの境界

この実践的なワークフローにより、開発者および AI エージェントは、中断されたセッションを再開し、CLI/IDE の再起動をまたいでアクティブなコンテキストを復元し、アーキテクチャの決定、アクティブなブロッカー、またはタスクの継続性を失うことなく、異なるエージェント間 (Claude Code、Codex、Cursor、Hermes など) で進行中の作業を引き継ぐことができます。このワークフローは、無制限の会話履歴を出力したり認証情報を漏洩させたりすることなく、コンテキストのハンドオフが境界付けられた構造化された状態を送信することを保証します。

## 利用資格と前提条件

再開とハンドオフに必要な機能は、明示的な権限境界を持つスタンドアロンの XMemo Skill およびネイティブ MCP クライアントプロファイル全体で公開されます:

- スタンドアロン Skill (Claude Code、Codex、OpenClaw): 提供される 1.1.35 help.mjs からの逐語的 CLI コマンド: save-state および restore-state (88-95行)、restart-snapshot および restart-restore (104-111行)、recall-context (84-87行)、remember (72-75行)、および todo-add/list/done (112-123行)。
- MCP claude-plugin プロファイル: update_state、create_restart_snapshot、restore_restart_snapshot、record_event、recall_context、remember、recall、todo、create_pending_decision、および resolve_decision を含みます。
- MCP cursor-plugin および ordinary-full プロファイル: update_state、create_restart_snapshot、restore_restart_snapshot、record_event、recall_context、remember、recall、update_project_decision、update_project_todo、list_memory_todos、complete_memory_todo、および query_audit を含みます。
- MCP generic-public、chatgpt-public、および public-only プロファイル: get_project_summary(project_id, focus) や memory_overview などの読み取り専用サマリープロジェクションを公開します。書き込みツールには認証済みプラグインセッションが必要です。
- 前提条件: チェックポイントの永続化用の memory:write スコープおよびコンテキスト取得用の memory:read を備えたアクティブな認証トークン (XMEMO_KEY またはローカルの skill-credentials.json)。

## 1 つの完全なタスク: 合成マルチエージェントハンドオフ

この合成シナリオでは、Agent Alpha (Claude Code CLI で実行) がプロジェクト proj_payments_v2 でのデータベース接続プーリングのリファクタリングに取り組み、明示的な決定とブロッカーを記録し、再起動スナップショット (restart snapshot) を封印して、Agent Beta (Cursor IDE で実行) に実行を引き継ぎます。

## アクティブな状態とブロッカーを記録する

Agent Alpha は、ハンドオフの前に save-state または update_state を使用して現在のタスクとアクティブなブロッカーを記録します:

```bash
node scripts/xmemo-skill.mjs save-state --key active_task --content "Refactoring database connection pooling to asyncpg: blocked on internal CA bundle" --ttl_seconds 86400
```

## 継続性のための再起動スナップショットを作成する

Agent Alpha は、ハンドオフの前に restart-snapshot または create_restart_snapshot を使用して完全なセッション継続性パッケージをキャプチャします:

```bash
node scripts/xmemo-skill.mjs restart-snapshot --state_key active_task --session_id sess_alpha_0928 --ttl_seconds 604800
```

## 受信エージェントセッションで再開および復元する

Agent Beta は Cursor IDE で起動し、スナップショットを復元して、境界付けられたバックグラウンドコンテキストを取得します:

```bash
node scripts/xmemo-skill.mjs restart-restore --source_session_id sess_alpha_0928 --target_session_id sess_beta_0929
node scripts/xmemo-skill.mjs recall-context --query "internal CA bundle TLS root pin database pooling" --max_items 5 --max_tokens 2000
```

## 観察可能な結果

ハンドオフが成功すると、会話上の装飾なしにツール応答内に明示的で検証可能な確認が生成されます:

- スナップショット作成出力: create_restart_snapshot は次を返します: "✅ Restart snapshot created. ID: snap_xxx Captured: state=1, events=1, reminders=0, decisions=1"。
- 復元レシート: restore_restart_snapshot はアクティブな状態スロットを復元し、target_session_id の下に監査復元イベントを記録し、復元された正確な状態コンテンツとブロッカーの理由を返します。
- コンテキストの根拠付け: recall_context は、ソースの session_id、agent_id、および正確な作成タイムスタンプでタグ付けされた構造化メモリ項目を返し、Agent Beta が決定のソースを即座に確認できるようにします。

## エージェントがアクセスできるもの

セッション間のコンテキストアクセスは、認可されたスコープと来歴によって厳格に境界付けられます:

- 境界付けられたメモリコンテキスト: 復元するエージェントは、クエリに一致する構造化された状態スロット、タイムラインのマイルストーン、および明示的に取得されたメモリを受け取ります。無関係な開発者メモリや無関係なプロジェクトは受け取りません。
- 自分の書き込みを読み取る一貫性 (Read-Your-Writes): 状態の更新と再起動スナップショットはトランザクションメタデータストアに即座に書き込まれ、ハンドオフエージェント間の結果整合性による競合状態を防ぎます。
- 呼び出し元の来歴: 取得されたコンテキストには呼び出し元 ID (source_identity、agent_id、および node_id) が含まれるため、後続のエージェントは人間のユーザーの指示と自動化されたピアエージェントの提案を区別できます。

## 共有とストレージの境界

すべての再開およびハンドオフ操作には、厳格なプライバシーおよびセキュリティ分離ルールが適用されます:

- 生のトランスクリプトダンプの禁止: チャットの全トランスクリプトやモデルの思考トレースを状態やメモリに保存してはいけません。ハンドオフでは、構造化された状態の要約、明示的な決定イベント、および検証された事実のみを送信します。
- 認証情報漏洩のゼロ化: トークン、API キー、パスワード、および認可ヘッダーを state_key、content、または metadata_json に書き込んではいけません。
- プロジェクト分離境界: project:proj_payments_v2 にバインドされたスナップショットは、明示的なチーム権限がない限り、異なるプロジェクトまたは個人スコープで認証されたセッションからは一切アクセスできません。

## 障害回復

決定論的なフォールバック戦略を使用して、一般的な再開およびハンドオフのエラーを処理します:

- 期限切れのスナップショットまたは TTL: スナップショットが ttl_seconds (スナップショットの場合はデフォルトで 7 日間、アクティブな状態の場合は 24 時間) を超えた場合、restore_restart_snapshot はスナップショットの期限切れを報告します。get_project_context(project_id="proj_payments_v2") またはプロジェクトスコープのクエリを使用した recall_context にフォールバックします。
- セッション ID の欠落: source_session_id が利用できないか失われた場合は、node scripts/xmemo-skill.mjs restore-state --key active_task を使用して最新の状態レコードを復元するか、todo-list を使用してアクティブな TODO を一覧表示します。
- スコープまたはテナントの不一致: エージェントが未承認のテナントまたは一致しないプロジェクトスコープ間でスナップショットを復元しようとすると、サーバーは HTTP 403 Forbidden でリクエストを拒否します。クライアント構成でバインドされたプロジェクト ID を確認してください。

## 関連リファレンス

関連するアーキテクチャ、スコープの定義、およびツールカタログについては、以下のガイドを参照してください:

- エージェント間ワークフロー: オーケストレーションの概念については /docs/operations/cross-agent-workflow を参照してください。
- スコープと分離: 4 層の直交スコープ階層については /docs/concepts/scopes を参照してください。
- プロジェクトワークスペース: プロジェクトの関連付けと境界の強制については /docs/concepts/projects を参照してください。
- クイックスタート: クライアント構成と初期認証については /docs/quickstart を参照してください。
- MCP ツールリファレンス: 低レベルのツールパラメータについては /docs/tools/recall-context および /docs/tools/remember を参照してください。

## ChatGPT ユーザー

bearer token をチャットに貼り付けずに、ChatGPT が XMemo の設定、プロジェクト事実、意思決定、TODO に永続的にアクセスできるようにします。

ChatGPT/OpenAI app の OAuth フローで hosted XMemo MCP server に接続し、XMemo アカウントに memory:read と memory:write の許可を承認します。

合成の設定またはプロジェクトメモを保存し、新しいチャットを開始してから、作業を続ける前に ChatGPT に XMemo 経由でそれを呼び出させます。

OAuth が失敗する、またはツールが表示されない場合は、direct token を作成する前に、ホストアプリで MCP server からサインアウトし、XMemo server URL を再接続して再試行します。

## Copilot / Codex 開発者

リポジトリの判断、コーディング規約、バグ修正メモ、タスク履歴を IDE と CLI エージェント間で持ち運べます。

利用可能な場合は、VS Code / GitHub Copilot および Gemini CLI に OAuth を使用してください。Copilot CLI、Codex、Cursor、またはその他の直接 MCP クライアントの場合は、XMEMO_KEY をローカル環境またはシークレットストアに保持し、安定した XMEMO_AGENT_INSTANCE_ID を設定してください。

コードベースの判断またはバグ修正を記録し、次の IDE または CLI エージェントに、編集前に関連する XMemo コンテキストを呼び出させます。

呼び出し結果が空の場合は、選択した MCP 設定パス、direct client 用の XMEMO_KEY 環境変数、ホストアプリ内の古い OAuth 認証情報を確認します。

## チーム / エンタープライズ pilot owner

アカウント制御、ソース attribution、エクスポート/削除ワークフロー、レビュー担当者向けに安全な設定証跡で共有メモリを評価します。

保護された XMemo workspace を作成または開き、承認済みユーザーを招待してから、readiness badges に従って OAuth またはスコープ付き direct credential で各クライアントを接続します。

pilot メンバーに合成のチームメモリを保存してもらい、XMemo でソース attribution を確認し、削除/エクスポートとサポート経路をレビューします。

メンバーが接続できない場合は、新しい token を発行する前に、ロール権限、OAuth 承認、クライアント readiness 状態、サポートガイダンスを確認します。

## 自律エージェント operator

headless またはスケジュール済みエージェントが進捗を記録し、過去の判断を取得し、安定した非秘密のインスタンス ID を保持できるようにします。

/api/v1/mcp/config/autonomous-agent を取得します。runner が OAuth + custom headers をサポートする場合は auth_modes.oauth を優先し、完全 headless runner の場合のみ secret store の XMEMO_KEY で auth_modes.xmemo_key を使います。

XMemo に進捗を書き込む合成タスクを 1 つ実行し、runner を再起動して、同じ XMEMO_AGENT_INSTANCE_ID でその進捗を呼び出せることを確認します。

attribution が変わる、または呼び出し結果がインスタンス間で分かれる場合は、XMEMO_AGENT_INSTANCE_ID を git の外に永続化し、runner が起動ごとに再生成していないことを確認します。