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 code needed on a user's machine.

@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.

Install

npm install -g @xmemo/client

Upgrade an existing global install:

xmemo update

This runs npm install -g @xmemo/client@latest. Use xmemo update --dry-run to print the exact command without changing anything.

Commands

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 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 profile status codex
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; it does not write token values into project files.
• The CLI generates one stable non-secret XMEMO_AGENT_INSTANCE_ID per local client profile and stores it in user-scoped config outside git.
• 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, README.md, and LICENSE are published.

Token flow

Recommended personal-user flow:

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:

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:

export XMEMO_KEY="your-token"

PowerShell:

[Environment]::SetEnvironmentVariable("XMEMO_KEY", "your-token", "User")

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

Hosted discovery setup

Hosted setup uses the XMemo public discovery contracts. The CLI reads secret-free discovery and onboarding status documents, then tells the user where the API, MCP endpoint, docs, and any server-advertised onboarding links are.

xmemo doctor
xmemo discovery show
xmemo setup

Discovery requests do not send XMEMO_KEY or any Authorization header. Token creation still happens in the website or enterprise console; the public service discovery document does not return token values.

The hosted default service/base URL is https://xmemo.dev, so normal users do not need to type a service address. The MCP endpoint is discovered from that base URL and written as https://xmemo.dev/mcp; https://mcp.xmemo.dev is not the current canonical setup URL. Use --url <service-url> or XMEMO_URL only for private, enterprise, or self-hosted deployments. MEMORY_OS_URL remains accepted as a compatibility alias.

Generate and write a client config from discovery:

xmemo setup codex
xmemo setup codex --url "https://your-private-service.example"
xmemo setup cursor
xmemo setup copilot

xmemo setup <client> is the unified setup entry point. For write-capable clients, it applies the user-scoped config directly; use --dry-run to preview without writing. Generated config references XMEMO_KEY; it does not embed the token value. Write-capable client configs also include stable non-secret agent identity headers where the client format supports them. --yes remains accepted for Codex and Cursor as a compatibility no-op.

xmemo setup codex is the recommended Codex path. It writes the Codex MCP config and installs the profile into the current project's AGENTS.md marker block. Use --dry-run to preview, --profile-target <path> to choose a different project instruction file, or --no-profile to configure MCP only.

MCP setup

List supported client generators:

xmemo mcp list

Current write-capable clients:

codex   ~/.codex/config.toml
cursor  ~/.cursor/mcp.json
copilot ~/.copilot/mcp-config.json

For clients without a verified user-scoped write path, generate a read-only template and apply it manually after review:

xmemo mcp config --client generic --base-url "https://your-private-service.example" --json

Codex, Cursor, and Copilot CLI have write-capable setup helpers. Other client writes should only be added after their official user-scoped config format is verified.

Copilot CLI

Copilot CLI has /mcp management and reads user MCP configuration from ~/.copilot/mcp-config.json (or $COPILOT_HOME/mcp-config.json). XMemo writes a local proxy server entry there:

xmemo login
xmemo setup copilot
xmemo mcp proxy

xmemo setup copilot writes memory-os to Copilot CLI's user MCP config and does not include token or identity headers. Use xmemo setup copilot --dry-run to preview without writing. xmemo mcp proxy reads the token saved by xmemo login or xmemo token add --from-stdin, adds the XMemo bearer token and local agent identity, then forwards requests to https://xmemo.dev/mcp. If Copilot CLI is already open, reload MCP config or restart Copilot CLI after setup. If you specifically want the older environment-variable template, run:

xmemo mcp config --client copilot-cli --remote-env

Codex

Recommended Codex setup:

xmemo setup codex
xmemo smoke --client codex

setup codex writes the MCP config to user-scoped Codex config and installs the XMemo Codex behavior profile into the current project's AGENTS.md between these markers. Use xmemo setup codex --dry-run to preview without writing.

<!-- memory-os:codex-profile:start -->
<!-- memory-os:codex-profile:end -->

Repeat installs update only that marker block. Remove it with:

xmemo profile uninstall codex

Advanced: generate a Codex MCP config snippet without touching files:

xmemo mcp add codex --url "$XMEMO_URL"

Write it to the default Codex config path:

xmemo mcp add codex --url "$XMEMO_URL" --write

The generated config references XMEMO_KEY and does not include the token value. Codex custom identity headers are not written until the CLI format is verified to support them.

Codex MCP-depth checks:

xmemo mcp profile codex
xmemo profile install codex --dry-run
xmemo profile install codex
xmemo profile status codex
xmemo smoke --client codex

xmemo mcp profile codex prints the recommended memory behavior profile: recall/search at the start of non-trivial tasks, write back high-signal decisions and fixes, and never store secrets. xmemo smoke --client codex checks the local Codex TOML config for the memory_os MCP server, bearer_token_env_var = "XMEMO_KEY", token presence in the environment, and absence of embedded token values.

Cursor

Recommended Cursor setup:

xmemo setup cursor

setup cursor merges the Cursor MCP config into the default Cursor user config path. Use xmemo setup cursor --dry-run to preview without writing. The lower-level equivalent remains:

xmemo mcp add cursor --url "$XMEMO_URL" --write

The CLI refuses to overwrite an existing memory_os MCP server entry. Edit the config manually if you need to rotate the endpoint. Cursor configs include X-Memory-OS-Agent-ID and X-Memory-OS-Agent-Instance-ID; the instance ID is non-secret and stored under the user's XMemo CLI config directory.

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:

develop -> test -> tag/release -> GitHub Actions -> npm publish --provenance

Package boundary

Included in npm:

bin/
src/
README.md
LICENSE

Excluded from npm:

.github/
test/
coverage/
server code
database migrations
deployment files
logs
local state
secrets