Configure the direct MCP path with XMEMO_KEY from a local environment or supported secret store.
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.
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.
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.
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>
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 MCP configuration
Configuration file: %APPDATA%\Claude\claude_desktop_config.json
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}"
}
}
}
}
Client readiness
- Evidence required
- Marketplace pending
- See /product/docs#client-capability-matrix; this matches the authoritative config installed by @xmemo/client.