XMemo CLI

XMemo CLI

@xmemo/client is the privacy-first command line entry point for XMemo clientsetup. It is intentionally small: the npm package contains only the CLI andsetup helper code needed on a user's machine.

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

The XMemo server, database, token registry, deployment files, logs, andinternal 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-runto 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 setup gemini
xmemo setup gemini --dry-run
xmemo setup antigravity
xmemo setup antigravity --dry-run
xmemo setup kiro
xmemo setup kiro --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'sMCP OAuth flow; it does not write token values into project files.
• The CLI generates one stable non-secret XMEMO_AGENT_INSTANCE_ID per deviceand stores it in user-scoped config outside git. All agents on the same deviceshare this instance ID.
• xmemo setup <client> can install a marker-scoped XMemo memory behaviorprofile for the selected agent. The profile contains instructions only; itnever embeds token values.
• xmemo login stores the issued credential in the user-scoped XMemo CLIconfig 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 avoidsproject 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, andthe CLI stores the issued MCP token in the user-scoped credential file. When theservice returns approved account metadata, the CLI prints the account label sousers can confirm which XMemo account was connected. No manual token setup isneeded after a successful xmemo login; xmemo token status --verify is onlyan optional connectivity check. The CLI waits for the full browser authorizationwindow by default; use --timeout-ms only to shorten or extend that approvalwindow, 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 devicelogin. It still avoids project files, MCP config files, logs, and chattranscripts.

Tokens should be created by the XMemo website or enterprise console, thenstored with xmemo login, xmemo token add, a user environment variable, or anenterprise 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, orchat transcripts.

Hosted discovery setup

Hosted setup uses the XMemo public discovery contracts. The CLI readssecret-free discovery and onboarding status documents, then tells the user wherethe 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 Authorizationheader. Token creation still happens in the website or enterprise console; thepublic service discovery document does not return token values.

The hosted default service/base URL is https://xmemo.dev, so normal users donot need to type a service address. The MCP endpoint is discovered from thatbase URL and written as https://xmemo.dev/mcp; https://mcp.xmemo.dev is notthe current canonical setup URL. Use --url <service-url> or XMEMO_URL onlyfor private, enterprise, or self-hosted deployments. MEMORY_OS_URL remainsaccepted 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 gemini
xmemo setup antigravity

xmemo setup <client> is the unified setup entry point. For write-capableclients, it applies the user-scoped config directly; use --dry-run to previewwithout writing. Codex/Cursor configs reference XMEMO_KEY; OAuth-nativeclients such as Gemini CLI and Antigravity use the client's MCP OAuth flowinstead. No generated config embeds a token value. Write-capable client configsalso include stable non-secret agent identity headers where the client formatsupports them. --yes remains accepted for Codex and Cursor as a compatibilityno-op.

After writing MCP config, xmemo setup <client> prompts:

Write XMemo memory behavior profile to <path>? [Y/n]

The default is Y, so pressing Enter writes a marker-scoped profile that nudgesthe agent to recall/search XMemo at the start of non-trivial work and rememberhigh-signal decisions after meaningful changes. Use n or --no-profile toconfigure MCP only. Use --dry-run to preview without writing config or profilefiles, and --profile-target <path> to choose a different behavior profiletarget.

Default behavior profile targets:

codex       ./AGENTS.md
cursor      ~/.cursor/memory-profile.md
gemini      ~/.gemini/GEMINI.md
antigravity ~/.gemini/antigravity/MEMORY.md

Antigravity 2.0 currently uses the lower-level MCP writer because its stableuser config path is separate from the original Antigravity profile. Preview thegenerated OAuth-first config with:

xmemo mcp add antigravity2 --url https://xmemo.dev

Write it to the default Antigravity 2.0 config path with:

xmemo mcp add antigravity2 --url https://xmemo.dev --write

The generated config uses https://xmemo.dev/mcp, contains no bearer token, andexpects Antigravity 2.0 to complete MCP OAuth in the browser on first use.XMEMO_AGENT_INSTANCE_ID is a device-level identifier shared by all agents onthe same machine, generated and stored when --write is used.

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
gemini      ~/.gemini/settings.json
antigravity ~/.gemini/antigravity/mcp_config.json
antigravity2 ~/.antigravity2/mcp.json
kiro        ~/.kiro/settings/mcp.json

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

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

Codex, Cursor, Copilot CLI, Gemini CLI, Antigravity, and Kiro have write-capable setuphelpers. Antigravity 2.0 is write-capable through xmemo mcp add antigravity2 --write.Other client writes should only be added after their official user-scoped configformat 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 writesa local proxy server entry there:

xmemo login
xmemo setup copilot
xmemo mcp proxy

xmemo setup copilot writes XMemo to Copilot CLI's user MCP config anddoes not include token or identity headers. Use xmemo setup copilot --dry-runto preview without writing. xmemo mcp proxy reads the token saved byxmemo login or xmemo token add --from-stdin, adds the XMemo bearer token andlocal agent identity, then forwards requests to https://xmemo.dev/mcp. IfCopilot CLI is already open, reload MCP config or restart Copilot CLI aftersetup.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, by default,installs the XMemo Codex behavior profile into the current project's AGENTS.mdbetween these markers. Use xmemo setup codex --dry-run to preview withoutwriting or xmemo setup codex --no-profile to skip the behavior profile.

<!-- 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, includes the non-secretX-Memory-OS-Agent-ID / X-Memory-OS-Agent-Instance-ID attribution headers,and does not include the token value.

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-signaldecisions and fixes, and never store secrets. xmemo smoke --client codexchecks the local Codex TOML config for the XMemo MCP server,bearer_token_env_var = "XMEMO_KEY", token presence in the environment, andabsence of embedded token values.

Cursor

Cursor marketplace plugin assets live in .cursor-plugin/marketplace.json andplugins/xmemo/. The marketplace plugin is OAuth-first and its mcp.json storesonly https://xmemo.dev/mcp; it must not contain Authorization, Bearer, orXMEMO_KEY.

Recommended Cursor setup:

xmemo setup cursor

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

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

The CLI refuses to overwrite an existing XMemo, memory_os, or memory-osMCP server entry. Edit the config manually if you need to rotate the endpoint.Cursor configs includeX-Memory-OS-Agent-ID and X-Memory-OS-Agent-Instance-ID; the instance ID isnon-secret and stored under the user's XMemo CLI config directory. By default,the setup prompt also installs a Cursor behavior profile at~/.cursor/memory-profile.md; answer n or pass --no-profile to skip it.Use this direct-key setup only for local/manual installs where Cursor OAuth isunavailable; public plugin submission should use the OAuth-first plugin config.

Gemini CLI

Recommended Gemini CLI setup:

xmemo setup gemini

setup gemini merges an XMemo MCP server into Gemini CLI's user settings at~/.gemini/settings.json. It writes a remote HTTP server using Gemini'shttpUrl key plus X-Memory-OS-Agent-ID and X-Memory-OS-Agent-Instance-IDheaders. Use xmemo setup gemini --dry-run to preview without writing.

Unlike Codex/Cursor, the Gemini config carries no token: authentication usesGemini CLI's built-in MCP OAuth flow (a one-time browser login on first use).This is deliberate — Gemini redacts environment variables matching*KEY*/*TOKEN*/*AUTH* during header expansion, so an ${XMEMO_KEY}reference would not survive. OAuth avoids storing any secret in the config andstill grants the full XMemo tool profile. After setup, restart Gemini CLI andrun /mcp (or the first XMemo tool call) to complete the OAuth login. Bydefault, the setup prompt also installs a Gemini behavior profile at~/.gemini/GEMINI.md; answer n or pass --no-profile to skip it.

The CLI refuses to overwrite an existing XMemo, memory_os, or memory-osMCP server entry. Edit the config manually if you need to rotate the endpoint.

Antigravity

Recommended Antigravity setup:

xmemo setup antigravity

setup antigravity merges an XMemo MCP server into Antigravity's user MCP configat ~/.gemini/antigravity/mcp_config.json. It writes Antigravity'sserverUrl shape plus X-Memory-OS-Agent-ID andX-Memory-OS-Agent-Instance-ID headers. Like Gemini CLI, the config carriesno token: restart Antigravity and complete the MCP OAuth flow on first use.By default, the setup prompt also installs an Antigravity behavior profile at~/.gemini/antigravity/MEMORY.md; answer n or pass --no-profile to skip it.

The lower-level equivalent is:

xmemo mcp add antigravity --write

Use xmemo setup antigravity for normal installs because it performs discoveryand chooses the recommended Antigravity path automatically. Usexmemo mcp add antigravity --write when you want the generic MCP writerdirectly, for example with --url or --config in advanced/multi-client setup.The CLI refuses to overwrite an existing XMemo, memory_os, or memory-osMCP server entry. Edit the config manually if you need to rotate the endpoint.

Kiro

Recommended Kiro setup:

xmemo setup kiro

setup kiro merges an XMemo MCP server into Kiro's user MCP config at~/.kiro/settings/mcp.json. It writes a remote HTTP server using Kiro'sstandard url key plus X-Memory-OS-Agent-ID and X-Memory-OS-Agent-Instance-IDheaders. Use xmemo setup kiro --dry-run to preview without writing.

The Kiro config includes Authorization: Bearer ${env:XMEMO_KEY} soauthentication uses the environment variable approach. Set your XMemo token with:

xmemo login
# or
printf '%s\n' 'your-token' | xmemo token add --from-stdin

After setup, restart Kiro or reload MCP servers for the changes to take effect.The CLI refuses to overwrite an existing XMemo, memory_os, or memory-osMCP server entry. Edit the config manually if you need to rotate the endpoint.

Antigravity 2.0

Recommended Antigravity 2.0 setup:

xmemo mcp add antigravity2 --write

Use a dry preview first if you want to inspect the exact JSON before writing:

xmemo mcp add antigravity2

Antigravity 2.0 uses a separate config path from the original Antigravityprofile. The default write target is ~/.antigravity2/mcp.json; on Windows theserver-side config contract also documents %APPDATA%\\Antigravity 2.0\\mcp.jsonas the Antigravity 2.0 user config location. Pass --config <path> when youwant to write to a specific file.

The generated XMemo entry uses hosted HTTP MCP:

{
  "mcpServers": {
    "XMemo": {
      "type": "http",
      "url": "https://xmemo.dev/mcp"
    }
  }
}

No token value is written. Restart Antigravity 2.0 after setup and complete theMCP OAuth browser flow on first use. If you use --write, the CLI also preparesa device-level XMEMO_AGENT_INSTANCE_ID shared by all agents on the samemachine so XMemo can attribute activity consistently without embedding secrets.

Release model

This repository is the source for the @xmemo/client npm package. Releasesshould be published from GitHub Actions on tags or GitHub Releases, not from adeveloper 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