Quickstart

1. Choose client and auth mode

Select your agent client and preferred connection path. For Claude Code, Codex, and compatible agents, use the standalone Skill installer with 'Ask your agent'. For clients without skills like ChatGPT, use hosted MCP over OAuth. For direct and headless runners like Cursor or VS Code, use Direct MCP with XMEMO_KEY. Dedicated client guides are available under /docs/mcp/claude-code, /docs/mcp/codex, /docs/connect/openclaw, /docs/mcp/chatgpt, /docs/mcp/cursor, and /docs/mcp/copilot.

• Path 1 (Skill): Ask your agent to install the standalone XMemo Skill for Claude Code, Codex, and OpenClaw (/docs/connect/openclaw).
• Path 2 (OAuth MCP): Hosted MCP over OAuth for clients without skills, including ChatGPT (/docs/mcp/chatgpt) and Claude Desktop (/docs/mcp/overview).
• Path 3 (Direct MCP): Direct Streamable HTTP MCP referencing ${XMEMO_KEY} from your local environment for Cursor (/docs/mcp/cursor) and VS Code (/docs/mcp/copilot).
• Auth modes: OAuth (preferred, browser-approved) vs Direct MCP (environment variable XMEMO_KEY).
• Intermediate status: Selecting a client and copying config is an intermediate step, not activation.

2. Configure client without exposing tokens

Install the standalone Skill or configure your client using the hosted MCP endpoint (https://xmemo.dev/mcp). For Skill clients, provide the official installation prompt to your agent as the primary copy action, or execute the canonical installer manually. For Direct MCP, reference ${XMEMO_KEY} from your local environment or secret store. Never hardcode plaintext bearer tokens into client configuration files or version control.

• Path 1 (Ask your agent): 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.
• Manual-copy fallback: Run 'curl -fsSL https://xmemo.dev/skill/install | sh' (Windows PowerShell: 'irm https://xmemo.dev/skill/install.ps1 | iex') with XMEMO_SKILL_DIR set explicitly.
• OAuth clients: Configure https://xmemo.dev/mcp and approve memory:read and memory:write in the browser.
• Direct MCP: Reference ${XMEMO_KEY} in config; keep the real token in your local environment or secret store.
• Zero secrets: Configuration files must never contain unencrypted bearer tokens.

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

3. Verify connection with read-only check

Always verify connectivity with a read-only request before writing data. Installation, authentication, and activation are distinct milestones. For the standalone Skill, execute the doctor command printed by the installer. Before signing in, choose your credential path: prefer providing XMEMO_KEY from a secret store or using managed credentials. If you use interactive device login with --allow-plaintext, note that this flag stores the credential unencrypted on this computer. Verify status after authentication. For MCP clients, get_mcp_identity confirms that your client can reach the server and that your memory:read scope is valid.

• Skill doctor command: node scripts/xmemo-skill.mjs doctor --anonymous (checks runtime and connection).
• Skill credential alternatives: Provide XMEMO_KEY from a secret store or use managed credentials.
• Skill device login: node scripts/xmemo-skill.mjs login --allow-plaintext (opens browser verification; note that --allow-plaintext stores the credential unencrypted on this computer).
• Skill auth verification: node scripts/xmemo-skill.mjs auth status --verify (confirms credential validity).
• MCP tool: get_mcp_identity() (or recall with limit 1).
• Scope gate: memory:read.
• Success signal: Identity metadata confirms the server is reachable and authorized.

get_mcp_identity()

4. Save an explicit synthetic fact

Record a synthetic project convention to verify write capability under memory:write. Give the memory a specific path so subsequent queries can find it within the project scope. Use surface-correct syntax for your integration surface.

• Skill command: node scripts/xmemo-skill.mjs remember --content "Demo project timestamps use UTC." --path "projects/demo-onboarding/conventions".
• MCP tool: remember with explicit synthetic content.
• Path scope: projects/demo-onboarding/conventions.
• Success signal: Receipt begins with 'Saved to XMemo.' with assigned ID and Location.

remember({
  content: "Demo project timestamps use UTC.",
  path: "projects/demo-onboarding/conventions"
})

5. Open a fresh client session

Start a new conversation thread or restart your client to clear ephemeral in-memory context. This stateless transition ensures your next recall verifies server-side persistence rather than local chat history replay.

• Action: Close or reset the current chat session in your client.
• Context reset: Ephemeral client context is cleared to guarantee stateless testing.
• Persistence verification: Subsequent recall queries the remote store directly.

6. Recall fact with source attribution

Query the stored convention from the fresh session. Activation is strictly defined as completing the first verified memory recall with source attribution—copying configuration or inspecting snippets is only an intermediate setup step.

• Skill command: node scripts/xmemo-skill.mjs recall --query "demo project timestamp format" --limit 1.
• MCP tool: recall with query 'demo project timestamp format'.
• Receipt format: Textual output beginning with '### XMemo Memory Results:' showing Reference, Location, optional Created/Updated/Revision, and content.
• Success signal: First verified recall with source attribution marks true activation.

recall({
  query: "demo project timestamp format",
  limit: 1
})

7. Correct convention with update_memory

When project conventions evolve or require clarification, update the memory with the exact active memory ID or Reference returned from recall. For Skill clients, use the update command. For MCP clients, use update_memory. Optional cleanup is user-directed via forget.

• Skill command: node scripts/xmemo-skill.mjs update --id "mem_01hxyz..." --content "Demo project timestamps use UTC with ISO 8601 formatting.".
• MCP tool: update_memory with valid memory_id.
• Revision trail: Supersedes previous revision while preserving immutable history.
• Optional cleanup: To delete, run 'node scripts/xmemo-skill.mjs forget --id mem_01hxyz... --confirm' (Skill) or call forget (MCP).
• Success signal: Receipt begins with 'XMemo memory updated.' showing Reference and Revision.

update_memory({
  memory_id: "mem_01hxyz...",
  content: "Demo project timestamps use UTC with ISO 8601 formatting."
})

Recovery: Clipboard access denied

If your browser denies clipboard access or permissions are blocked, manually select the snippet text inside the code block and copy with Ctrl+C (or Cmd+C). All code blocks provide tabIndex=0 for keyboard scrolling and selection.

• Symptom: Browser blocks automatic clipboard copy or permissions prompt fails.
• Action: Click or tab into the code container and use Ctrl+C or Cmd+C.
• Verification: Pasted configuration matches the displayed snippet exactly.

Recovery: Expired or insufficient auth

If your client receives HTTP 401 Unauthorized, HTTP 403 Forbidden, or SetupRequiredMCPError, your authentication token has expired or lacks required scopes.

• Symptom: HTTP 401, HTTP 403, or SetupRequiredMCPError on tool invocation.
• Action: Re-authenticate via OAuth, or set XMEMO_KEY in your local environment.
• Verification: Confirm token grants both memory:read and memory:write scopes.

Recovery: Tools not visible in client

If XMemo tools do not appear in your client palette after configuration, the configuration file may contain syntax errors or the MCP connection process may need a restart.

• Symptom: Client shows 0 tools or fails to recognize the XMemo MCP server.
• Action: Check client developer logs, validate JSON syntax, and restart client.
• Verification: Client logs show successful MCP initialization and tool discovery.

Recovery: Empty recall results

If recall returns no matching memories ('No matching memories found' or 'No strong memory match'), verify that the write in Step 4 completed successfully and check your search query.

• Symptom: recall returns text message indicating no matching memories were found.
• Action: Check query keywords ('timestamp', 'UTC') and verify path scope.
• Verification: Confirm remember returned receipt starting with 'Saved to XMemo' before recalling.

Recovery: Unknown memory ID on update

If update_memory rejects your call because memory_id is unknown or invalid, do not guess identifiers.

• Symptom: update_memory returns error indicating memory_id not found.
• Action: Call recall first to retrieve the active memory Reference and pass it as memory_id.
• Verification: Pass the active memory Reference from recall into update_memory.

Recovery: Wrong install target

If the installer saved scripts directly into your agent's skills root directory rather than an isolated skill subdirectory, the agent cannot locate scripts/xmemo-skill.mjs or loads raw install files.

• Symptom: Error finding scripts/xmemo-skill.mjs or files extracted directly into skills root.
• Action: Set XMEMO_SKILL_DIR explicitly to your skills directory plus /xmemo-memory (e.g., export XMEMO_SKILL_DIR="$HOME/.claude/skills/xmemo-memory").
• Verification: SKILL.md and scripts/xmemo-skill.mjs reside directly inside the xmemo-memory folder.

Recovery: Missing Node 22.22.0 runtime

The standalone Skill requires Node.js >= 22.22.0. If node is missing or an older version is active, doctor and skill operations fail.

• Symptom: 'command not found: node', or runtime errors on startup, or node -v reports version below 22.22.0.
• Action: Install or switch to Node.js 22.22.0 or higher using nvm (nvm install 22.22.0 && nvm use 22.22.0) or your operating system package manager.
• Verification: Run 'node -v' and confirm output is v22.22.0 or higher.

Recovery: Skill reload needed

If the Skill is installed and doctor passes, but your agent does not list XMemo tools or operations in its active session, the agent's in-memory skills cache must be reloaded.

• Symptom: Agent reports no knowledge of XMemo skills after installation.
• Action: Restart the agent session to reload in-memory skills.
• Verification: Ask the agent 'what skills are available?' and verify xmemo-memory is listed.

Recovery: Interrupted login

If device login was interrupted, timed out, or closed before entering the verification code, credentials are not written to disk.

• Symptom: Browser was closed before approval, the one-time code expired, or 'auth status --verify' reports auth_valid: false.
• Action: If not using secret-store XMEMO_KEY or managed credentials, re-run 'node scripts/xmemo-skill.mjs login --allow-plaintext' (which stores the credential unencrypted on this computer), open the displayed URL, and enter the code before expiry.
• Verification: Run 'node scripts/xmemo-skill.mjs auth status --verify' and confirm 'status: ok' with 'auth_valid: true'.