# Claude Code

Configure the direct MCP path with XMEMO_KEY from a local environment or supported secret store.

- Canonical: https://docs.xmemo.dev/docs/mcp/claude-code
- Locale: en-US
- Content-Locale: en-US
- Canonical-Content-Digest: e8bd7e3d1916dc07db3fc023bdbb024e7a6ab6523a959ea3edc2dc1bc30c33cd
- Edition-Digest: 5d1519ebcf856627066b2a34f5fba62ad977616e4f4e8de9a711738908f696f9
- Source-Revision: sha256:2903abfa64f7df438edf67c2acfc24028cd4975dc499eca630db33c965227d14

## Prerequisite

Use a Claude Code MCP setup that supports hosted Streamable HTTP and a bearer token from a local environment or supported secret store.

- Endpoint: https://xmemo.dev/mcp.
- Auth mode: direct MCP with a bearer token.
- Token source: XMEMO_KEY.

## Two distinct Claude integration surfaces

XMemo offers host-native and remote connection modes for Claude runtimes:

- Claude Code (CLI): Host-native execution via local configuration or direct streamable-http MCP connection.
- Claude Desktop & Cowork: Connect to the hosted XMemo endpoint through native client configuration.
- Cross-runtime continuity: Seamless memory sharing between Claude Code CLI and desktop workspaces powered by XMemo.

## Representative Claude workflows

Focused workflows turn live project evidence into durable, retrieval-ready outcomes:

- Recall & Context: Retrieve past decisions and context before making substantial modifications.
- Decisions & Planning: Align on approved architecture and record milestones.
- Session Continuity: Preserve progress and pending tasks across sessions and agent environments.
- Audit & Ledger: Review logged operations and monthly resource summaries when requested.

## Install / setup

Register the hosted server through the reviewed Claude Code setup path: /v1/mcp/config/claude-code, .mcp.json, or claude mcp add. Keep the generated or checked-in configuration shape unchanged.

- Use the hosted MCP URL, not a local stdio substitute.
- Keep the bearer value in the environment or secret store.
- Use the existing XMemo block rendered on this page.

## Permissions and data boundaries

XMemo requests memory:read and memory:write scopes. All memory changes generated within Claude remain strictly bounded inside the authenticated user's isolated XMemo workspace.

## Set the credential

Set XMEMO_KEY before starting Claude Code. Store the real token outside the repository and reference the variable from the MCP configuration.

```bash
export XMEMO_KEY='<your-xmemo-token>'
```

## Generate / confirm XMEMO_AGENT_INSTANCE_ID

Generate one non-secret value per local Claude Code install, persist it outside git, and reuse it after restarts so attribution stays stable.

```bash
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 existing Claude Code XMemo configuration block rendered on this page. Preserve the Authorization variable reference and the identity-header names; never replace the token placeholder with a real secret.

## Restart the client

Restart Claude Code after changing the environment or MCP configuration so it opens a fresh hosted connection.

## Test with a real recall call

Make the first MCP call read-only. This is an actual recall invocation, not a health-check placeholder, and it does not write memory.

```text
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.

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

## Common Errors

Claude Code direct MCP failures use the shared bearer-token error contract.

- 401 invalid_token — the token is missing, expired, revoked, or otherwise invalid: verify XMEMO_KEY in the active environment or secret store, then restart.
- 403 insufficient_scope — the token does not grant memory:read: issue a token with the required scope.
- Invalid XMEMO_AGENT_INSTANCE_ID values are normalized to no instance attribution rather than raising an auth error: regenerate a stable value using allowed characters and persist it.

## 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_KEY": "${env:XMEMO_KEY}",
        "XMEMO_AGENT_INSTANCE_ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}
```