# Installing MeMesh — deterministic steps for an AI agent

This document is for an AI agent installing MeMesh (`@pcircle/memesh`) on its
user's machine. Execute each section exactly, verify with the stated check,
then stop. Once installed, read [AGENTS.md](AGENTS.md) for how to use it.

Facts that hold for every path below:

- Every host reads and writes the **same database**: `~/.memesh/knowledge-graph.db`.
  Installing for a second host adds an access path, not a second memory.
- **Nothing is auto-configured beyond what each step states.** `npm install -g`
  runs **no install scripts** — the package has none, by design (it installs
  fully working even under `--ignore-scripts`). Nothing registers MCP servers
  except the per-host commands in this document.
- Where a host asks for a configured MCP command, use `memesh-mcp` —
  **never `npx -p @pcircle/memesh`**. `npx -p` resolves to the *local* package
  whenever the host's working directory is inside a checkout of this
  repository, silently running that working tree instead of the installed
  release.

## 1. Claude Code (plugin)

Type these in Claude Code's **chat input** — they are Claude Code slash
commands, not shell commands:

```
/plugin marketplace add PCIRCLE-AI/memesh
/plugin install memesh@pcircle-memesh
```

Claude Code wires the MCP server, the auto-capture hooks, and the `/memesh`
skill automatically.

**Verify**: restart Claude Code. A status line beginning `◉ MeMesh` appears at
the top of the next session.

| Failure | Remedy |
|---|---|
| `/plugin marketplace add` fails | The marketplace is fetched as a git clone. Check `git --version` succeeds and github.com is reachable. |
| `/plugin install` says plugin not found | The argument is exactly `memesh@pcircle-memesh` — plugin name `memesh`, marketplace name `pcircle-memesh`. Re-run the marketplace add first. |
| No `◉ MeMesh` line after restart | Run `/plugin` inside Claude Code and confirm the `memesh` plugin is installed and enabled, then restart again. |

The plugin does **not** put a `memesh` command on the shell PATH. For terminal
use — and as a prerequisite for section 4 and for section 3's manual
npm-global alternative — also do section 2. The two installs coexist and share
the database.

## 2. Terminal / CLI (npm global)

Check Node **first** — the floor is 22.13.0 (`node:sqlite` is part of Node
itself; npm only warns on an engine mismatch, so an install onto an old Node
"succeeds" and fails later at runtime):

```
node --version
```

Expected: `v22.13.0` or later. If lower, stop and upgrade Node before
continuing.

```
npm install -g @pcircle/memesh
```

Expected: exits without error; `memesh`, `memesh-mcp` and `memesh-http` are
now in `$(npm prefix -g)/bin/`. No compiler is involved and no install script
runs.

After installation, run `memesh doctor`. To probe the **installed** message MCP plus its bundled host-adapter imports (rather than only checking a manifest hash), opt in explicitly:

```
MEMESH_DOCTOR_PROBE_MESSAGE_CAPABILITY=1 memesh doctor
```

This probe does not exercise a real host session and never wakes a stopped
session. The ordinary Codex path below is the documented bounded native queue
path; `poll`/`watch` and cursor recovery remain available for compatibility and
diagnosis.

Message storage remains owner-controlled. There is no default quota or
automatic pruning. To inspect it after installation:

```bash
memesh message storage report --cutoff 2026-08-01T00:00:00Z
memesh message storage prune --cutoff 2026-08-01T00:00:00Z --batch-size 100
```

The prune command is a dry-run unless `--apply` is supplied. Only old terminal
payload content is tombstoned; unresolved/offline-pending messages and all
lifecycle audit facts are preserved. Set an explicit hard quota for all send
transports with `MEMESH_AGENT_MESSAGE_STORAGE_QUOTA_BYTES=<bytes>`; an
over-quota send is rejected atomically.

### Optional: one-time local host setup

This is separate from MCP setup. It is for the owner of an active local Codex
session, a MeMesh-managed Codex app-server, or a Claude channel. Keep all
files private to that Unix account; do not commit the token or config files.
This secure host-native runtime currently supports macOS and Linux. Windows
can still use core MeMesh, durable messages, and MCP tools, but not this
host-native wakeup path.

Each configured host connection starts the packaged router and retries its
connection when the owner-private socket is absent or refused. Start the router
yourself only when you want to inspect the socket directly:

```bash
umask 077
memesh-router
```

If you start it yourself, it creates the current protocol endpoint
`agent-router-v2.sock` and the shared `agent-router.token` beside the active
MeMesh database (normally `~/.memesh/`) with owner-private permissions. After
an upgrade, an older router may remain on its legacy socket until its old
sessions exit or the machine restarts. Current clients do not attach to it,
and MeMesh does not kill or unlink a live process without durable ownership
proof.

A router that started before an upgrade is caught when a host connects: each
host reports its MeMesh version, and a router that finds the installed version
newer steps aside so the installed one starts. A router from 4.10.11 or
earlier cannot step aside; a host refuses it with `router_outdated` and the
command to stop it (`pkill -f dist/host-runtime/router.js`), and the next
MeMesh session starts the installed router. The exact rules are in the
[agent messaging guide](docs/platforms/agent-messaging.md#one-time-owner-private-local-host-setup).

Check the installed adapter imports and the live socket as distinct facts:

```bash
MEMESH_DOCTOR_PROBE_MESSAGE_CAPABILITY=1 memesh doctor
MEMESH_DOCTOR_PROBE_MESSAGE_ROUTER=1 memesh doctor
```

The router probe does not register a host, send content, or wake a stopped
session. Generate reusable `0600` configs; session identities are not copied
from an active ordinary session.

For an ordinary active local Codex session, install and enable the MeMesh
Codex plugin (section 3), which supplies the packaged SessionStart hook. On the
next startup or resume, that thread registers automatically under the current
project with a thread-scoped principal. First read the exact automatic project
value, then copy its `project` field into the discover command:

```bash
memesh briefing --json
memesh message discover --project '<project from briefing>'
```

No manual host setup is required. If one exact workspace needs a stable named
principal across different Codex threads, create this optional override and
restart Codex in that workspace:

```bash
memesh agent setup codex-session --principal codex-recipient --workspace "$PWD"
```

This stores the configured workspace realpath and principal in
`~/.memesh/hosts/codex-session.json`. On `SessionStart` (`startup` or
`resume`), a short hook validates the Codex thread ID and cwd, then launches an
owner-private detached companion. SessionEnd leaves a bounded 45-second idle
queue window; resume replaces the prior generation, and expiry removes it. A
matching valid override supplies its principal; the project is always the
automatic one for that workspace, same as an ordinary thread there would get.
Another workspace keeps automatic thread-scoped registration. A malformed or
insecure override fails closed. The authenticated router sends the exact
registered thread a short notice through native `codex queue`, never the
message body; the agent fetches the body from the durable inbox and records
intake, and stops if it already has. A notice accepted during the idle window
becomes model-visible when the same thread resumes; a stopped UI is not
awakened.

`host_accept` records only that the local Codex queue accepted that message. It
does not prove an agent read the payload, acknowledged it, or accepted the
work. The notice's routing identifiers, not the body, appear in the `codex queue`
process arguments; still do not send secrets through the native path. If the session is stopped, missing,
or disconnected, MeMesh neither starts nor replaces it; the durable inbox remains
available to scoped fetch, cursor recovery, `poll`, and `memesh message watch`
for audit and diagnosis. Failed exact-session native delivery is not replayed
automatically after a later registration; the sender must retry deliberately.

The following are separate managed-host paths:

No `--project` flag is needed, or read, for routing (#474). Each host derives
its own routing project the same way the automatic Codex project above does:
`codex` from its `--workspace`, `claude` from its own process's working
directory (the directory Claude Code was started in). Pairing Claude Channel
with an automatically registered Codex session in the same repository is
therefore automatic too — start both from the same directory and they land in
the same project with no value to copy between them.

```bash
memesh agent setup codex --principal codex-recipient --workspace "$PWD"
memesh-host-codex --config "$HOME/.memesh/hosts/codex.json"

memesh agent setup claude --principal claude-recipient
# Run the printed `registration_command` (`claude mcp add ... memesh-host-claude ...`) once.
# Start each participating session with the printed research-preview launch command:
claude --dangerously-load-development-channels server:memesh-channel
```

The managed Codex runner owns its app-server and thread; Claude owns its
Channel MCP child. Neither is the ordinary Codex-session path, and neither
attaches to, resumes, or replaces an ordinary stopped host. When no active
registration exists, the message remains durable with no false dispatch or
host acceptance. The package also contains the experimental
`memesh-host-acp` binary for protocol development, but no ACP provider is a
documented native-wakeup integration here.

**Verify**:

```
memesh doctor
```

Expected: a report starting `MeMesh doctor v…` with `Overall: PASS`
(`PASS_WITH_CONCERNS` is also functional), exit code 0.

| Failure | Remedy |
|---|---|
| `command not found: memesh` | npm's global bin dir is not on PATH. Run `npm prefix -g`, append `/bin` to its output, and add that directory to PATH. |
| `No such built-in module: node:sqlite` | The running Node is older than 22.13.0. Upgrade Node, then re-run `memesh doctor`. |
| `EACCES` during `npm install -g` | The global prefix is not user-writable. Use a user-level Node (nvm/fnm), or `npm config set prefix ~/.npm-global` and add `~/.npm-global/bin` to PATH, then re-install. |
| `Overall: FAIL` (exit code 1) | The report names the failing check and prints the fix next to it. Apply that fix and re-run `memesh doctor`. |

Only if Claude Code is used **without** the section-1 plugin (the plugin wires
hooks itself — skip this if section 1 is done):

```
memesh install-hooks
memesh doctor
```

## 3. Codex CLI

Install from the Codex plugin marketplace for zero-config MCP tools and the
SessionStart/SessionEnd companion lifecycle:

```
codex plugin marketplace add PCIRCLE-AI/memesh
codex plugin add memesh@pcircle-memesh
```

The plugin manifest starts its bundled `dist/mcp/server.js` directly from the
plugin cache. It does not need a global `memesh-mcp` command or a manual
`codex mcp add` entry.

**Verify**:

```
codex mcp list
```

Expected: `memesh` is listed as enabled.

### Manual npm-global alternative

If you installed section 2 instead of the Codex plugin, register the global
stdio command manually:

```
codex mcp add memesh -- memesh-mcp
```

This writes `[mcp_servers.memesh]` into `~/.codex/config.toml`.

### Refresh a stale plugin cache

If the configured marketplace snapshot is stale, refresh it and re-stage the
plugin. `codex plugin add` replaces the installed cache atomically, so do not
remove the working plugin first:

```
codex plugin marketplace upgrade pcircle-memesh
codex plugin add memesh@pcircle-memesh
```

| Failure | Remedy |
|---|---|
| `command not found: codex` | Codex CLI itself is not installed — out of scope here; install it first, then re-run the add. |
| Plugin-installed `memesh` is absent | Refresh and reinstall the plugin using the commands above, then restart Codex. |
| Manually registered `memesh` is absent | Re-run `codex mcp add memesh -- memesh-mcp` and re-check. |
| Manual registration is listed, but tool calls fail | Run `command -v memesh-mcp`. Empty output means section 2 is incomplete or PATH is wrong — fix per section 2's table. |

## 4. Cursor

Prerequisite: section 2 — `memesh-mcp` must resolve on PATH.

For a personal server available in every Cursor project, create or edit
`~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "memesh": {
      "command": "memesh-mcp"
    }
  }
}
```

For one project only, use the same entry in that project's `.cursor/mcp.json`.
Restart Cursor, then open Cursor's MCP settings and confirm that `memesh` is
connected. If the Cursor Agent CLI is installed, `cursor-agent mcp list` also
shows the configured server.

A client that reports no workspace root needs `MEMESH_PROJECT_ROOT` set to the project's absolute directory in the server's `env`, or pass `project` on each `remember`, `learn` and `recall` call.

| Failure | Remedy |
|---|---|
| `memesh` is disconnected | Run `command -v memesh-mcp`. Empty output means section 2 is incomplete or PATH is not visible to Cursor. |
| Cursor cannot start the server | Use the absolute path returned by `command -v memesh-mcp` as `command`, then restart Cursor. |
| Tools are missing | Confirm the `mcpServers.memesh` entry is valid JSON and that the server is configured as a local stdio command, not an HTTP URL. |