Agent-guided setup

This page is designed for an AI agent to read and follow while setting up xmemory for you. The instructions are generic: they contain no instance ids, names, or data. To connect a specific instance, the agent needs its id from the xmemory console or from the response that created it.

xmemory is a first-party memory store: it holds the data you explicitly save to your xmemory instance, in xmemory’s own backend. It does NOT read the assistant’s built-in memory, your past chat history, or your files, email, or cloud drives — it only stores and returns what is written to this instance.

Pick your surface:

Surface	What installs	Session-start context
Claude Code	Plugin (skills, hooks) and the xmemcli CLI	Yes, for instances bound autoload
Codex	Plugin (skills, hooks) and the xmemcli CLI	Yes, once hooks are enabled and trusted
Claude Desktop and claude.ai	Custom connector	No
ChatGPT	Custom MCP server (a “plugin”)	No

Every surface reaches the same remote MCP server at https://mcp.xmemory.ai.

What you need

• An xmemory account and at least one instance. The console creates both; so does the agent onboarding prompt, which walks an agent through installing the CLI, signing in by email, and creating a first instance. This page starts one step later, from an instance that already exists.
• The instance id (a UUID) of whatever you want to connect.
• For Claude Code: the claude CLI. For Codex: the codex CLI.

When no instance exists yet, the agent has three ways to shape one: start from a ready-made template (xmemcli instance templates lists them; xmemcli instance create --template <id> creates one with no schema generated), use the description-first flow — tell it what the memory should retain and answer, and xmemory generates the XMD schema — or author and validate the XMD directly. A template is the quickest start when one fits; direct authoring remains available whenever exact control is useful.

None of the paths below asks you to paste an API key into a client configuration file. On Claude Code and Codex the xmemcli CLI signs in once — you approve one emailed link — and every instance entry then connects through it. On the connector surfaces, and for a direct entry on a machine that cannot install the CLI, connecting opens xmemory’s own authorization form in the browser, which asks for an xmemory API key from the console’s API Keys page; the key stays with xmemory rather than being written into the client. The CLI keeps its own credential on disk; see security posture.

---

Claude Code

1. Install the plugin

claude plugin marketplace add xmemory-ai/claude-code-plugin
claude plugin install xmemory@xmemory-ai

The equivalent inside a session is /plugin marketplace add xmemory-ai/claude-code-plugin followed by /plugin install xmemory@xmemory-ai.

Restart Claude Code, or run /reload-plugins. The plugin ships three skills:

Component	What it does
/xmemory:connect	Discovers your instances and writes the project binding
/xmemory:doctor	Reports which parts of the setup work, and what to do about the rest
/xmemory:xmemory-memory	Tells Claude when to reach for the memory tools

It also installs a SessionStart hook and a PreCompact hook. Both are POSIX sh with no dependencies, and neither can fail a session — see what the install asks of you.

The plugin bundles no MCP entry. The connection is registered per instance in the next step, so /mcp never lists a connection you did not ask for.

2. Connect an instance

An MCP entry holds one connection bound to one instance, so each instance you use gets its own named entry. Registering two instances under one name silently replaces the first, so name each entry xmemory- followed by the first eight characters of its instance id — the same name xmemcli instance setup prints for that instance. Following this page and following the per-instance instructions then produce one entry, not two under different names.

Check the local CLI first. This reports version and authenticated together, contacts nothing, and exits 0 either way — read the fields rather than the exit code:

xmemcli --json status

If the shell says xmemcli is not found, or version is below 0.0.9 — the release the emailed sign-in below needs — install or upgrade it:

uv tool install --upgrade xmemcli

Where uv is missing, pipx install xmemcli installs it and pipx upgrade xmemcli upgrades it. If the install warns that its directory is not on your PATH, run uv tool update-shell and open a new terminal, so later sessions and the plugin’s session-start hook find xmemcli. Until then, use the absolute path the install printed, in double quotes, wherever these steps say xmemcli.

If authenticated is false, or rc_file names a file other than ~/.xmemrc.json, sign in. It sends you one email, and approving it is the only step:

xmemcli auth login --rc-dir "$HOME" --email <your-email>

--rc-dir "$HOME" puts the key in ~/.xmemrc.json wherever you run it, and both the connection below and the preload hook read it there. If rc_file named a file inside a project, delete that file once this succeeds: the connection reads the nearest file, so a project credential keeps shadowing the home one, which is the only one the hook reads. Without --email, xmemcli auth login signs in through the browser instead.

With xmemcli installed and signed in (0.0.7 or newer), register through it. The credential is read from the CLI’s own configuration on every connection, so an entry written today still works in a session opened next week on a machine whose environment carries nothing:

claude mcp add xmemory-<FIRST8> -- xmemcli mcp <WORK_INSTANCE_ID>

mcp arrived in 0.0.7. An older client accepts the command and then cannot run it, leaving a server that never starts, which is why an older client is upgraded first.

Only on a machine that cannot install or upgrade the CLI, register against the endpoint directly. Its authorization page asks for an xmemory API key from the console’s API Keys page:

claude mcp add --transport http xmemory-<FIRST8> https://mcp.xmemory.ai/instance/<WORK_INSTANCE_ID>

The direct form is also what a hand-written .mcp.json holds:

{
  "mcpServers": {
    "xmemory-<WORK_FIRST8>": { "type": "http", "url": "https://mcp.xmemory.ai/instance/<WORK_INSTANCE_ID>" },
    "xmemory-<PERSONAL_FIRST8>": { "type": "http", "url": "https://mcp.xmemory.ai/instance/<PERSONAL_INSTANCE_ID>" }
  }
}

Each direct entry authorizes on its own, with /mcp or claude mcp login xmemory-<FIRST8>, and gives the preload hook no credential. An entry added mid-session connects after a restart.

Creating, listing and reshaping instances is the admin plane, and the plugin registers no entry for it either — the CLI covers it (xmemcli instance create, xmemcli org list instances, xmemcli xmd generate), or add the admin server yourself as the Claude guide shows: claude mcp add --transport http xmemory-admin https://mcp.xmemory.ai/admin. It is a separate sign-in because it includes destructive operations.

3. Bind instances to a project

A binding records which instances an agent working in a directory should know about, and how eagerly to engage each one. Ask Claude to “connect xmemory to this project” and the connect skill discovers your instances and writes .xmemory.json.

Tier	Meaning
autoload	Pull this instance’s context at the start of every session in this directory
available	Default. Do not preload; engage it when the work matches
off	Bound but dormant — silences an instance inherited from a wider scope

Two files are merged like git config, with the nearer one winning field by field: .xmemory.json at the project root, and ~/.xmemory.json for instances personal to you.

Binding is local bookkeeping. It does not grant access, move data, or change anything on the server — and binding three instances does not make all three readable over MCP at once, which is what the per-instance server entries above are for.

4. Preload bound instances at session start

Instances bound autoload are pulled into the session by the SessionStart hook, which runs in a separate process and so cannot reach the MCP sign-in. It needs its own credential, which is what xmemcli provides. If you signed it in in step 2, this is already done; otherwise:

uv tool install --upgrade xmemcli
xmemcli auth login --rc-dir "$HOME" --email <your-email>

The same command upgrades an older client already on the machine. The hook reads bindings and fetches context through xmemcli binding and xmemcli context, and the per-instance MCP transport is xmemcli mcp — all three are in 0.0.7, so an install left at an earlier version preloads nothing. /xmemory:doctor reports the version it finds.

Everything else — binding, and the instance context that arrives with the MCP connection — works without it. A binding written today starts preloading the moment the CLI is installed.

5. Check the setup

/xmemory:doctor

Five things have to line up and they fail independently: the MCP server registered, the connection authorized, a binding present, xmemcli installed and signed in, and no hand-wired hooks duplicating the plugin’s. The doctor reports all five and names the remaining step.

If you already wired xmemory into Claude Code by hand, installing the plugin does not replace your hooks — both run, and context is injected twice. Set XMEMORY_DISABLE_HOOKS=1 to stand the plugin’s hooks down and keep your own; the skills and your MCP entries are unaffected.

---

Codex

Codex installs the same package as Claude Code. One repository carries two entry points, so the skills and the session-start hook are the ones described above, not a separate build:

codex plugin marketplace add xmemory-ai/claude-code-plugin
codex plugin add xmemory@xmemory-ai

Start a new session after installing.

Hooks are gated on this surface

Codex lifecycle hooks require [features] hooks = true, and their definitions must also be reviewed and trusted through /hooks. Both are deliberate, and both are yours to grant. Until they are, nothing runs at session start and the plugin’s managed block in the global AGENTS.md carries the instructions instead — a file Codex always loads. The doctor skill checks the two states separately and names whichever is missing.

Connect an instance

Installing the package and pointing it at an instance are separate acts. Codex takes stdio servers, so the same two forms apply as on Claude Code.

Check the local CLI first, as above — xmemcli --json status reports version and authenticated and contacts nothing. If the shell does not find it, or it is older than 0.0.9, install or upgrade it; if it is signed out, or its rc_file is not ~/.xmemrc.json, sign in as above:

uv tool install --upgrade xmemcli
xmemcli auth login --rc-dir "$HOME" --email <your-email>

With xmemcli installed and signed in (0.0.7 or newer):

codex mcp add xmemory-<FIRST8> -- xmemcli mcp <INSTANCE_ID>

Only on a machine that cannot install or upgrade the CLI, register directly:

codex mcp add xmemory-<FIRST8> --url https://mcp.xmemory.ai/instance/<INSTANCE_ID>
codex mcp login xmemory-<FIRST8>

codex mcp login opens xmemory’s authorization page, which asks for an xmemory API key from the console; the key is not written into config.toml. Restart Codex and run /mcp to confirm the server is connected and its tools are listed.

The naming rule is the one above: xmemory- plus the first eight characters of the instance id, matching what xmemcli instance setup prints. Two instances sharing a name means one entry, and the second silently replaces the first.

For a headless setup that sends a fixed API key with every request, see the Codex guide.

---

Claude Desktop and claude.ai

Open Customize → Connectors, open the Add menu beside the Connectors heading — the same menu on claude.ai and Claude Desktop — choose Add custom connector, and give it this URL:

https://mcp.xmemory.ai/instance/<INSTANCE_ID>

The instance path binds the connector to that instance up front. To pick the instance during sign-in instead, use the root URL https://mcp.xmemory.ai/.

Click Connect and complete the browser sign-in. That form asks for an xmemory API key, which you create on the API Keys page of the console; it has one field and no other way through. Enable the connector for a conversation to use its tools. The connector then appears on the mobile apps too. There are no plugins or hooks on these surfaces, so the connection itself is what binds the instance. The Claude guide has screenshots of the dialog and of the per-tool permissions screen; the menu path above is the current one.

---

ChatGPT

On chatgpt.com, turn on Developer mode under Settings → Security and login first: until it is on, the Plugins page has nothing on it to add a custom server with. Then open Plugins (a top-level item in the left sidebar), choose +, give it a name, keep Connection on Server URL and paste the same instance URL, leave Authentication on OAuth, and confirm the risk notice to create it.

The ChatGPT desktop app takes a different route — Settings → Plugins → MCPs → + Add server, where Type has to be set to Streamable HTTP, because the form opens on STDIO and its next field is a shell command.

Complete the browser sign-in when the connector asks for it; it asks for an xmemory API key from the console’s API Keys page. Then mention it by the name you gave it to use its tools in a chat. The ChatGPT guide covers the Codex CLI and the admin and status connection types; for the connector itself, the routes above are the current ones.

---

What the install asks of you

Stated up front rather than discovered halfway through:

• Approving commands. When an agent runs the install for you, it asks before each command.
• One sign-in for the CLI. On Claude Code and Codex, the CLI’s emailed sign-in sends one email, and approving it signs the CLI in; every entry that runs xmemcli mcp reuses that credential, and so does the session-start hook. A connector on Claude Desktop, claude.ai and ChatGPT, and a direct entry, instead ask for an xmemory API key from the console once per connection. Data and admin planes are separate connections.
• Choosing tool groups. On a connector or a direct entry, the authorization screen lets you pick which tools to authorize. Core memory and schema-evolution suggestions are granted by default; schema management — which can replace a schema — starts unchecked.
• Hooks, on Claude Code and Codex. Installing the plugin enables them on Claude Code; on Codex they additionally wait on [features] hooks = true and your /hooks approval. A directory with no .xmemory.json gets silence: the SessionStart hook exits without a network call. Where something is bound autoload, it fetches that instance’s context. The PreCompact hook is a reminder to the agent to persist durable facts before context is summarized away — it has no model and sends nothing itself.

A missing CLI, an expired credential, or an unreachable API costs context, never the session. Both hooks exit successfully and say in one line what went wrong, so an agent can tell “nothing saved” from “could not reach it”.

Security posture

• No static tokens in client configuration. A direct entry authorizes with OAuth 2.1 and PKCE on xmemory’s own page in the browser, where you enter an xmemory API key that is not written into the client; an entry that runs xmemcli mcp stores nothing in the client either — the CLI supplies its own credential per connection, from ~/.xmemrc.json.
• The two planes authorize separately. Reading and writing one instance’s data is a different consent from creating, managing, or deleting instances.
• An instance id is an identifier, not a credential. It appears in URLs and committed files. Access is decided by the credential presented, never by knowledge of the id.
• .xmemory.json holds no secrets and is meant to be committed and shared with your team. .xmemrc.json is not — it sits in the same directory and holds a plaintext API key. xmemcli context refuses to fetch with a credential found inside a checkout, so committing one both exposes the key and disables preloading.
• A committed binding shares a list, not data. When a teammate opens a session there, those instances are fetched with their credential, so the server returns only what their own access already reaches. An instance they never listed for themselves is flagged in their session as having come from the project.
• Per-instance setup and context reads are authenticated and audit-logged. This page is static and carries none of that content.

Machine-readable copies of this page

• Markdown: https://xmemory.ai/install/index.html.md
• Site index for agents: llms.txt, llms-full.txt
• Install coordinates as JSON: /.well-known/xmemory.json
• Bootstrap prompt for a reader with no account yet: /agent-onboarding-prompt.txt