XMemo Docs

Public docs

A customer-safe walkthrough backed by the implemented discovery route, onboarding contract, MCP server, and TypeScript SDK helpers.

# Quickstart for XMemo

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

- 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

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

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

- Skills chapter: agent Skill contract, MCP lane, and REST/Python fallback

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

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

Discovery setup

Install the public CLI package, then run setup against the approved service URL to fetch discovery, onboarding status, and the per-client MCP config template.

Public boundary

Docs describe implemented capabilities without linking to internal console, raw discovery, raw bootstrap, or control-plane endpoints.

Source evidence

The page content maps to server.py discovery/onboarding code, docs/HOSTED_DISCOVERY_CONTRACT.md, mcp_server.py, and packages/memory-os-js.

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.

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": {
    "memory_os": {
      "url": "https://xmemo.dev/mcp",
      "transport": "streamable-http",
      "auth": {
        "type": "oauth2",
        "resource": "https://xmemo.dev/mcp",
        "scopes": ["memory:read", "memory:write"]
      }
    }
  }
}

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": {
    "memory-os": {
      "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 for attribution.

[mcp_servers.memory_os]
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

Direct client: merge this memory_os block into settings.json, keep XMEMO_KEY in the environment, and use XMEMO_AGENT_INSTANCE_ID for stable local attribution.

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

Cursor

Cursor Settings -> MCP

Direct client: Cursor can install the same URL from Settings -> MCP or deeplink; keep the bearer token in XMEMO_KEY and retain the non-secret identity headers.

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

Other

Any MCP-capable agent

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

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