Skip to content
xmemoryxmemory Website

Install xmemory in your agent

This page is generic: it contains no instance ids, names, or data. To connect a specific instance you need its id, which comes 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 (MCP servers, skills, hooks) Yes, for instances bound autoload
Codex Plugin (MCP servers, skills, hooks) 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

Section titled “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.

None of the paths below asks you to paste an API key into a client configuration file — each connection signs in through a browser. On the two connector surfaces that browser form is xmemory’s own, and it 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 optional CLI in step 4 keeps its own credential on disk; see security posture.

Claude Code

Section titled “Claude Code”

1. Install the plugin

Section titled “1. Install the plugin”
Terminal window
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 registers two MCP servers and three skills:

Component What it does
xmemory MCP server Reads and writes one instance’s data
xmemory-admin MCP server Creates, lists and manages instances and schemas
/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.

2. Authorize the connections

Section titled “2. Authorize the connections”

Run /mcp and authorize xmemory. A browser opens; nothing is pasted anywhere. The xmemory and xmemory-admin servers authorize separately — one working says nothing about the other.

The bundled xmemory entry points at the root URL, so it holds one connection bound to one instance, which you choose in the sign-in screen. To keep several instances live at the same time, add one named server per instance. 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.

Which of the two forms below applies depends on the local CLI, so ask it first. This reports version and authenticated together, contacts nothing, and exits 0 either way — read the fields rather than the exit code, and treat “command not found” as no CLI:

Terminal window
xmemcli --json status

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:

Terminal window
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, so upgrade first with uv tool install --upgrade xmemcli if version is lower.

Without the CLI, register against the endpoint directly and sign in through a browser:

Terminal window
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": { "type": "http", "url": "https://mcp.xmemory.ai/instance/<WORK_INSTANCE_ID>" },
    "xmemory-personal": { "type": "http", "url": "https://mcp.xmemory.ai/instance/<PERSONAL_INSTANCE_ID>" }
  }
}

Each entry authorizes on its own.

3. Bind instances to a project

Section titled “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

Section titled “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:

Terminal window
uv tool install xmemcli
xmemcli auth login

If an older client is already on the machine, upgrade it with uv tool install --upgrade xmemcli. 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

Section titled “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 MCP servers are unaffected.

Codex

Section titled “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:

Terminal window
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

Section titled “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

Section titled “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.

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

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

Without the CLI, register directly and sign in through a browser:

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

codex mcp login opens a browser; no key is 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 authenticates with an API key rather than a browser, see the Codex guide.

Claude Desktop and claude.ai

Section titled “Claude Desktop and claude.ai”

Open Customize → Connectors, open the add menu beside the Connectors heading — a + on claude.ai, an Add menu in 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

Section titled “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

Section titled “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.
  • A browser sign-in per connection. Data and admin planes are separate sign-ins. On Claude Desktop, claude.ai and ChatGPT that form asks for an xmemory API key from the console.
  • Choosing tool groups. The sign-in 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

Section titled “Security posture”
  • No static tokens in client configuration. Every connection above authorizes with OAuth 2.1 and PKCE through a browser.
  • 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

Section titled “Machine-readable copies of this page”