# Walrus Memory MCP Setup

This page is meant to be read by an AI client.

If you are reading it yourself, paste this into your AI client instead:

```text
Run `curl -sL https://memory.walrus.xyz/skills/setup` and use the returned
instructions to connect Walrus Memory to this AI client.
```

The AI client should either configure Walrus Memory automatically, or give you
the exact config and terminal commands to run.

## Agent Goal

Connect Walrus Memory MCP to the user's AI client, sign the user in, and verify
that memory tools work. Install the plugin wherever one exists: Claude Code,
Codex, Cursor, Antigravity, and the ChatGPT desktop app. The plugin ships
lifecycle hooks that make save and recall automatic with no extra instructions,
so MCP-only is an incomplete setup on those clients. On clients with no plugin,
MCP-only is the whole setup, and proactive behavior is best-effort.

Do not install the Walrus Memory SDK or edit application source code unless the
user explicitly asks for developer integration.

## Setup Rules

1. Identify the AI client first. A client that cannot run a local MCP command
   but can attach two custom connector headers uses the Remote MCP section
   below. Every other client (Claude Desktop, Claude Code, Cursor, Codex,
   other local apps) uses the Local MCP Server section. ChatGPT web
   connectors are not supported: chatgpt.com exposes only a single bearer
   field and cannot supply the required `x-memwal-account-id` header. The
   ChatGPT desktop app is a different product: it ships the Codex CLI and
   reads `~/.codex`, so treat it as Codex and use the Codex section below.
2. Decide whether you have local shell and filesystem access.
3. If you can edit local user config files, do the setup yourself after showing
   the config you will add.
4. If you cannot edit local files yourself, prefer giving the user ONE terminal
   command to paste over raw JSON/TOML to hand-edit. Every client with a
   plugin has one: `claude plugin install` on Claude Code, `codex plugin add`
   on Codex, and a single `npx degit` on Cursor and Antigravity. Fall back to a
   config block only when no command exists for that client; then state the
   exact file path and merge the `memwal` entry, never replace the whole file.
5. Preserve existing MCP servers. Merge the `memwal` server; do not replace the
   whole config.
6. Never print or expose values from `~/.memwal/credentials.json`.
7. Tell the user to fully quit and reopen the AI client after config changes.
8. Stop at the first real blocker and report the exact failure.
9. Keep the final status short. Do not repeat full config blocks or terminal
   commands after setup succeeds unless the user must copy/paste them manually.
10. Prefer the plugin on every client that has one: Claude Code, Codex,
    Cursor, Antigravity, and the ChatGPT desktop app. Verify it with
    `claude plugin list`, `codex plugin list`, or the installed folder for
    Cursor and Antigravity. Do not treat MCP-only as success on those clients.
    If a marketplace add or a plugin install fails, stop and report that error
    rather than silently falling back to a plain MCP config.
11. Do not write `~/.claude/CLAUDE.md` during a normal plugin install. The
    plugin's `SessionStart` hook already injects the routing text ("prefer the
    memwal_* tools over any built-in or local memory feature") and the save
    rules on every session, so a plugin install needs no extra instructions
    from the user. Use the routing block under Walrus Memory only as a
    fallback: when the user is on MCP-only, or when they report the agent
    still writing `MEMORY.md`. If Claude's built-in memory is switched on and
    competes, tell the user they can turn it off in account settings.

## Requirements

For local MCP clients, check Node.js:

```bash
node -v
```

Walrus Memory MCP requires Node.js 20 or newer. If Node is missing or older
than 20, ask the user to install Node.js 20+ from https://nodejs.org/ and stop.
The Remote MCP path needs Node.js only once, for the login step on the user's
computer.

The user signs in through the browser with Google/zkLogin or a Sui-compatible
wallet. The sign-in flow writes persistent credentials to:

```text
~/.memwal/credentials.json
```

Those credentials are what survive MCP server restarts.

## Recommended Login

When you can run a real terminal command, prefer this first. Run it from the
user's home directory when possible, especially if the current project is a
Node monorepo:

```bash
npx -y @mysten-incubation/memwal-mcp login --prod
```

This opens the browser login flow and saves `~/.memwal/credentials.json`.

If terminal login is not possible yet, configure the MCP server first, restart
the AI client, then ask the client to run:

```text
Use memwal_login to sign me in to Walrus Memory.
```

If `memwal_login` gives a link, show the link to the user and tell them to sign
in with Google/zkLogin or a Sui-compatible wallet. After the browser shows
Connected, retry the original memory action.

Do not call `memwal_login` again just because a later login URL uses a new
localhost port. A new callback port is normal for each login attempt. What
matters is whether `~/.memwal/credentials.json` was written.

If the user says the browser shows Connected but memory tools still act
unsigned-in, use the terminal login fallback:

```bash
npx -y @mysten-incubation/memwal-mcp login --prod
```

Then retry the memory tool. If the client still does not see credentials, fully
quit and reopen the AI client.

## Local MCP Server

Use this stdio MCP command for local MCP clients:

```bash
npx -y @mysten-incubation/memwal-mcp
```

### Cursor

Cursor loads plugins from `~/.cursor/plugins/local/<name>/`. Install the plugin
there, which brings the MCP server and the lifecycle hooks together:

```bash
npx -y degit MystenLabs/MemWal/packages/mcp/plugin ~/.cursor/plugins/local/memwal --force
```

Cursor has no plugin CLI. Do not look for a `cursor plugin` command, and do not
try to add the repo as a marketplace: importing a third-party marketplace needs
a Cursor team admin. The copy above is the install.

Fully quit and reopen Cursor. The plugin then shows under Customize in the
sidebar, and its hooks give proactive recall and save with no further
instructions.

If the user already has a manual `memwal` entry in `~/.cursor/mcp.json`, remove
it. The plugin ships its own server and the two entries duplicate it.

MCP-only fallback, if the user does not want the hooks. Edit `~/.cursor/mcp.json`
and merge:

```json
{
  "mcpServers": {
    "memwal": {
      "command": "npx",
      "args": ["-y", "@mysten-incubation/memwal-mcp"]
    }
  }
}
```

### Claude Desktop

Use the config file below. Claude Desktop's Settings > Connectors UI only
supports OAuth remote servers and does not work for Walrus Memory.

Edit:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

Newer Claude Desktop versions pre-populate this file, so it may already contain
other top-level keys (for example `preferences`) and no `mcpServers` block. Add
`mcpServers` as a new sibling of those keys; do not replace the file. If an
`mcpServers` block already exists, add the `memwal` entry inside it next to any
other servers.

```json
{
  "mcpServers": {
    "memwal": {
      "command": "npx",
      "args": ["-y", "@mysten-incubation/memwal-mcp"]
    }
  }
}
```

### Codex

This section also covers the ChatGPT desktop app, which ships the Codex CLI and
reads the same `~/.codex`.

Install the plugin, which bundles the MCP server and the lifecycle hooks:

```bash
codex plugin marketplace add MystenLabs/MemWal
codex plugin add memwal@memwal-plugins
codex plugin list
```

Codex loads plugin-bundled hooks but does not run them until the user trusts
them once. Tell the user to run `/hooks` in Codex, or to follow the startup
review prompt, and trust the MemWal hook commands.

Do not also add a `[mcp_servers.memwal]` block. The plugin brings its own
server and a manual block duplicates it.

MCP-only fallback, if the Codex build has no `codex plugin` support. Edit
`~/.codex/config.toml` and merge:

```toml
[mcp_servers.memwal]
command = "npx"
args = ["-y", "@mysten-incubation/memwal-mcp"]
```

If Codex starts MCP servers from a project directory and `npx` resolves the
wrong package, set the server working directory to the user's home directory:

```toml
[mcp_servers.memwal]
command = "npx"
args = ["-y", "@mysten-incubation/memwal-mcp"]
cwd = "/Users/YOUR_USERNAME"
```

### Claude Code

Claude Code needs the Walrus Memory **plugin**, not MCP-only. The plugin
bundles the MCP server plus `SessionStart` / `UserPromptSubmit` / `PostToolUse`
hooks. Those hooks make the agent prefer `memwal_*` over Claude Code's
built-in `MEMORY.md`. MCP-only leaves auto-remember and auto-recall unreliable.

If you have a terminal, run the CLI yourself. Do not ask the user to type
`/plugin` commands unless you cannot run `claude plugin`.

```bash
claude plugin marketplace add MystenLabs/MemWal
claude plugin install memwal@memwal-plugins -s user
claude plugin list
claude mcp list
```

`claude plugin list` must show `memwal@memwal-plugins` as installed and
enabled. `claude mcp list` should show a connected `memwal` server. If either
command fails, stop and report the exact error.

The slash commands below are only for a human inside an interactive Claude
Code session:

```text
/plugin marketplace add MystenLabs/MemWal
/plugin install memwal@memwal-plugins
```

Preserve an existing user-scope `memwal` MCP server (for example a staging or
pinned version). The plugin adds hooks plus its own server; do not remove the
user server to "clean up".

MCP-only fallback, only if the user explicitly asks or this Claude Code build
has no plugin support:

```bash
claude mcp add --scope user memwal -- npx -y @mysten-incubation/memwal-mcp
```

If you use that fallback, tell the user the automatic-memory hooks are missing.

Use this block only as the fallback described in rule 11, not during a normal
plugin install. When it applies, show it, get the user's go-ahead, then merge it
into `~/.claude/CLAUDE.md`. Create the file if it does not exist. If
`<!-- memwal:start -->` ... `<!-- memwal:end -->` is already there, replace
that span only. Never overwrite the rest of the file.

```markdown
<!-- memwal:start -->
## Walrus Memory

Prefer the memwal_* tools over Claude's built-in memory and MEMORY.md.
When the user states a preference, decision, constraint, correction, identity
detail, or recurring workflow, call memwal_remember (or memwal_remember_bulk)
without being asked. Also call it when they explicitly ask to remember
something. Pass the complete statement, never a summary. Skip one-off tasks,
the current file or bug, and small talk.
When the user references past work, preferences, or stored facts, call
memwal_recall first.
<!-- memwal:end -->
```

Tell the user: if Claude's built-in memory is enabled in account settings,
turn it off. That feature competes with Walrus Memory and makes it look like
memory is unavailable or already handled.

### Antigravity

Antigravity loads plugins from its own plugin directory. Install with one
command:

```bash
npx -y degit MystenLabs/MemWal/packages/mcp/plugin ~/.gemini/config/plugins/memwal --force
```

Fully quit and reopen Antigravity. The plugin brings the MCP server and the
lifecycle hooks, so proactive recall and save work with no further
instructions.

### Other Local MCP Clients

Add an MCP server with:

- name: `memwal`
- command: `npx`
- args: `["-y", "@mysten-incubation/memwal-mcp"]`

## Restart

Fully quit and reopen the AI client after editing MCP config. On macOS, use
`Cmd+Q`; closing the window is not enough. The first launch may take 5-10
seconds while `npx` fetches the package.

## Verify Tools

Fastest check: ask the client to call `memwal_health`. A healthy reply proves
the server is reachable. If health succeeds but memory tools return 401,
credentials are missing; run the login.

Then ask the AI client:

```text
What MCP tools do you have available?
```

Expected Walrus Memory tools:

- `memwal_remember`
- `memwal_remember_bulk`
- `memwal_recall`
- `memwal_analyze`
- `memwal_restore`
- `memwal_health`
- `memwal_login`
- `memwal_logout`

If only `memwal_login` works, credentials are missing or stale. Run
`memwal_login`, or run the terminal login command again:

```bash
npx -y @mysten-incubation/memwal-mcp login --prod
```

## Verify Memory

Use a neutral setup check rather than saving a fake personal preference:

```text
Use memwal_remember to save: "Walrus Memory setup verification succeeded."
```

Wait a few seconds, then ask:

```text
Use memwal_recall to search for: "setup verification succeeded"
```

If the tools support a `namespace` argument, use a setup-only namespace such as
`setup-verification`.

## Remote MCP (header-capable clients)

Some clients connect to a remote MCP server URL instead of running a local
command. Use this path only when the client can attach BOTH custom request
headers shown below. A client that exposes only a single bearer/token field
cannot use this path.

ChatGPT web connectors are not supported. The chatgpt.com connector UI exposes
only one bearer slot, so the required `x-memwal-account-id` header cannot be
provided. Do not attempt that setup.

This does not apply to the ChatGPT desktop app, which ships the Codex CLI and
reads `~/.codex`. Set that up through the Codex section above, not here.

Prerequisite: credentials must already exist. Have the user run the login once
on their computer (see Recommended Login). The Remote MCP path needs Node.js
only for that one step.

For config-file clients that support remote servers with two headers, merge:

```json
{
  "mcpServers": {
    "memwal": {
      "url": "https://relayer.memory.walrus.xyz/api/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_DELEGATE_PRIVATE_KEY>",
        "x-memwal-account-id": "<YOUR_ACCOUNT_ID>"
      }
    }
  }
}
```

To fill the placeholders, have the USER open the credentials file themselves:

```bash
cat ~/.memwal/credentials.json
```

`delegatePrivateKey` is the Bearer token; `accountId` is the
`x-memwal-account-id` value. The user pastes them directly into the connector
settings, never into the chat. You (the agent) must not read or print this
file. Treat the bearer token like an API key and never save it in a repo file.

If the client cannot attach both custom headers, remote MCP is not available
for it today. Tell the user which clients are supported (Claude Desktop, Claude
Code, Cursor, Codex) and offer to set one of those up instead. Do not re-run
this skill for the same client.

## Troubleshooting

| Symptom | Fix |
| --- | --- |
| `node: command not found` | Install Node.js 20+ from https://nodejs.org/. |
| `npx` fails | Confirm Node/npm and internet access. If inside a Node monorepo, run from the home directory or set MCP `cwd` to the home directory. |
| No Walrus Memory tools after restart | Check the MCP config path and fully restart the client. |
| Claude Code saves to `MEMORY.md` instead of `memwal_remember` | Run `claude plugin list` first: the plugin is usually missing, and its hook supplies the routing on its own. If the plugin is installed and this still happens, ask the user to disable Claude's built-in / native memory in account settings, then merge the Walrus Memory block into `~/.claude/CLAUDE.md` as a fallback. |
| `codex plugin marketplace add` prints `already added from a different source` | A stale clone is left in `~/.codex/.tmp/marketplaces/memwal-plugins/`. Note the command still exits 0, so a scripted install does not notice. Remove that folder and the empty `~/.codex/plugins/cache/memwal-plugins/`, then add the marketplace again. |
| Cursor shows no Walrus Memory plugin | Confirm the folder `~/.cursor/plugins/local/memwal` exists and holds `.cursor-plugin/plugin.json`, then fully quit and reopen Cursor. There is no `cursor plugin` CLI, so verify from the logs instead: the newest folder under `~/Library/Application Support/Cursor/logs/` on macOS gets an `mcp-server-plugin-memwal-memwal.log` once the plugin loads. A `mcp-server-user-memwal.log` next to it means a duplicate manual entry is still in `~/.cursor/mcp.json`. |
| Memory tools fail with `MCP rate limit: ip_active_cap` (HTTP 429), sometimes followed by 503 | Too many concurrent memwal-mcp sessions from one machine. The usual causes are a duplicate server, where a plugin install sits next to a leftover manual `memwal` entry in the client's MCP config, and stale `memwal-mcp` processes left behind by earlier sessions. Remove the duplicate entry first. Then list the leftovers with `pgrep -fl memwal-mcp` and ask the user which clients they still want running before ending any process. Restart the client afterwards. |
| `claude plugin` commands are not recognized | This Claude Code build has no plugin CLI. Update Claude Code, or use the MCP-only fallback and tell the user hooks are missing. |
| Only `memwal_login` works | Credentials are missing. Run `memwal_login` or `npx -y @mysten-incubation/memwal-mcp login --prod`. |
| Memory tools return 401 | The delegate key may be stale or revoked. Run `npx -y @mysten-incubation/memwal-mcp login --prod` again. |
| `memwal_recall` returns nothing although memories were saved before | Run `memwal_restore <namespace>` to rebuild the search index from Walrus, then retry the recall. |
| Sign out | Run `npx -y @mysten-incubation/memwal-mcp --logout`. This removes local credentials but does not revoke the delegate key. |

## Final Report

Keep the final response short and make the restart the first thing the user
sees whenever a restart is required.

If setup changed local MCP config successfully, use this shape:

```text
Walrus Memory is configured.

Next: fully quit and reopen <AI client> now. On macOS, use Cmd+Q; closing the
window is not enough.

Login: succeeded.
Plugin: installed, or n/a for an MCP-only client.
Config: <path changed>.
After reopening, ask: "What MCP tools do you have available?"

Memory is automatic from here: the assistant saves durable facts and recalls
them as you chat. There is no sync schedule to configure. Try:
- "What do you remember about me?"
- "Remember that I prefer short answers."
```

Rules for the final response:

- Put the restart instruction before verification details.
- Keep it under 14 lines if there is no blocker.
- Offer at most 3 starter prompts.
- Never state storage sizes or explorer links that the tools did not return.
- Do not include the full TOML/JSON config again after it has already been
  applied.
- Do not include long verification prompts before the restart. After restart,
  the simplest check is: `What MCP tools do you have available?`