Labsco
yonro logo

XMemo

★ 12

from yonro

User-owned memory for AI agents over remote MCP. Save, search, recall, update, and manage scoped memories across Copilot, Claude, ChatGPT, IDEs, and CLIs.

🔥🔥🔥✓ VerifiedAccount requiredAdvanced setup
#automation#analytics#database#devops#git#maps#security#memory

XMemo CLI

@xmemo/client is the privacy-first command line entry point for XMemo client setup. It is intentionally small: the npm package contains only the CLI and setup/helper assets needed on a user's machine: the CLI runtime, client setup profiles, XMemo skills, and marketplace plugin metadata.

@yonro/xmemo-client is reserved as a Yonro fallback package. The CLI exposes xmemo as the primary command and keeps memory-os as a compatibility alias.

The XMemo server, database, token registry, deployment files, logs, and internal scripts are not part of this npm package.

XMemo CLI is the top-level control plane — use xmemo login, xmemo doctor, xmemo setup <client>, and smoke checks before hand-editing MCP config. Hosted MCP remains the universal runtime path for clients that do not have a native integration.

XMemo Runtime Overview

XMemo is a user-owned memory system that lets AI agents persistently store, search, recall, update, and manage notes and memory fragments across sessions, projects, and tools.

  • Top-level CLI: xmemo from @xmemo/client

  • Native integrations: OpenClaw XMemo memory plugin and Hermes hermes-xmemo provider

  • MCP Endpoint: https://xmemo.dev/mcp (Streamable HTTP)

  • Auth: Bearer Token (XMEMO_KEY) or MCP OAuth

  • Tools: remember, recall, search_memory, update_memory, forget, redact_memory, explain_memory, create_memory_todo, list_memory_todos, complete_memory_todo, record_event, get_timeline, add_expense

  • Clients: Kimi, Claude, Cursor, Copilot, Gemini, Grok, Windsurf, Cline, Trae, Zed, Qwen, and more

Copy & paste — that's it
{
 "mcpServers": {
 "XMemo": {
 "type": "streamable-http",
 "url": "https://xmemo.dev/mcp",
 "headers": {
 "Authorization": "Bearer ${XMEMO_KEY}"
 }
 }
 }
}

See MCP Setup for detailed client configuration.

Commands

Copy & paste — that's it
xmemo update
xmemo setup codex
xmemo setup codex --dry-run
xmemo setup cursor
xmemo setup cursor --dry-run
xmemo setup copilot
xmemo setup copilot --dry-run
xmemo setup openclaw
xmemo setup openclaw --dry-run
xmemo setup openclaw --with-mcp
xmemo setup openclaw --mcp-only
xmemo setup hermes
xmemo setup hermes --with-mcp
xmemo setup hermes --mcp-only
xmemo setup gemini
xmemo setup gemini --dry-run
xmemo setup antigravity
xmemo setup antigravity --dry-run
xmemo setup kiro
xmemo setup kiro --dry-run
xmemo setup grok
xmemo setup grok --dry-run
xmemo mcp add antigravity2
xmemo mcp add antigravity2 --write
xmemo doctor
xmemo discovery show
xmemo setup
xmemo login
xmemo auth status
xmemo status
xmemo token status
xmemo token add --from-stdin
xmemo env example --shell bash
xmemo mcp list
xmemo mcp config --client generic
xmemo mcp config --client antigravity
xmemo mcp add antigravity --write
xmemo profile status codex
xmemo profile install gemini
xmemo profile install antigravity
xmemo smoke --client codex
xmemo privacy

Enterprise privacy and security defaults

  • No telemetry or analytics.

  • xmemo doctor, xmemo discovery show, and xmemo status do not send tokens.

  • MCP config generated by the CLI references XMEMO_KEY or uses the client's MCP OAuth flow; it does not write token values into project files.

  • The CLI generates one stable non-secret XMEMO_AGENT_INSTANCE_ID per device and stores it in user-scoped config outside git. All agents on the same device share this instance ID.

  • xmemo setup <client> can install a marker-scoped XMemo memory behavior profile for the selected agent. The profile contains instructions only; it never embeds token values.

  • xmemo login stores the issued credential in the user-scoped XMemo CLI config directory, shows the approved account when the server provides it, and does not require extra token configuration afterward.

  • xmemo token add remains available for existing tokens and still avoids project files, shell history, and printed token values.

  • Legacy xmemo token set refuses plaintext credential storage unless --allow-plaintext is explicitly provided.

  • The npm package uses a files whitelist so only bin, src, skills, published plugin metadata/assets, README.md, and LICENSE are published.

Token flow

Recommended personal-user flow:

Copy & paste — that's it
xmemo login
xmemo auth status
xmemo token status --verify

xmemo login uses the hosted device-login flow when the service advertises it: the CLI shows a browser URL and one-time code, the user authorizes in XMemo, and the CLI stores the issued MCP token in the user-scoped credential file. When the service returns approved account metadata, the CLI prints the account label so users can confirm which XMemo account was connected. No manual token setup is needed after a successful xmemo login; xmemo token status --verify is only an optional connectivity check. The CLI waits for the full browser authorization window by default; use --timeout-ms only to shorten or extend that approval window, and --http-timeout-ms only for individual service requests.

Users who already have a token can configure it directly without shell profiles:

Copy & paste — that's it
printf '%s\n' 'your-token' | xmemo token add --from-stdin
xmemo token status --verify

This is the preferred fallback while a hosted service is rolling out device login. It still avoids project files, MCP config files, logs, and chat transcripts.

Tokens should be created by the XMemo website or enterprise console, then stored with xmemo login, xmemo token add, a user environment variable, or an enterprise secret manager:

Copy & paste — that's it
export XMEMO_KEY="your-token"

PowerShell:

Copy & paste — that's it
[Environment]::SetEnvironmentVariable("XMEMO_KEY", "your-token", "User")

Do not commit tokens to source control, MCP config files, .env files, logs, or chat transcripts.

Release model

This repository is the source for the @xmemo/client npm package. Releases should be published from GitHub Actions on tags or GitHub Releases, not from a developer workstation.

Recommended flow:

Copy & paste — that's it
develop -> test -> tag/release -> GitHub Actions -> npm publish --provenance

Package boundary

Included in npm:

Copy & paste — that's it
bin/
src/
README.md
LICENSE

Excluded from npm:

Copy & paste — that's it
.github/
test/
coverage/
server code
database migrations
deployment files
logs
local state
secrets