Quickstart for XMemo

Use XMemo as a shared memory home for AI assistants: connect a client, save useful context once, recall it later, and keep credentials out of public configuration.

Introduction #

Use XMemo as a shared memory home for AI assistants: connect a client, save useful context once, recall it later, and keep credentials out of public configuration.

One memory home

Keep durable preferences, project facts, decisions, and handoff notes in a user-owned memory layer that approved assistants can recall.

Connect your client

Use the hosted MCP URL with the client profile for ChatGPT, Claude, VS Code / GitHub Copilot, Copilot CLI, Codex, Gemini, Cursor, or direct MCP runners.

Keep control

Use OAuth where supported, environment-secret handoff for direct clients, and account controls for review, deletion, and export boundaries.

Persona onboarding flows #

ChatGPT user

Goal: Give ChatGPT durable access to your XMemo preferences, project facts, decisions, and TODOs without pasting bearer tokens into a chat.
Connection: Connect the hosted XMemo MCP server through the ChatGPT/OpenAI app OAuth flow, then approve the memory:read and memory:write grant for your XMemo account.
Success action: Save a synthetic preference or project note, start a new chat, then ask ChatGPT to recall it through XMemo before continuing work.
Troubleshooting: If OAuth fails or tools do not appear, sign out of the MCP server in the host app, reconnect the XMemo server URL, and retry before creating direct tokens.

Copilot / Codex developer

Goal: Carry repo decisions, coding conventions, bug-fix notes, and task history between IDE and CLI agents.
Connection: Use OAuth for VS Code / GitHub Copilot and Gemini CLI when available. For Copilot CLI, Codex, Cursor, or other direct MCP clients, keep XMEMO_KEY in the local environment or secret store and set a stable XMEMO_AGENT_INSTANCE_ID.
Success action: Record a codebase decision or bug fix, then ask the next IDE or CLI agent to recall the relevant XMemo context before editing.
Troubleshooting: If recalls are empty, verify the selected MCP config path, the XMEMO_KEY environment variable for direct clients, and any stale OAuth credential in the host app.

Team / enterprise pilot owner

Goal: Evaluate shared memory with account controls, source attribution, export/delete workflows, and reviewer-safe setup evidence.
Connection: Create or enter the protected XMemo workspace, invite approved users, then connect each client through OAuth or a scoped direct credential according to the readiness badges.
Success action: Have a pilot member save a synthetic team memory, confirm source attribution in XMemo, then review delete/export and support paths.
Troubleshooting: If a member cannot connect, check role permissions, OAuth approval, client readiness status, and support guidance before issuing a new token.

Autonomous agent operator

Goal: Let headless or scheduled agents record progress, retrieve prior decisions, and keep a stable non-secret instance identity.
Connection: Fetch /api/v1/mcp/config/autonomous-agent. Prefer auth_modes.oauth when the runner supports OAuth + custom headers; use auth_modes.xmemo_key with XMEMO_KEY from a secret store only for fully headless runners.
Success action: Run one synthetic task that writes progress to XMemo, restart the runner, and confirm it recalls that progress using the same XMEMO_AGENT_INSTANCE_ID.
Troubleshooting: If attribution changes or recalls split across instances, persist XMEMO_AGENT_INSTANCE_ID outside git and verify the runner is not regenerating it on every start.

Memory Console controls #

XMemo is not only an MCP endpoint. The Memory Console is the user-facing place to review, correct, remove, and export memory while keeping agent attribution visible.

View and search memory

Open the console to see saved memories, inspect paths and memory types, and confirm whether a recall should have returned a specific item.

Edit or correct entries

Correct stale facts, move items to clearer paths, or replace outdated notes so future assistants recall the latest user-approved context.

Delete and export

Use account workflows to remove memories you no longer want and to locate export paths for account-scoped memory review.

Agent attribution

Review which client or runner wrote a memory, including non-secret agent and instance labels when the client sends them.

Privacy and credential controls

Keep OAuth consent, direct-token usage, environment-secret handoff, and support boundaries visible before expanding a personal or team pilot.

Request XMemo access #

Open account entry ↗

Hosted XMemo quickstart #

Start with the managed XMemo service and one of these connection paths. Self-hosted, Docker, Supabase, and Python package setup are developer references, not the first path for hosted users.

OAuth clients

Use this path for ChatGPT, OpenAI app review, VS Code, and GitHub Copilot when the host supports OAuth. Add the hosted MCP URL, approve memory:read and memory:write, and do not paste XMEMO_KEY into the client config.

MCP URL: https://xmemo.dev/mcp
Scopes: memory:read memory:write

@xmemo/client setup

Use the public CLI to discover the hosted service, review the generated MCP profile, and copy only client-safe configuration into your local tool.

npm install -g @xmemo/client
npx @xmemo/client setup --url https://xmemo.dev

Direct MCP with XMEMO_KEY

Use this path only for clients or headless runners that cannot complete OAuth. Store XMEMO_KEY in the local environment or secret store, keep the hosted MCP URL in config, and never paste the real token into public docs or chat.

MCP URL: https://xmemo.dev/mcp
Token source: XMEMO_KEY environment variable
Optional identity: XMEMO_AGENT_INSTANCE_ID

Account controls

After the first connection, use the account entry to review what was saved, check agent attribution, and find delete/export or support paths before expanding a pilot.

Account entry: https://xmemo.dev/login

Public safety #

Public discovery is read-only and secret-free.
Client setup requires secrets in environment variables or a system secret store, not in generated URLs.
Public product docs intentionally avoid links to operator consoles, API docs, discovery JSON, installer catalogs, raw bootstrap URLs, raw service URLs, and credential material.

Source evidence #

Source-backed docs from the XMemo discovery route, hosted discovery contract, MCP server, and TypeScript SDK.

FAQ / Troubleshooting #

Why does my AI assistant not remember something I told it earlier? —
Why is my AI assistant mixing up my projects or conversations? —
How can I make my AI assistant forget something completely? —
I changed computers or AI assistants; will XMemo still remember me? —
Why did my AI assistant save the same thing twice? —
Why is my AI assistant giving me too much or too little of my past context? —
I disconnected XMemo; how do I make sure the old assistant cannot use it? —
Why cannot my AI assistant use XMemo anymore? —
Which XMemo connection should I use in my AI assistant? —
What should I do if my AI assistant still cannot connect to XMemo? —

Prerequisites #

Approved service URL - Used by xmemo setup --url to fetch discovery, onboarding status, and MCP config templates.
Node.js and npm - Discovery and the product page advertise @xmemo/client as the public CLI package.
Scoped token or OAuth grant - ChatGPT and VS Code / GitHub Copilot use OAuth; direct MCP and REST clients use XMEMO_KEY from an environment variable or secret store.

Connect with XMemo #

xmemo setup --url drives the entire trial. The documented hosted setup flow is implemented as discovery → onboarding status → MCP config template → reviewed client configuration.

npm install -g @xmemo/client
npx @xmemo/client setup --url https://xmemo.dev

MCP configuration #

XMemo MCP setup lives in Docs because auth differs by client. ChatGPT, VS Code / GitHub Copilot, and Gemini CLI use hosted OAuth; direct/headless clients use the hosted Streamable HTTP URL plus XMEMO_KEY from the local environment or secret store.

VS Code / GitHub Copilot

%APPDATA%\Code\User\mcp.json

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

Cursor

~/.cursor/mcp.json

{
  "mcpServers": {
    "XMemo": {
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:XMEMO_KEY}",
        "X-Memory-OS-Agent-ID": "cursor",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}

Codex

~/.codex/config.toml

[mcp_servers.XMemo]
url = "https://xmemo.dev/mcp"
bearer_token_env_var = "XMEMO_KEY"

[mcp_servers.XMemo.http_headers]
X-Memory-OS-Agent-ID = "codex"
X-Memory-OS-Agent-Instance-ID = "${XMEMO_AGENT_INSTANCE_ID}"

Gemini CLI

~/.gemini/settings.json

{
  "mcpServers": {
    "XMemo": {
      "httpUrl": "https://xmemo.dev/mcp",
      "headers": {
        "X-Memory-OS-Agent-ID": "gemini-cli",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}

Claude Desktop

%APPDATA%\Claude\claude_desktop_config.json

{
  "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}"
      }
    }
  }
}

Devin Desktop (formerly Windsurf)

~/.config/devin/mcp_config.json

{
  "mcpServers": {
    "XMemo": {
      "serverUrl": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:XMEMO_KEY}",
        "X-Memory-OS-Agent-ID": "windsurf",
        "X-Memory-OS-Agent-Instance-ID": "${env:XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}

Kiro

~/.kiro/settings/mcp.json

{
  "mcpServers": {
    "XMemo": {
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "X-Memory-OS-Agent-ID": "kiro",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      },
      "oauth": {
        "oauthScopes": [
          "memory:read",
          "knowledge:read"
        ]
      }
    }
  }
}

OpenClaw

~/.openclaw/openclaw.json

{
  "mcpServers": {
    "XMemo": {
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:XMEMO_KEY}",
        "X-Memory-OS-Agent-ID": "openclaw",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}

Copilot CLI

~/.copilot/mcp-config.json

{
  "mcpServers": {
    "XMemo": {
      "type": "http",
      "url": "https://xmemo.dev/mcp",
      "tools": ["*"],
      "timeout": 30000,
      "headers": {
        "Authorization": "Bearer <replace-with-XMEMO_KEY-or-supported-secret-reference>",
        "X-Memory-OS-Agent-ID": "copilot-cli",
        "X-Memory-OS-Agent-Instance-ID": "<stable-local-copilot-cli-instance-id>"
      }
    }
  }
}

ChatGPT / OpenAI Apps SDK

OpenAI Platform app management dashboard

{
  "mcpServers": {
    "XMemo": {
      "url": "https://xmemo.dev/mcp",
      "transport": "streamable-http",
      "auth": {
        "type": "oauth2",
        "resource": "https://xmemo.dev/mcp",
        "scopes": ["memory:read", "memory:write"]
      }
    }
  }
}

Autonomous agent

Agent runner MCP config

{
  "mcpServers": {
    "XMemo": {
      "type": "http",
      "transport": "streamable-http",
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "X-Memory-OS-Agent-ID": "autonomous-agent",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      },
      "auth": {
        "type": "oauth2",
        "flow": "authorization_code",
        "pkce_required": true,
        "resource": "https://xmemo.dev/mcp",
        "scopes": ["memory:read", "memory:write"]
      },
      "fallback": {
        "use_when": "headless runner cannot complete OAuth sign-in or persist OAuth tokens",
        "authorization_header": "Bearer ${XMEMO_KEY}"
      }
    }
  }
}

Other

Any MCP-capable agent

{
  "mcpServers": {
    "XMemo": {
      "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}"
      }
    }
  }
}

Client capability matrix #

The canonical matrix is the source of truth for each client's OAuth mode, MCP transport, credential handling, readiness, evidence boundary, and marketplace state. This page only provides the setup console; do not copy a status into another page without checking the matrix.

Read CLIENT_CAPABILITY_MATRIX.md on GitHub ↗

Autonomous agent preset #

Autonomous agents should fetch /api/v1/mcp/config/autonomous-agent instead of asking humans to choose identity fields.

MCP tool surface #

The discovery response lists the actual MCP transport as streamable-http and advertises tools implemented by the XMemo MCP server.

Recall tools - search_memory, recall, recall_plan, and recall_context.
Write tools - remember, store_memory, update_memory, and record_event.
Governance tools - forget_memory, redact_memory, explain_memory, and conflict/version helpers.

SDK workflow helpers #

The TypeScript SDK exposes workflow helpers in packages/memory-os-js. These helpers route events through capture policy before writing memory.

Skills and agents #

Skills are the instruction-and-command lane for agents that do not mount a hosted MCP server directly.