# Codex

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

- Canonical: https://docs.xmemo.dev/ja/docs/mcp/codex
- Locale: ja-JP
- Content-Locale: ja-JP
- Canonical-Content-Digest: 509a4d640bcac1076020015dcc2e3ca09db14ea5c7d405058a07ddf2bdd426b6
- Edition-Digest: e6cb4fa235ee8791d4bd351777304763fac5035057f9c6dee9926d176c6d55cc
- Source-Revision: sha256:99af2f1e8dcd76b03aa4019faeb9d18995ed91ee2d0633430737af760cbcfdbf

## 前提条件

Streamable HTTP MCP および Skill 実行サポートを備えた OpenAI Codex CLI または Codex Desktop を使用します：

- 具体的なインターフェース: Codex CLI および Codex Desktop (codex)。
- ランタイム要件: スタンドアロン Skill ランナー用の Node.js バージョン 22.22.0 以上。
- アカウント: https://xmemo.dev の有効な XMemo アカウント。
- MCP の前提条件: ~/.codex/config.toml での bearer_token_env_var のサポート。

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

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

- プロンプト: 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.
- デフォルトのインストールパス: ~/.codex/skills/xmemo-memory。
- 代替パス: bearer_token_env_var を使用して ~/.codex/config.toml でダイレクト MCP プロファイルを構成します。

## 認証情報を設定する

操作を実行する前に認証情報を構成します。Codex の起動に使用する環境で XMEMO_KEY を設定します。bearer_token_env_var は config.toml にトークンを配置せずに値を読み取ります。--allow-plaintext を指定した対話型デバイスログインを使用する場合、このフラグはこのコンピューター上に認証情報を暗号化せずに保存することに注意してください：

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

## XMEMO_AGENT_INSTANCE_ID を生成 / 確認する

クライアント構成は、このインストール用の安定したインスタンス ID をマップします。env_http_headers が XMEMO_AGENT_INSTANCE_ID をマップしていることを確認し、セッション間で同じ非シークレット値を再利用します。

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

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

レビュー済みの Codex 構成ブロックを使用します。bearer_token_env_var と XMemo URL を保持し、シークレットを config.toml に直接貼り付けないでください：

```toml
[mcp_servers.xmemo]
url = "https://xmemo.dev/mcp"
bearer_token_env_var = "XMEMO_KEY"
```

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

構成ファイルの書き込み、環境変数の変更、または Skill のインストール後に Codex を再起動して、新しいコンポーネントが検出されるようにします。

## 実際の 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. ステートレス移行: 新鮮な Codex ターミナルセッションを開いて、セッション間での永続性を確認します。
- 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 ツール)。

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

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

- コアメモリツール: remember, recall, update_memory, forget, read_memory, explain_memory, search_memory, recall_context。
- ワークスペースツール: get_mcp_identity, get_project_summary, project, todo, open_project_workspace, open_todo_board, ledger, open_ledger。

## 制限事項と境界

Codex の運用上の境界と制約：

- ワークスペースの分離: 操作はサインインしたユーザーのワークスペースに厳密に制限されます。
- シークレットの処理: 常に bearer_token_env_var を使用してください。config.toml にトークンをハードコードしないでください。
- 配布範囲: Codex の非標準またはサードパーティのフォークは未テストとしてマークされたままになります。

## よくあるエラー

次のリカバリ手順を使用して、Codex の一般的な問題をトラブルシューティングします：

- 401 invalid_token — XMEMO_KEY が欠落、期限切れ、または無効です: Codex を起動する環境を確認して再起動します。
- 403 insufficient_scope — トークンに memory:read 権限がありません: 必要なスコープを持つトークンを生成します。
- 誤ったインストール先 — XMEMO_SKILL_DIR が ~/.codex/skills/xmemo-memory に設定されていることを確認します。
- Skill の再読み込みが必要 — Codex を再起動して、メモリ内のスキルが確実に再読み込みされるようにします。

## 更新と削除

Codex のメンテナンス手順：

- 更新: インストーラーコマンドを再実行して最新の Skill リリースを取得するか、MCP エンドポイント URL を更新します。
- 削除: ~/.codex/skills/xmemo-memory ディレクトリを削除するか、~/.codex/config.toml から [mcp_servers.xmemo] を削除します。

## Codex

Direct client: Codex reads XMEMO_KEY through bearer_token_env_var and sends non-secret identity headers. Run npx @xmemo/client mcp add codex --write to generate the stable XMEMO_AGENT_INSTANCE_ID automatically.

```
[mcp_servers.XMemo]
url = "https://xmemo.dev/mcp"
bearer_token_env_var = "XMEMO_KEY"

[mcp_servers.XMemo.http_headers]
X-Memory-OS-Agent-ID = "codex"

[mcp_servers.XMemo.env_http_headers]
X-Memory-OS-Agent-Instance-ID = "XMEMO_AGENT_INSTANCE_ID"

```