Claude Code

Prerequisite

Use Claude Code CLI (claude) in your local terminal. Runtimes and prerequisites:

• Concrete interface: Claude Code CLI (claude).
• Runtime requirement: Node.js version 22.22.0 or higher for the standalone Skill runner.
• Account: Valid XMemo account at https://xmemo.dev.
• Alternative MCP prerequisite: Streamable HTTP transport support with bearer token in local environment.

Install / setup

The recommended path installs the standalone XMemo Skill into Claude Code's skills directory using the owner-selected prompt. Ask your agent in Claude Code 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: ~/.claude/skills/xmemo-memory.
• Alternative path: Register direct Streamable HTTP MCP via claude mcp add or .mcp.json with https://xmemo.dev/mcp.

Set the credential

Before running commands, configure your credential storage path. Prefer setting XMEMO_KEY from a secret store or local shell environment. If using interactive device login with --allow-plaintext, note that this flag stores the credential unencrypted on this computer:

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

Generate / confirm XMEMO_AGENT_INSTANCE_ID

Generate one non-secret value per local Claude Code install, persist it outside git, and reuse it across sessions so instance attribution remains stable.

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

Preserve the existing config block

For direct MCP environments, use the reviewed Claude Code configuration block. Preserve the Authorization variable reference; never replace the token placeholder with a real secret:

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

Restart the client

Restart Claude Code after changing environment variables, configuration files, or installing the Skill so all components load cleanly into memory.

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

Verify memory persistence, stateless session transition, source-attributed 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 Claude Code 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

Claude Code has access to profile-qualified tools defined in the MCP documentation contract for claude-plugin and claude-public profiles:

• Core memory tools: remember, recall, update_memory, forget, read_memory, explain_memory, search_memory, recall_context.
• Project and context tools: get_mcp_identity, get_project_context, project, todo, update_state.
• Session continuity: create_restart_snapshot, restore_restart_snapshot, record_event, create_pending_decision, resolve_decision.

Limitations and boundaries

Operational boundaries and constraints for Claude Code:

• Workspace boundary: Memory access is strictly confined to the authorized user's workspace.
• Desktop separation: Claude Code CLI configuration is independent from Claude Desktop Cowork settings.
• Claude on claude.ai and Claude Desktop: connect through the custom connector with OAuth; see [Claude (claude.ai)](/docs/mcp/claude).
• Secret handling: Never commit plaintext tokens to git or paste secrets into checked-in configuration files.

Common Errors

Troubleshoot common connection and authorization issues with these steps:

• 401 invalid_token — XMEMO_KEY is missing, expired, or invalid: verify environment token or re-run device login.
• 403 insufficient_scope — Token lacks memory:read or memory:write scope: issue a token with required permissions.
• Wrong install target — Verify XMEMO_SKILL_DIR was set to ~/.claude/skills/xmemo-memory.
• Skill reload needed — Exit Claude Code (/exit) and relaunch to reload in-memory skills.

Update and removal

Procedures to update or uninstall the integration:

• Update: Re-run the installer prompt to pull the latest Skill package release.
• Removal: Delete ~/.claude/skills/xmemo-memory, or run claude mcp remove xmemo to remove direct MCP configuration.