# クイックスタート

1 つのクライアントを接続し、有用なコンテキストを保存し、後でリコールし、認証情報を公開構成から除外します。

- Canonical: https://docs.xmemo.dev/ja/docs/quickstart
- Locale: ja-JP
- Content-Locale: ja-JP
- Canonical-Content-Digest: abd73d03ccf55170c5c85c4eb326e77c66fde0b1654ec463e46bfe8613eed6fd
- Edition-Digest: ebc0e714d86df7e968b092f90b155c710095c5c76e780c3546ac4d0571eb89c5
- Source-Revision: sha256:cf650121954b22e4cd8c386342083e6a3a903c519472bb4b370f9e3c03b0c8b8

## 1. クライアントと認証モードの選択

エージェントクライアントと希望する接続パスを選択します。Claude Code、Codex、および互換性のあるエージェントの場合は、「エージェントに依頼する」を指定してスタンドアロンの Skill インストーラーを使用します。ChatGPT などのスキルのないクライアントの場合は、OAuth 経由のホスト型 MCP を使用します。Cursor や VS Code などの直接実行またはヘッドレスランナーの場合は、XMEMO_KEY を使用した Direct MCP を使用します。専用のクライアントガイドは、/docs/mcp/claude-code、/docs/mcp/codex、/docs/connect/openclaw、/docs/mcp/chatgpt、/docs/mcp/cursor、および /docs/mcp/copilot で入手できます。

- パス 1 (Skill): Claude Code、Codex、および OpenClaw (/docs/connect/openclaw) 用のスタンドアロン XMemo Skill をインストールするようエージェントに依頼します。
- パス 2 (OAuth MCP): ChatGPT (/docs/mcp/chatgpt) や Claude Desktop (/docs/mcp/overview) を含む、スキルのないクライアント向けの OAuth 経由のホスト型 MCP。
- パス 3 (Direct MCP): Cursor (/docs/mcp/cursor) および VS Code (/docs/mcp/copilot) 向けに、ローカル環境の ${XMEMO_KEY} を参照する Direct Streamable HTTP MCP。
- 認証モード: OAuth (推奨、ブラウザ承認) と Direct MCP (環境変数 XMEMO_KEY)。
- 中間ステータス: クライアントを選択して構成をコピーすることは中間ステップであり、アクティベーションではありません。

## 2. トークンを公開せずにクライアントを設定

スタンドアロン Skill をインストールするか、ホストされた MCP エンドポイント (https://xmemo.dev/mcp) を使用してクライアントを構成します。Skill クライアントの場合は、公式のインストールプロンプトをプライマリコピーアクションとしてエージェントに提供するか、正規のインストーラーを手動で実行します。Direct MCP の場合は、ローカル環境またはシークレットストアから ${XMEMO_KEY} を参照します。プレーンテキストのベアラートークンをクライアント構成ファイルやバージョン管理にハードコードしないでください。

- パス 1 (エージェントに依頼): スタンドアロン XMemo Skill をスキルディレクトリにインストールします。https://xmemo.dev/skill/install (Windows では https://xmemo.dev/skill/install.ps1) からインストーラーを実行し、XMEMO_SKILL_DIR をスキルディレクトリ + /xmemo-memory に設定します。出力される doctor コマンドを実行してインストールを確認し、スキルをリロードして Skill の初回実行手順に従います。通常の安全性チェックに従い、昇格した権限は使用しないでください。
- 手動コピーのフォールバック: XMEMO_SKILL_DIR を明示的に設定して 'curl -fsSL https://xmemo.dev/skill/install | sh' (Windows PowerShell: 'irm https://xmemo.dev/skill/install.ps1 | iex') を実行します。
- OAuth クライアント: https://xmemo.dev/mcp を構成し、ブラウザで memory:read と memory:write を承認します。
- Direct MCP: 構成内で ${XMEMO_KEY} を参照します。実際のトークンはローカル環境またはシークレットストアに保持します。
- シークレットゼロ: 構成ファイルに暗号化されていないベアラートークンを含めることはできません。

```json
{
  "mcpServers": {
    "XMemo": {
      "type": "http",
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${XMEMO_KEY}"
      }
    }
  }
}
```

## 3. 読み取り専用チェックで接続を確認

データを書き込む前に、必ず読み取り専用リクエストで接続を確認してください。インストール、認証、およびアクティベーションはそれぞれ異なるマイルストーンです。スタンドアロン Skill の場合は、インストーラーによって出力された doctor コマンドを実行します。サインインする前に、認証情報のパスを選択します。シークレットストアから XMEMO_KEY を提供するか、管理された認証情報を使用することを推奨します。--allow-plaintext を使用した対話型デバイスログインを使用する場合、このフラグは認証情報を暗号化せずにこのコンピュータに保存することに注意してください。認証後にステータスを確認します。MCP クライアントの場合、get_mcp_identity はクライアントがサーバーに到達でき、memory:read スコープが有効であることを確認します。

- Skill doctor コマンド: node scripts/xmemo-skill.mjs doctor --anonymous (ランタイムと接続を確認)。
- Skill 認証情報の代替手段: シークレットストアから XMEMO_KEY を提供するか、管理された認証情報を使用します。
- Skill デバイスログイン: node scripts/xmemo-skill.mjs login --allow-plaintext (ブラウザ検証を開きます。--allow-plaintext は認証情報を暗号化せずにこのコンピュータに保存することに注意してください)。
- Skill 認証検証: node scripts/xmemo-skill.mjs auth status --verify (認証情報の有効性を確認)。
- MCP ツール: get_mcp_identity() (または制限 1 の recall)。
- スコープゲート: memory:read。
- 成功シグナル: アイデンティティメタデータによって、サーバーが到達可能であり認証されていることが確認されます。

```ts
get_mcp_identity()
```

## 4. 明示的な合成事実を保存

合成プロジェクト規約を記録して、memory:write での書き込み機能を確認します。その後のクエリがプロジェクトスコープ内でそれを見つけられるように、メモリに特定のパスを指定します。統合サーフェスに適した構文を使用してください。

- Skill コマンド: node scripts/xmemo-skill.mjs remember --content "Demo project timestamps use UTC." --path "projects/demo-onboarding/conventions"。
- MCP ツール: 明示的な合成コンテンツを含む remember。
- パススコープ: projects/demo-onboarding/conventions。
- 成功シグナル: レシートは、割り当てられた ID と Location と共に 'Saved to XMemo.' で始まります。

```ts
remember({
  content: "Demo project timestamps use UTC.",
  path: "projects/demo-onboarding/conventions"
})
```

## 5. 新しいクライアントセッションを開く

新しい会話スレッドを開始するかクライアントを再起動して、メモリ内の一時的なコンテキストをクリアします。このステートレスな移行により、次のリコールでローカルチャット履歴の再生ではなくサーバー側の永続性が検証されるようになります。

- アクション: クライアントで現在のチャットセッションを閉じるかリセットします。
- コンテキストのリセット: ステートレスなテストを保証するために、一時的なクライアントコンテキストがクリアされます。
- 永続性の検証: その後のリコールはリモートストアに直接クエリを実行します。

## 6. ソース帰属付きで事実をリコール

新しいセッションから保存された規約をクエリします。アクティベーションは、ソース帰属を伴う最初の検証済みメモリリコールを完了することとして厳密に定義されています。構成のコピーやスニペットの確認はセットアップの中間ステップにすぎません。

- Skill コマンド: node scripts/xmemo-skill.mjs recall --query "demo project timestamp format" --limit 1。
- MCP ツール: クエリ 'demo project timestamp format' を指定した recall。
- レシート形式: Reference、Location、任意の Created/Updated/Revision、およびコンテンツを示す '### XMemo Memory Results:' で始まるテキスト出力。
- 成功シグナル: ソース帰属を伴う最初の検証済みリコールが真のアクティベーションを示します。

```ts
recall({
  query: "demo project timestamp format",
  limit: 1
})
```

## 7. update_memory で規則を修正

プロジェクト規約が進化したり明確化が必要になった場合は、リコールから返された正確なアクティブメモリ ID または Reference でメモリを更新します。Skill クライアントの場合は update コマンドを使用します。MCP クライアントの場合は update_memory を使用します。オプションのクリーンアップは forget を介してユーザーが直接指示します。

- Skill コマンド: node scripts/xmemo-skill.mjs update --id "mem_01hxyz..." --content "Demo project timestamps use UTC with ISO 8601 formatting."。
- MCP ツール: 有効な memory_id を指定した update_memory。
- リビジョントレイル: 不変の履歴を保持しながら以前のリビジョンを置き換えます。
- オプションのクリーンアップ: 削除するには、'node scripts/xmemo-skill.mjs forget --id mem_01hxyz... --confirm' (Skill) を実行するか、forget (MCP) を呼び出します。
- 成功シグナル: レシートは Reference と Revision を示す 'XMemo memory updated.' で始まります。

```ts
update_memory({
  memory_id: "mem_01hxyz...",
  content: "Demo project timestamps use UTC with ISO 8601 formatting."
})
```

## 復旧：クリップボードへのアクセスが拒否されました

ブラウザがクリップボードへのアクセスを拒否したり権限がブロックされたりした場合は、コードブロック内のスニペットテキストを手動で選択し、Ctrl+C (または Cmd+C) でコピーします。すべてのコードブロックにはキーボードスクロールと選択用の tabIndex=0 が用意されています。

- 症状: ブラウザが自動クリップボードコピーをブロックするか、権限プロンプトが失敗します。
- アクション: コードコンテナをクリックまたはタブ移動して選択し、Ctrl+C または Cmd+C を使用します。
- 検証: 貼り付けられた構成が表示されたスニペットと正確に一致します。

## 復旧：認証の期限切れまたは権限不足

クライアントが HTTP 401 Unauthorized、HTTP 403 Forbidden、または SetupRequiredMCPError を受信した場合、認証トークンの有効期限が切れているか、必要なスコープが不足しています。

- 症状: ツール呼び出し時の HTTP 401、HTTP 403、または SetupRequiredMCPError。
- アクション: OAuth 経由で再認証するか、ローカル環境で XMEMO_KEY を設定します。
- 検証: トークンが memory:read と memory:write の両方のスコープを付与していることを確認します。

## 復旧：クライアントにツールが表示されない

構成後に XMemo ツールがクライアントパレットに表示されない場合、構成ファイルに構文エラーが含まれているか、MCP 接続プロセスの再起動が必要な可能性があります。

- 症状: クライアントに 0 個のツールが表示されるか、XMemo MCP サーバーの認識に失敗します。
- アクション: クライアント開発者ログを確認し、JSON 構文を検証して、クライアントを再起動します。
- 検証: クライアントログに MCP の初期化とツールの検出が成功したことが示されます。

## 復旧：リコール結果が空

recall が一致するメモリを返さない場合 ('No matching memories found' または 'No strong memory match')、ステップ 4 の書き込みが正常に完了したことを確認し、検索クエリを確認してください。

- 症状: recall は、一致するメモリが見つからなかったことを示すテキストメッセージを返します。
- アクション: クエリキーワード ('timestamp'、'UTC') を確認し、パススコープを確認します。
- 検証: リコールする前に、remember が 'Saved to XMemo' で始まるレシートを返したことを確認します。

## 復旧：更新時の不明なメモリ ID

memory_id が不明または無効であるために update_memory が呼び出しを拒否した場合、識別子を推測しないでください。

- 症状: update_memory は、memory_id が見つからないことを示すエラーを返します。
- アクション: 最初に recall を呼び出してアクティブなメモリ Reference を取得し、それを memory_id として渡します。
- 検証: recall からのアクティブなメモリ Reference を update_memory に渡します。

## 復旧：誤ったインストール先

インストーラーがスクリプトを隔離されたスキルサブディレクトリではなくエージェントのスキルルートディレクトリに直接保存した場合、エージェントは scripts/xmemo-skill.mjs を見つけることができないか、未処理のインストールファイルを読み込みます。

- 症状: scripts/xmemo-skill.mjs の検索エラー、またはファイルがスキルルートに直接抽出されます。
- アクション: XMEMO_SKILL_DIR をスキルディレクトリ + /xmemo-memory に明示的に設定します (例: export XMEMO_SKILL_DIR="$HOME/.claude/skills/xmemo-memory")。
- 検証: SKILL.md と scripts/xmemo-skill.mjs が xmemo-memory フォルダの直下に存在します。

## 復旧：Node 22.22.0 ランタイムが見つかりません

スタンドアロン Skill には Node.js >= 22.22.0 が必要です。node が見つからないか古いバージョンがアクティブな場合、doctor およびスキル操作は失敗します。

- 症状: 'command not found: node'、起動時のランタイムエラー、または node -v が 22.22.0 未満のバージョンを報告します。
- アクション: nvm (nvm install 22.22.0 && nvm use 22.22.0) またはオペレーティングシステムのパッケージマネージャーを使用して、Node.js 22.22.0 以上をインストールまたは切り替えます。
- 検証: 'node -v' を実行し、出力が v22.22.0 以上であることを確認します。

## 復旧：Skill のリロードが必要です

Skill がインストールされ doctor に合格したにもかかわらず、エージェントのアクティブセッションに XMemo ツールまたは操作が一覧表示されない場合は、エージェントのメモリ内スキルキャッシュを再ロードする必要があります。

- 症状: インストール後、エージェントが XMemo スキルについての知識がないことを報告します。
- アクション: エージェントセッションを再起動して、メモリ内スキルを再ロードします。
- 検証: エージェントに「what skills are available?」と尋ね、xmemo-memory がリストされていることを確認します。

## 復旧：ログインが中断されました

デバイスログインが中断されたか、タイムアウトしたか、確認コードを入力する前に閉じられた場合、認証情報はディスクに書き込まれません。

- 症状: 承認前にブラウザが閉じられたか、ワンタイムコードが期限切れになったか、または 'auth status --verify' が auth_valid: false を報告します。
- アクション: シークレットストアの XMEMO_KEY や管理された認証情報を使用していない場合は、'node scripts/xmemo-skill.mjs login --allow-plaintext' (認証情報を暗号化せずにこのコンピュータに保存します) を再実行し、表示された URL を開いて期限切れ前にコードを入力します。
- 検証: 'node scripts/xmemo-skill.mjs auth status --verify' を実行し、'auth_valid: true' と共に 'status: ok' を確認します。

## ホステッド XMemo クイックスタート

まず管理型 XMemo サービスと以下の接続パスから始めます。セルフホスト、Docker、Supabase、Python パッケージのセットアップは開発者向け参考資料であり、ホステッドユーザーの最初の導線ではありません。

### エージェントに依頼

通常の安全確認に従う信頼できるエージェントに貼り付けてください。

```
スタンドアロン XMemo Skill をスキルディレクトリにインストールします: https://xmemo.dev/skill/install (Windows では https://xmemo.dev/skill/install.ps1) からインストーラーを実行し、XMEMO_SKILL_DIR をスキルディレクトリ + /xmemo-memory に設定します。出力される doctor コマンドを実行してインストールを確認し、スキルを再読み込みして Skill の初期設定手順に従ってください。通常の安全確認に従い、管理者権限は使用しないでください。
```

### OAuth クライアント

ホストが OAuth に対応している場合、ChatGPT、OpenAI アプリレビュー、VS Code、GitHub Copilot ではこのパスを使います。ホステッド MCP URL を追加し、memory:read と memory:write を承認し、XMEMO_KEY をクライアント設定に貼り付けないでください。

```
MCP URL: https://xmemo.dev/mcp
Scopes: memory:read memory:write
```

### XMEMO_KEY を使う直接 MCP

OAuth を完了できないクライアントまたはヘッドレスランナーでのみこのパスを使います。XMEMO_KEY はローカル環境またはシークレットストアに保存し、設定にはホステッド MCP URL を残し、実トークンを公開ドキュメントやチャットへ貼り付けないでください。

```
MCP URL: https://xmemo.dev/mcp
Token source: XMEMO_KEY environment variable
Optional identity: XMEMO_AGENT_INSTANCE_ID
```

### アカウント管理

初回接続後はアカウント入口で保存内容を確認し、エージェント帰属をチェックし、パイロット拡大前に削除・エクスポートやサポートの導線を確認します。

```
Account entry: https://xmemo.dev/login
```