MCP Quick Start

Every supported client runs the same local server, npx -y @mysten-incubation/memwal-mcp, and differs only in where the configuration lives. Pick your client below, add the server, restart, and sign in.

For regular Claude Desktop or web chat, use the OAuth custom connector instead of the local setup below. It needs no local Node.js or CLI. The Code tab inside Claude Desktop uses the Claude Code plugin guide.

Prerequisites

• You need Node.js 22.23.4+ (22.x), 24.22.1+ (24.x), or 26.12.1+ (26.x), because the server runs through npx with no install step.
• If the project you have open contains its own installed @mysten-incubation/memwal-mcp, your client runs that copy instead of the published package. npx resolves the package name against the directory your client starts the server in, which is usually the open project, and pinning a version in the command does not prevent this. To avoid it, use the plugin, which installs the pinned version into ~/.memwal/runtime and launches that absolute path. Without the plugin, install the version yourself outside any project and point command and args at the absolute entry point, as the package README describes.
• You need a Walrus Memory account. An unauthenticated memory-tool call returns sign-in instructions rather than signing you in, so ask the agent to run memwal_login and follow the URL it returns to connect your wallet. Config files carry no keys.

How do I add Walrus Memory to my client?

Client	Where the config lives	Setup
Claude Code	Managed by the CLI	claude mcp add --scope user memwal -- npx -y @mysten-incubation/memwal-mcp, or install the plugin for automatic-memory hooks
Claude Desktop	claude_desktop_config.json	Add the JSON block below; see Claude Desktop for the per-OS file path
Cursor	~/.cursor/mcp.json	Add the JSON block below; hooks are optional
Codex	~/.codex/config.toml	codex plugin marketplace add MystenLabs/MemWal then codex plugin add memwal@memwal-plugins for the plugin with automatic-memory hooks, or add the TOML block below for MCP-only
OpenCode	~/.config/opencode/opencode.json	Add the OpenCode block below
Antigravity	Plugin directory or MCP config	npx degit MystenLabs/MemWal/packages/mcp/plugin ~/.gemini/config/plugins/memwal, or the JSON block; see Antigravity

After any of these, restart the client (MCP servers load at startup) and ask the agent to run memwal_login.

Config blocks

Every client runs the same server and differs only in the file format. The server entry is the canonical configuration from the packages/mcp README, and a CI check keeps every copy in these docs in sync with it.

JSON clients

Claude Desktop, Cursor, and Antigravity's MCP config all take this shape:

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

Codex

Codex reads ~/.codex/config.toml:

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

OpenCode

OpenCode reads ~/.config/opencode/opencode.json:

{
  "mcp": {
    "memwal": {
      "type": "local",
      "command": ["npx", "-y", "@mysten-incubation/memwal-mcp"],
      "enabled": true
    }
  }
}

How do I configure a namespace?

Every recall runs inside one account and namespace. To keep a client's memories in their own space, set the MEMWAL_NAMESPACE environment variable in the server entry (env in JSON configs, environment in OpenCode), or pass "--namespace", "<name>" in args. Without it, memories go to the default namespace.

How do I verify the setup?

1. Open your client's MCP status view (for example /mcp in Claude Code) and confirm the status view lists memwal as connected with its tools.
2. Ask the agent to run memwal_health; it returns a fast connectivity check against the relayer.
3. State a durable fact, for example a package-manager preference, confirm the agent calls memwal_remember, then start a fresh session and confirm memwal_recall finds it.

If a step fails, run npx -y @mysten-incubation/memwal-mcp --help in a terminal to surface the real error, and set MEMWAL_MCP_DEBUG=1 in the server's environment for verbose logging. The Claude Code page carries the full troubleshooting FAQ; the errors apply to every client.

Antigravity plugin directory

The degit command copies the plugin into ~/.gemini/config/plugins/memwal, which is Antigravity's plugin directory, so the .gemini path is correct. The plugin deploys the MCP server and its lifecycle hooks together. Restart Antigravity after you copy it. Antigravity reads GEMINI.md and AGENTS.md in the project as standing context. See Antigravity for the MCP-only alternative.

What is a namespace?

A namespace is a label that groups related memories inside your account. One account holds many namespaces, and recall and restore treat each one as a separate memory space. Recall is scoped per account plus namespace, so recall in one namespace never returns a memory from another. Every client that omits a namespace writes to and recalls from the same default space, so memories one client saves there are visible to the others.

Choose namespaces before you write at scale. Recall and restore match a namespace exactly, so splitting or merging memories across namespaces later means rewriting them. Namespaces organize data, but they are not an onchain authorization boundary. Use separate Walrus Memory accounts when you need cryptographic isolation.