XMemo

One private memory layer for every AI agent.

Install, authenticate, diagnose, and connect XMemo across editors, CLIs, and autonomous agents from one production-ready command line.

Quick start·Integrations·Connection modes·Commands·Security

@xmemo/clientis the official control plane for connecting AI tools toXMemo. It makes setup repeatable, keeps credentials out of project files, and gives every supported client a consistent path to durable, user-owned memory.

npm install -g @xmemo/client xmemo login xmemo doctor xmemo setup codex xmemo status

[!TIP] Start withxmemo login,xmemo doctor, andxmemo setup <client>. Hand-edit MCP configuration only when a client has no verified setup path.

The client registry also covers Windsurf, Cline, Continue, Claude Desktop, Claude Code, Kimi Code, Zed, JetBrains, OpenCode, Qwen, Trae, and compatible MCP hosts. Runxmemo mcp listfor the current machine-readable catalog.

The recommended universal path is the XMemo Streamable HTTP endpoint:

OAuth-capable clients complete authentication in the browser. Other clients referenceXMEMO_KEYwithout copying its value into repository files.

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

Client configuration keys differ; preferxmemo setup <client>over copying this generic example directly.

xmemo-mcpis the dedicated stdio entry point for marketplaces and clients that launch a local process. Safe discovery exposes 20 tools, three prompts, and two documentation resources without a token. Tool execution still requires authentication.

{ "mcpServers": { "XMemo": { "command": "npx", "args": [ "-y", "--package", "@xmemo/client@latest", "xmemo-mcp" ] } } }

xmemo mcp serveis equivalent when the CLI is already installed.

OpenClaw and Hermes have dedicated memory providers. Their default setup avoids installing a second, duplicate XMemo tool surface.

# Native OpenClaw plugin + XMemo Skill xmemo setup openclaw # Native Hermes memory provider xmemo setup hermes

Add hosted MCP only when an explicit fallback is desired:

xmemo setup openclaw --with-mcp xmemo setup hermes --with-mcp

Use--mcp-onlyto skip the native integration and install only the hosted MCP fallback.

The CLI uses the hosted device-login flow, waits for browser approval, and asks once before storing the issued credential unencrypted in the current user's XMemo config directory. The exact path is shown before approval, file permissions are restricted where the operating system supports it, and the credential value is never printed. PreferXMEMO_KEYor a managed secret store on shared systems.

For non-interactive automation, record the same decision explicitly:

Pipe an existing token through stdin so it does not appear in command history:

printf '%s\n' 'your-token' | xmemo token add --from-stdin --allow-plaintext xmemo token status --verify

$xmemoToken = Read-Host "XMemo token" $xmemoToken | xmemo token add --from-stdin --allow-plaintext Remove-Variable xmemoToken

For CI and managed workstations, exposeXMEMO_KEYthrough the platform's secret manager. Do not commit it to.env, MCP configuration, logs, issue reports, or chat transcripts.

xmemo --version xmemo update xmemo update --dry-run xmemo doctor xmemo discovery show xmemo status xmemo privacy

xmemo login xmemo auth status xmemo auth-status --verify xmemo token status --verify xmemo token add --from-stdin --allow-plaintext xmemo env example --shell bash

xmemo setup <client> xmemo setup <client> --dry-run xmemo setup --all xmemo setup openclaw [--with-mcp|--mcp-only] xmemo setup hermes [--with-mcp|--mcp-only]

xmemo mcp serve xmemo mcp list xmemo mcp config --client generic xmemo mcp add <client> --write xmemo mcp proxy xmemo profile install <client> xmemo profile status <client> xmemo profile uninstall <client> xmemo smoke --client codex

xmemo uninstall <client> --dry-run xmemo uninstall <client> --yes xmemo uninstall --all --dry-run xmemo uninstall --all --yes --profiles

Only XMemo-owned entries and marker-scoped behavior profiles are removed. Unrelated MCP servers, credentials, and device identity remain intact.

Runxmemo helporxmemo <command> --helpfor complete, version-matched options.

xmemo setup codex xmemo smoke --client codex xmemo setup cursor

Both setup paths write a user-scoped MCP entry and can install a marker-scoped memory behavior profile. Use--no-profileto configure MCP only. Cursor's public marketplace plugin remains OAuth-first and contains no bearer-token configuration.

xmemo setup gemini xmemo setup antigravity

These clients use hosted MCP OAuth. Their generated configuration carries no token value; restart the client and complete the browser login on first use.

xmemo login xmemo setup openclaw openclaw xmemo status

The setup command installs or updates@xmemo/openclaw-memory, installs the XMemo Skill, reuses the shared XMemo credential, and checks plugin status.

The setup command installs or updateshermes-xmemo, configures the native provider, and synchronizes the user-scoped XMemo credential with Hermes.

xmemo login xmemo setup copilot xmemo mcp proxy

Copilot CLI receives a local proxy entry. The proxy reads the credential from user-scoped storage, adds identity metadata, and forwards requests to hosted MCP without writing secrets into Copilot configuration.

Credential precedence and compatibility aliases are documented by:

xmemo env example --shell bash xmemo privacy

For private or self-hosted deployments, setXMEMO_URLor pass--url <service-url>.MEMORY_OS_URLremains a compatibility alias.

bin/ docs/assets/ src/ skills/ plugins/kiro/ plugins/xmemo/ README.md LICENSE

.github/ docs/analysis/ docs/architecture/ test/ coverage/ server code database migrations deployment files logs and local state

npm install npm run release:check npm run lint npm test npm run pack:dry-run

Before proposing a release, run the complete package gate:

The local stdio server can be inspected directly:

Normal releases are produced by GitHub Actions from the exact tagged commit, not from a mutable branch checkout or a developer workstation:

develop → CLI version sync → test → cli-v tag → GitHub Actions → npm publish --provenance

The CLI package and hosted MCP service intentionally have separate version streams:

- CLI/npm version:package.json,package-lock.json, and the npm package entry inserver.json.
- Hosted MCP/Registry version: the top-levelserver.json.versionandlhm.plugin.json. This version follows the deployed XMemo service.

node scripts/check-release-version.mjsverifies both contracts. Acli-vX.Y.Ztag must equal the CLI/npm version and publishes only npm. The MCP Registry is published separately with thePublish MCP Registry metadataworkflow usingmcp-vX.Y.Z, which must equal the hosted MCP/Registry version. The separate npm publish workflow is manual recovery only, so creating a GitHub Release cannot publish twice.

- XMemo
- XMemo MCP guide
- MCP server reference
- Issues
- Releases

Self-hosted MCP server giving AI agents persistent memory — Markdown source of truth, hybrid BM25+embedding search, typed graph relations.