Codex

Prerequisite

Use OpenAI Codex CLI or Codex Desktop with Streamable HTTP MCP and Skill execution support:

• Concrete interface: Codex CLI and Codex Desktop (codex).
• Runtime requirement: Node.js version 22.22.0 or higher for the standalone Skill runner.
• Account: Valid XMemo account at https://xmemo.dev.
• MCP prerequisite: Support for bearer_token_env_var in ~/.codex/config.toml.

Install / setup

The recommended path installs the standalone XMemo Skill into Codex's skills directory using the owner-selected prompt. Ask your agent in Codex to execute the installation:

• Prompt: 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.
• Default installation path: ~/.codex/skills/xmemo-memory.
• Alternative path: Configure the direct MCP profile in ~/.codex/config.toml using bearer_token_env_var.

Set the credential

Configure your credential before running operations. Set XMEMO_KEY in the environment used to launch Codex. bearer_token_env_var reads the value without putting the token in config.toml. If using interactive device login with --allow-plaintext, note that this flag stores credentials unencrypted on this computer:

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

Generate / confirm XMEMO_AGENT_INSTANCE_ID

The client configuration maps the stable instance identity for this install. Confirm that env_http_headers maps XMEMO_AGENT_INSTANCE_ID and reuse the same non-secret value across sessions.

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

Preserve the existing config block

Use the reviewed Codex configuration block. Preserve bearer_token_env_var and the XMemo URL; never paste secrets directly into config.toml:

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

Restart the client

Restart Codex after writing configuration files, modifying environment variables, or installing the Skill so the new components are detected.

Test with a real recall call

Make the first request read-only to verify connectivity before writing data. This check does not modify memory state.

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

Expected response (literal shape)

A successful call returns the public ranked text shape below; the reference and content are real values from the authorized memory space.

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

First useful task: Synthetic memory lifecycle

Exercise the complete synthetic memory task across saving, session transition, recall, and correction:

• 1. Save synthetic fact: node scripts/xmemo-skill.mjs remember --content "Demo project timestamps use UTC." --path "projects/demo-onboarding/conventions" (or MCP remember tool).
• 2. Stateless transition: Open a fresh Codex terminal session to verify persistence across sessions.
• 3. Recall with source attribution: node scripts/xmemo-skill.mjs recall --query "demo project timestamp format" (or MCP recall tool). Verify Reference and Location in returned output.
• 4. Correct memory: node scripts/xmemo-skill.mjs update --id <active-memory-id> --content "Demo project timestamps use UTC with ISO 8601 formatting." (or MCP update_memory tool).
• 5. Optional cleanup: node scripts/xmemo-skill.mjs forget --id <active-memory-id> --confirm (or MCP forget tool).

Capabilities and profile tools

Codex has access to profile-qualified tools defined in the MCP documentation contract for generic-public profile:

• Core memory tools: remember, recall, update_memory, forget, read_memory, explain_memory, search_memory, recall_context.
• Workspace tools: get_mcp_identity, get_project_summary, project, todo, open_project_workspace, open_todo_board, ledger, open_ledger.

Limitations and boundaries

Operational boundaries and constraints for Codex:

• Workspace isolation: Operations are strictly confined to the signed-in user's workspace.
• Secret handling: Always use bearer_token_env_var; never hardcode tokens in config.toml.
• Distribution scope: Non-standard or third-party forks of Codex remain marked untested.

Common Errors

Troubleshoot common Codex issues using these recovery steps:

• 401 invalid_token — XMEMO_KEY is missing, expired, or invalid: verify the environment launching Codex and restart.
• 403 insufficient_scope — Token lacks memory:read permission: generate a token with the required scope.
• Wrong install target — Verify XMEMO_SKILL_DIR was set to ~/.codex/skills/xmemo-memory.
• Skill reload needed — Restart Codex to ensure in-memory skills reload.

Update and removal

Maintenance procedures for Codex:

• Update: Re-run the installer command to pull the latest Skill release, or update the MCP endpoint URL.
• Removal: Delete the ~/.codex/skills/xmemo-memory directory, or remove [mcp_servers.xmemo] from ~/.codex/config.toml.