CLI

xmemcli is the xmemory command-line client — the fastest way to onboard (authenticate, design a schema, create an instance) and to read, write, and evolve memory from a terminal or a script. It talks to the HTTP API at https://api.xmemory.ai.

For agents that call xmemory as tools during a task, use the MCP server. xmemcli is the onboarding / control plane; MCP is the runtime data plane — they complement each other.

API key: To use xmemory APIs or integrations, you need an API key. Get one from the xmemory console, or run xmemcli auth login (below). Never share your API key publicly.

Install

Install it as a persistent tool (recommended for regular use — the examples below call xmemcli directly):

uv tool install xmemcli     # or: pip install xmemcli
xmemcli help

Or run it with no install — handy for a quick try, CI, or letting an agent invoke it — via uv’s uvx (prefix any command with uvx):

uvx xmemcli help

Add the agent skill (optional)

xmemcli ships an agent skill that teaches AI coding agents to use xmemory. Install it into your agents (Claude Code, Cursor, Codex, Gemini CLI, and more) with the skills installer:

npx skills add xmemory-ai/xmemory-skill

The agent then uses xmemory on its own — listing available instances, checking what’s already stored before redoing work, and writing down what it learns for next time.

Authenticate

The easiest path is the browser login (PKCE) — best run while you’re onboarding xmemory in the Console, so the handoff lands in .xmemrc.json with almost no extra steps:

xmemcli auth login       # opens the browser; --no-browser for headless
xmemcli auth status

Alternatively, create an API key in the Console. Prefer keeping it in a .xmemrc.json (which auth login writes for you) over the environment — a $XMEM_API_KEY env var also works and is handy for CI. xmemcli resolves credentials --api-key → $XMEM_API_KEY → the nearest .xmemrc.json (walking up from the current directory). Add .xmemrc.json to .gitignore — it holds secrets.

Onboard: create an instance from a description

xmemory stores data in typed instances governed by a schema. Describe the domain, let xmemcli synthesize the schema, then create the instance:

xmemcli xmd generate "Track contacts with name, email, company, and notes." -o schema.yml
xmemcli xmd validate schema.yml
xmemcli instance create --name contacts --description "People we talk to" --schema-file schema.yml
# → save the returned UUID:
export XMEM_INSTANCE_ID="<uuid from output>"

List the memory stores available to you any time:

xmemcli org list instances

Read and write

write and read act on the active instance — the XMEM_INSTANCE_ID you exported above (they take no instance argument, unlike control-plane commands such as schema/instance, which name the instance explicitly).

xmemcli write "Alice Johnson works at Acme Corp. Her email is alice@acme.com."
xmemcli read "What is Alice's email?"

# bulk / non-blocking:
xmemcli write --no-wait "..."      # returns a write_id
xmemcli write-status <write_id>

Writes take plain language — xmemory maps the text onto the instance’s schema.

Evolve the schema

When the domain grows, change the schema before writing facts that depend on it:

xmemcli schema get "$XMEM_INSTANCE_ID" -o schema.yml
xmemcli xmd enhance schema.yml "Add a Contact.phone field." -o schema-v2.yml
xmemcli xmd validate schema-v2.yml
xmemcli schema dry-run "$XMEM_INSTANCE_ID" --schema-file schema-v2.yml   # preview the migration
xmemcli schema update "$XMEM_INSTANCE_ID" --schema-file schema-v2.yml    # apply it

xmemcli help and xmemcli help <topic> document every command.