# Claude Code

推奨パスとしてスタンドアロンの XMemo Skill を使用し、サポートされている代替手段としてダイレクト MCP を使用して Claude Code を接続します。

- Canonical: https://docs.xmemo.dev/ja/docs/mcp/claude-code
- Locale: ja-JP
- Content-Locale: ja-JP
- Canonical-Content-Digest: 5edeeceeddc0cef8d2d6e339fda7faaccf26ce601200bc11845b78bb698132cd
- Edition-Digest: 2667f5a826766289aa351d32b3c5f36c0f98f8140b2491b6151de8919c8e4646
- Source-Revision: sha256:288082ef3586e3b1f3c2f1a2efb1500c46b876aa3b4c51604bd280c04fc27027

## 前提条件

ローカルターミナルで Claude Code CLI (claude) を使用します。ランタイムと前提条件：

- 具体的なインターフェース: Claude Code CLI (claude)。
- ランタイム要件: スタンドアロン Skill ランナー用の Node.js バージョン 22.22.0 以上。
- アカウント: https://xmemo.dev の有効な XMemo アカウント。
- 代替 MCP の前提条件: ローカル環境でのベアラートークンを使用した Streamable HTTP トランスポートのサポート。

## インストール / セットアップ

推奨されるパスでは、所有者が選択したプロンプトを使用して、スタンドアロンの XMemo Skill を Claude Code の skills ディレクトリにインストールします。Claude Code 内のエージェントにインストールの実行を依頼してください：

- プロンプト: Install the standalone XMemo Skill into your skills directory: run the installer from https://xmemo.dev/skill/install (on Windows, https://xmemo.dev/skill/install.ps1) with XMEMO_SKILL_DIR set to your skills directory plus /xmemo-memory. Run the doctor command it prints to verify the installation, then reload your skills and follow the Skill's first-run steps. Follow your normal safety checks and do not use elevated privileges.
- デフォルトのインストールパス: ~/.claude/skills/xmemo-memory。
- 代替パス: claude mcp add または .mcp.json を介して https://xmemo.dev/mcp を使用してダイレクト Streamable HTTP MCP を登録します。

## 認証情報を設定する

コマンドを実行する前に、認証情報ストレージパスを構成します。シークレットストアまたはローカルシェル環境から XMEMO_KEY を設定することをお勧めします。--allow-plaintext を指定した対話型デバイスログインを使用する場合、このフラグはこのコンピューター上に認証情報を暗号化せずに保存することに注意してください：

```bash
export XMEMO_KEY='<your-xmemo-token>'
# Interactive alternative (stores credential unencrypted on this machine):
# node ~/.claude/skills/xmemo-memory/scripts/xmemo-skill.mjs login --allow-plaintext
```

## XMEMO_AGENT_INSTANCE_ID を生成 / 確認する

ローカルの Claude Code インストールごとに非シークレット値を 1 つ生成し、git の外部に保持して、セッション間で再利用することで、インスタンスの帰属を安定させます。

```bash
export XMEMO_AGENT_INSTANCE_ID='<stable-local-instance-id>'
# Persist and reuse this value for the same local install
```

## 既存の構成ブロックを保持する

ダイレクト MCP 環境の場合は、レビュー済みの Claude Code 構成ブロックを使用します。Authorization 変数参照を保持し、トークンのプレースホルダーを実際のシークレットに置き換えないでください：

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

## クライアントを再起動する

環境変数や構成ファイルを変更した後、または Skill をインストールした後に Claude Code を再起動して、すべてのコンポーネントがメモリに正常に読み込まれるようにします。

## 実際の recall 呼び出しでテストする

データを書き込む前に接続を確認するため、最初のリクエストを読み取り専用にします。このチェックはメモリ状態を変更しません。

```text
recall({ query: "connection check", limit: 1 })
```

## 期待される応答（リテラル形式）

呼び出しが成功すると、以下の公開ランク付けテキスト形式が返されます。参照とコンテンツは、承認されたメモリ空間からの実際の値です。

```text
### XMemo Memory Results:
1. Reference: <opaque-memory-id> | Location: <location>
   > <memory content>
```

## 最初の有用なタスク：合成メモリライフサイクル

メモリの永続化、ステートレスなセッション移行、出所帰属付きリコール、および修正を確認します：

- 1. 合成事実の保存: node scripts/xmemo-skill.mjs remember --content "Demo project timestamps use UTC." --path "projects/demo-onboarding/conventions" (または MCP remember ツール)。
- 2. ステートレス移行: 新鮮な Claude Code ターミナルセッションを開いて、セッション間での永続性を確認します。
- 3. 出所帰属付きリコール: node scripts/xmemo-skill.mjs recall --query "demo project timestamp format" (または MCP recall ツール)。返された出力で Reference と Location を確認します。
- 4. メモリの修正: node scripts/xmemo-skill.mjs update --id <active-memory-id> --content "Demo project timestamps use UTC with ISO 8601 formatting." (または MCP update_memory ツール)。
- 5. オプションのクリーンアップ: node scripts/xmemo-skill.mjs forget --id <active-memory-id> --confirm (または MCP forget ツール)。

## 機能とプロファイルツール

Claude Code は、claude-plugin および claude-public プロファイルの MCP ドキュメント規約で定義されているプロファイル修飾ツールにアクセスできます：

- コアメモリツール: remember, recall, update_memory, forget, read_memory, explain_memory, search_memory, recall_context。
- プロジェクトおよびコンテキストツール: get_mcp_identity, get_project_context, project, todo, update_state。
- セッション継続性: create_restart_snapshot, restore_restart_snapshot, record_event, create_pending_decision, resolve_decision。

## 制限事項と境界

Claude Code の運用上の境界と制約：

- ワークスペース境界: メモリアクセスは承認されたユーザーのワークスペースに厳密に制限されます。
- デスクトップの分離: Claude Code CLI 構成は Claude Desktop Cowork 設定から独立しています。
- claude.ai の Claude と Claude Desktop: カスタムコネクタと OAuth で接続します。[Claude (claude.ai)](/docs/mcp/claude) を参照してください。
- シークレットの処理: 平文トークンを git にコミットしたり、チェックインされた構成ファイルにシークレットを貼り付けたりしないでください。

## よくあるエラー

次の手順で一般的な接続および認証の問題をトラブルシューティングします：

- 401 invalid_token — XMEMO_KEY が欠落、期限切れ、または無効です: 環境トークンを確認するか、デバイスログインを再実行してください。
- 403 insufficient_scope — トークンに memory:read または memory:write スコープがありません: 必要な権限を持つトークンを発行してください。
- 誤ったインストール先 — XMEMO_SKILL_DIR が ~/.claude/skills/xmemo-memory に設定されていることを確認します。
- Skill の再読み込みが必要 — Claude Code を終了 (/exit) して再起動し、メモリ内のスキルを再読み込みします。

## 更新と削除

統合を更新またはアンインストールする手順：

- 更新: インストーラープロンプトを再実行して、最新の Skill パッケージリリースを取得します。
- 削除: ~/.claude/skills/xmemo-memory を削除するか、claude mcp remove xmemo を実行してダイレクト MCP 構成を削除します。

## Claude Desktop

Stdio bridge: Claude Desktop uses mcp-remote to connect to hosted streamable-http with XMEMO_KEY from the environment. Run npx @xmemo/client mcp add claude-desktop to configure automatically.

```
{
  "mcpServers": {
    "XMemo": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://xmemo.dev/mcp",
        "--header",
        "Authorization:Bearer ${XMEMO_KEY}",
        "--header",
        "X-Memory-OS-Agent-ID:claude-desktop",
        "--header",
        "X-Memory-OS-Agent-Instance-ID:${XMEMO_AGENT_INSTANCE_ID}"
      ],
      "env": {
        "XMEMO_AGENT_INSTANCE_ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}
```