# Install xmemory in your agent

> Install the xmemory plugin or connector in Claude Code, Codex, Claude Desktop, claude.ai, or ChatGPT, bind instances to a project, and see what each step asks of you.

Canonical page: https://xmemory.ai/install/

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](https://console.xmemory.ai)
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](#claude-code) | Plugin (MCP servers, skills, hooks) | Yes, for instances bound `autoload` |
| [Codex](#codex) | Plugin (MCP servers, skills, hooks) | Yes, once hooks are enabled and trusted |
| [Claude Desktop and claude.ai](#claude-desktop-and-claudeai) | Custom connector | No |
| [ChatGPT](#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](https://console.xmemory.ai)
  creates both; so does the [agent onboarding prompt](https://xmemory.ai/agent-onboarding-prompt.txt), 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](#4-preload-bound-instances-at-session-start) keeps its own credential on disk; see
[security posture](#security-posture).

---

## Claude Code

### 1. Install the plugin

```bash
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](#what-the-install-asks-of-you).

### 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:

```bash
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:

```bash
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:

```bash
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:

```json
{
  "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

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`](https://xmemory.ai/cli/) provides:

```bash
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

```
/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

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:

```bash
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.

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

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

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

```bash
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](https://xmemory.ai/codex/).

---

## 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](https://xmemory.ai/claude/) 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](https://xmemory.ai/chatgpt/) 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.
- **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

- **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

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