MCP overview

Connect XMemo to your AI environment

XMemo provides durable project memory across Claude, ChatGPT, Codex, GitHub Copilot, OpenClaw, Hermes, DeepSeek Harness, Microsoft Agent Framework, and open AI agent runtimes. Clients connect to the hosted Streamable HTTP endpoint directly or through the first-party xmemo-mcp stdio proxy shipped in @xmemo/client.

• Claude on claude.ai and Claude Desktop (Axis A: Config supported; Evidence required for current client proof · Axis B: Manual MCP Configuration; Directory listing pending): Custom connector at https://xmemo.dev/mcp with OAuth; no API key in the connector (/docs/mcp/claude).
• Claude (Axis A: Config supported; Evidence required for current client proof · Axis B: Manual MCP Configuration): Memory workflows, lifecycle checkpoints, and cross-agent continuity for Claude Code and Cowork (/docs/mcp/claude-code).
• ChatGPT (Axis A: Hosted beta pilot; Evidence required for any refreshed external claim · Axis B: Manual MCP Configuration; Marketplace pending): Memory workflows and interactive workspaces (TODO Board, Ledger, Project Workspace) (/docs/mcp/chatgpt).
• Codex (Axis A: Config supported; Evidence required · Axis B: Manual MCP Configuration): Skill-guided project memory and MCP authorization (/docs/mcp/codex).
• OpenClaw (Axis A: Released; Pilot tested · Axis B: Official Marketplace, Native Integration): Recall-first Skill guidance plus a native OpenClaw memory plugin on ClawHub (/docs/connect/openclaw).
• Hermes (Axis A: Released; Pilot tested · Axis B: Native Integration): Native Hermes memory plugin (hermes-xmemo) on PyPI with session checkpointing and auto-capture (/docs/connect/hermes).
• DeepSeek Harness (Axis A: Released; Pilot tested · Axis B: Native Integration): Native dsh agent harness plugin (dsh-xmemo) on npm for CLI execution loop memory (/docs/connect/deepseek-harness).
• Microsoft Agent Framework (Axis A: Planned; package publication pending · Axis B: Native Integration): Independent community integration for Python context retrieval and opt-in capture; not an official Microsoft product or distribution (/docs/connect/microsoft-agent-framework).
• GitHub Copilot & VS Code (Axis A: Config supported; Evidence required for current client proof · Axis B: Manual MCP Configuration): MCP integration for IDE and CLI agents (/docs/mcp/copilot).
• Gemini CLI (Axis A: Config supported; Evidence required for current client proof · Axis B: Manual MCP Configuration): OAuth-first configuration without placing bearer credentials in settings.json.

Two orthogonal delivery axes: availability and distribution mode

Client integrations are classified along two independent axes: Axis A represents empirical readiness and availability status (Released, Pilot / Entitled, or Planned), while Axis B defines the integration and distribution mode (Official Marketplace, Community Directory, Native Integration, or Manual MCP Configuration). The delivery channel does not determine availability, and roadmap features remain strictly distinguished from production runtimes.

• Axis A (Availability / Evidence Status): Released (fully operational in production), Pilot / Entitled (hosted beta pilot or commercial entitlement required), Planned (roadmap items requiring explicit forward-looking disclosure).
• Axis B (Integration / Distribution Mode): Official Marketplace (vendor-reviewed listings such as ClawHub official skill), Community Directory (third-party index listings), Native Integration (embedded runtime support), Manual MCP Configuration (user-configured JSON snippets).

Four unified connection paths

Choose the connection path matching your client architecture and operational model:

• Path 1 (Ask your agent — Standalone Skill): For compatible agents (Claude Code, Codex). Installs the verified Skill into the client's skills directory via https://xmemo.dev/skill/install.
• Path 2 (Hosted MCP over OAuth): For desktop and hosted clients (ChatGPT, Claude custom connector on claude.ai and Claude Desktop, Cursor, VS Code Copilot). Connects https://xmemo.dev/mcp without manual token handling.
• Path 3 (Direct MCP with XMEMO_KEY): For headless runners and CI environments. Passes bearer tokens securely via local environment variables over Streamable HTTP.
• Path 4 (First-party stdio proxy — xmemo-mcp): For stdio-only desktop clients, Claude Desktop setups that do not use the custom connector, or tools lacking direct Streamable HTTP support. The official @xmemo/client CLI package provides xmemo-mcp (runnable via npx -y -p @xmemo/client xmemo-mcp or xmemo mcp serve) as a self-contained local stdio proxy bridging to the hosted service (https://xmemo.dev).

OAuth client configuration

The hosted URL is the entire configuration; the grant supplies the scopes.

{
  "servers": {
    "XMemo": {
      "type": "http",
      "url": "https://xmemo.dev/mcp"
    }
  }
}

Direct token configuration

Headless runners that cannot complete OAuth read the token from the environment instead.

{
  "mcpServers": {
    "XMemo": {
      "type": "http",
      "transport": "streamable-http",
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${XMEMO_KEY}",
        "X-Memory-OS-Agent-ID": "${XMEMO_AGENT_ID}",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}

First-party stdio proxy configuration (xmemo-mcp)

For Claude Desktop, start with the custom connector and OAuth (/docs/mcp/claude); this API key configuration is the alternative. For stdio-only clients, the official @xmemo/client CLI package ships xmemo-mcp as a self-contained local stdio proxy bridging to https://xmemo.dev. Paste your actual API key; Claude Desktop does not expand ${env:...} variables:

{
  "mcpServers": {
    "XMemo": {
      "command": "npx",
      "args": [
        "-y",
        "-p",
        "@xmemo/client",
        "xmemo-mcp"
      ],
      "env": {
        "XMEMO_KEY": "<your-xmemo-api-key>",
        "XMEMO_URL": "https://xmemo.dev"
      }
    }
  }
}

Profile-qualified tool surfaces

Available tools are profile-qualified according to client capabilities in config/mcp-documentation-contract.json:

• Cursor profile (cursor-plugin): provides tools for conflict resolution, snapshots, and Cloud Skills.
• ChatGPT profile (chatgpt-public): provides tools for interactive workspaces (TODO Board, Ledger, Project Workspace).
• Claude public profile (claude-public): provides tools for project memory, ledger summaries, and active recall.
• Claude plugin profile (claude-plugin): provides tools for snapshots, decision records, and project continuity.
• Generic public profile (generic-public): provides tools for standard MCP clients.

Candidate integrations and unverified distribution

XMemo tracks emerging client integrations and editor extensions through verified evidence. The following candidate paths remain unverified or pending maintainer review; no marketplace availability or official endorsement is claimed:

• VS Code Native Extension (xmemo-vscode): Source repository (yonro/xmemo-vscode @ bf08e7c237, v0.1.1) and CI workflows exist, but Visual Studio Marketplace publication is unconfirmed and Open VSX returned 404. Users should connect VS Code through the verified hosted MCP or Copilot Chat configuration (/docs/mcp/copilot) rather than unverified extension packages.
• Cindy Ghost Plugin (xmemo-cindy-plugin): Ghost plugin candidate (yonro/xmemo-cindy-plugin @ 0cbbac5a53, v1.0.0) remains pending maintainer review with no public GitHub Releases or verified distribution channel observed.
• Shared Skills Package (@xmemo/skills): While repository source exists, public npm lookup returned 404; use the verified standalone Skill (@xmemo/skill) instead.

Let a runner configure itself

An autonomous runner can fetch its own preset instead of asking a human to type identity values.

curl -s https://xmemo.dev/api/v1/mcp/config/autonomous-agent