XMemo CLI

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/client is the official control plane for connecting AI tools to XMemo. It makes setup repeatable, keeps credentials out of project files, and gives every supported client a consistent path to durable, user-owned memory.

The package is deliberately small: the CLI runtime, safe client configuration, behavior profiles, XMemo skills, and marketplace metadata. Server code, databases, deployment files, logs, and internal operations remain outside the npm distribution.

Architecture

Why XMemo CLI

• One control plane — login, diagnostics, configuration, profiles, updates, and smoke checks share one predictable interface.
• Private by design — generated project configuration references a credential; it never embeds the credential value.
• Native where it matters — OpenClaw and Hermes use dedicated memory integrations instead of duplicating the same capability through MCP.
• Portable everywhere else — hosted Streamable HTTP MCP and local stdio cover modern editors, terminals, and agent runtimes.
• Safe automation — supported setup and removal paths offer preview, dry-run, or explicit confirmation before making changes.
• Small supply-chain surface — the npm package is governed by an explicit file allowlist and release provenance.

Quick start

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

Replace codex with your client. Preview a configuration before writing it:

xmemo setup cursor --dry-run

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

Supported integrations

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

Connection modes

Hosted MCP

The recommended universal path is the XMemo Streamable HTTP endpoint:

https://xmemo.dev/mcp

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

Generic configuration shape:

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

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

Local stdio MCP

xmemo-mcp is 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.

After a global installation:

xmemo-mcp

Install-free MCP configuration:

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

xmemo mcp serve is equivalent when the CLI is already installed.

Native integrations

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-only to skip the native integration and install only the hosted MCP fallback.

Authentication

Browser login

Recommended for personal accounts:

xmemo login
xmemo auth status

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. Prefer XMEMO_KEY or a managed secret store on shared systems.

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

xmemo login --allow-plaintext

Existing token

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

PowerShell:

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

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

Command reference

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

Run xmemo help or xmemo <command> --help for complete, version-matched options.

Client notes

xmemo setup codex
xmemo smoke --client codex

xmemo setup cursor

xmemo setup gemini
xmemo setup antigravity

xmemo login
xmemo setup openclaw
openclaw xmemo status

xmemo login
xmemo setup hermes

xmemo login
xmemo setup copilot
xmemo mcp proxy

Security by default

Credential precedence and compatibility aliases are documented by:

xmemo env example --shell bash
xmemo privacy

For private or self-hosted deployments, set XMEMO_URL or pass --url <service-url>. MEMORY_OS_URL remains a compatibility alias.

Package boundary

Published to npm:

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

Not published:

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

Development

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:

npm run prepublishOnly

The local stdio server can be inspected directly:

node bin/mcp-stdio.js

Release model

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

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

Version-bearing files must stay synchronized:

• package.json
• package-lock.json
• server.json
• lhm.plugin.json

node scripts/check-release-version.mjs --tag vX.Y.Z verifies the tag and every version-bearing file before publication. The separate npm publish workflow is manual recovery only, so creating a GitHub Release cannot publish twice.

Documentation and support

• XMemo
• XMemo MCP guide
• MCP server reference
• Issues
• Releases

License

MIT © 2025–2026 Yonro