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

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. ChatGPT (or another client that cannot run a
   local MCP command but supports 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.
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 (for example a `claude mcp add ...` or login command) over
   raw JSON/TOML to hand-edit. 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.

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

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`

Merge:

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

### Codex

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

Preferred: install the Walrus Memory plugin. It bundles the same MCP server
plus lifecycle hooks that make memory automatic. Run inside Claude Code:

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

Then restart Claude Code.

MCP-only alternative:

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

Verify:

```bash
claude mcp list
```

### 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 (ChatGPT and other 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 supports custom request headers.
ChatGPT (developer mode) supports this today.

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

1. Settings > Connectors > enable Developer mode.
2. Add a connector with URL `https://relayer.memory.walrus.xyz/api/mcp`.
3. Add the two headers shown in the template below.

For config-file clients that support remote servers with 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 custom headers, remote MCP is not available for it
today. Tell the user which clients are supported (ChatGPT developer mode,
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. |
| 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.
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?`