XMemo Docs

Public docs

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.

# Quickstart for XMemo

Hosted XMemo quickstart for connecting MCP clients, CLIs, IDEs, and autonomous agents without putting bearer tokens in public configuration.

- CLI package: @xmemo/client

- Service URL: https://xmemo.dev

- MCP URL: https://xmemo.dev/mcp

- Setup command: npx @xmemo/client setup --url https://xmemo.dev

- Direct MCP token environment variable: XMEMO_KEY

- OAuth-supported clients: ChatGPT, VS Code / GitHub Copilot

- Persona flows: ChatGPT user, Copilot/Codex developer, team pilot owner, autonomous agent operator

- Autonomous agent preset: OAuth-first when supported; XMEMO_KEY fallback for headless runners; runner-generated XMEMO_AGENT_INSTANCE_ID required

- Supported MCP clients: chatgpt, vscode, copilot-cli, codex, gemini-cli, cursor, autonomous-agent, generic

- MCP chapter: per-client setup snippets and hosted streamable-http boundary

- Skills chapter: standalone Skill runtime, device login, and direct HTTPS operations

- SDK helpers: taskStart, taskEnd, recordDecision, recordBugFix, recordCorrection, recordEvent

- Safety guarantees: manual config review, environment-variable secrets, no token in generated URLs

## 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: https://xmemo.dev/mcp (memory:read memory:write)

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

- Direct MCP with XMEMO_KEY: https://xmemo.dev/mcp

## 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

- Edit or correct entries

- Delete and export

- Agent attribution

- Privacy and credential controls

## FAQ / Troubleshooting

Use these answers when a user or marketplace reviewer gets blocked. Every answer includes an action step and a safety boundary.

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.

Implemented hosted-service surfaces

The discovery response advertises the @xmemo/client CLI package, streamable-http MCP transport, supported MCP clients, onboarding status, auth metadata, and the MCP tool catalog.

CLI package — @xmemo/client is the published package name exposed by discovery and the public-home install bar.
Supported clients — The MCP catalog includes ChatGPT, VS Code / GitHub Copilot, copilot-cli, codex, gemini-cli, cursor, and generic direct MCP clients.
MCP tools — Discovery lists recall, remember, state, reflection, feedback, audit, and system-stat tools.
Auth boundary — Discovery declares token env vars and explicitly does not include token material.

xmemo setup --url drives the entire trial

Once the CLI is installed, the customer points it at the approved service URL. The hosted contract documents discovery, onboarding status, manual MCP config templates, operator-provisioned tokens, and env-var based MCP config.

# Customer-side, after npm install -g @xmemo/client
npx @xmemo/client setup --url https://xmemo.dev

# CLI internally: discovery -> status -> MCP config template ->
# operator token handoff -> local client configuration.

OAuth first, runner-generated identity

Autonomous runners should fetch /api/v1/mcp/config/autonomous-agent and choose auth_modes.oauth when they can complete OAuth and send custom identity headers. If the runner is fully headless or cannot persist OAuth tokens, it should use auth_modes.xmemo_key with XMEMO_KEY from a secret store. The agent id is fixed as autonomous-agent, while XMEMO_AGENT_INSTANCE_ID must be generated once by the runner and reused; the human should not type either identity value.

GET https://xmemo.dev/api/v1/mcp/config/autonomous-agent
# Preferred: auth_modes.oauth.mcpServers.XMemo
# Headless fallback: auth_modes.xmemo_key.mcpServers.XMemo
# Required identity: X-Memory-OS-Agent-ID=autonomous-agent
# Runner generates and persists: XMEMO_AGENT_INSTANCE_ID

What agents can do once connected

Agents talk to XMemo through the TypeScript SDK helpers, streamable-http MCP server, or REST. The SDK exposes workflow helpers and capture policy redaction before memory writes.

taskStart / taskEnd — Bound an agent run to a memory scope so resume and handoff work across sessions.
recordDecision — Persist architecture or product decisions with rationale and source identity.
recordBugFix — Log fixes so future runs recall the root cause and remediation.
captureEvent — Run any normalized agent event through capture policy before remember().
recallContext / search — Pull recent decisions and procedural notes back into agent context with explanation.

Manual onboarding guarantees

The hosted discovery contract requires read-only discovery, secret-free MCP config templates, no remote shell or PowerShell execution paths, and secrets stored through environment variables or a system secret store.

Supported MCP clients

VS Code / GitHub Copilot

%APPDATA%\Code\User\mcp.json

OAuth client: keep only the hosted server URL in mcp.json; first tool call opens browser OAuth, so no XMEMO_KEY or Authorization header belongs in this file.

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

ChatGPT / OpenAI Apps SDK

OpenAI Platform app management dashboard

OAuth marketplace lane: configure the hosted MCP URL and OAuth metadata in the OpenAI app dashboard; never paste XMEMO_KEY or Bearer tokens into the listing.

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

Claude Code / Claude Desktop

Claude MCP settings

Direct client: Claude Code can use the same hosted MCP URL with XMEMO_KEY from the local environment or secret store; set XMEMO_AGENT_INSTANCE_ID once per local install for stable attribution.

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

Copilot CLI

~/.copilot/mcp-config.json

Direct client: set XMEMO_KEY in the user environment or a supported secret reference, then replace the stable instance placeholder before applying the reviewed config.

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

Codex

~/.codex/config.toml

Direct client: Codex reads XMEMO_KEY through bearer_token_env_var and sends non-secret identity headers. Run npx @xmemo/client mcp add codex --write to generate the stable XMEMO_AGENT_INSTANCE_ID automatically.

[mcp_servers.XMemo]
url = "https://xmemo.dev/mcp"
bearer_token_env_var = "XMEMO_KEY"
http_headers = { "X-Memory-OS-Agent-ID" = "codex" }
env_http_headers = { "X-Memory-OS-Agent-Instance-ID" = "XMEMO_AGENT_INSTANCE_ID" }

Gemini CLI

~/.gemini/settings.json

OAuth client: merge this XMemo block into settings.json, set one stable XMEMO_AGENT_INSTANCE_ID for local attribution, then restart Gemini CLI and complete MCP OAuth. Do not add Authorization or XMEMO_KEY to this snippet.

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

Cursor

Cursor Settings -> MCP

OAuth client: Cursor marketplace and Settings -> MCP installs should store only the hosted server URL; first use opens browser OAuth, so no XMEMO_KEY or Authorization header belongs in the marketplace plugin.

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

Autonomous agent

Agent runner MCP config

OAuth-first self-config preset: fetch /api/v1/mcp/config/autonomous-agent, use auth_modes.oauth when the runner supports OAuth + custom headers, fall back to auth_modes.xmemo_key for headless runners, and never ask the human for agent_id or instance_id.

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

Generic direct client: the client must support streamable-http and Authorization headers; set XMEMO_AGENT_ID and a stable XMEMO_AGENT_INSTANCE_ID only for non-secret attribution.

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