MCP

Using an agent? Try this prompt

Add the Walrus Memory MCP server to this client. On Claude Code run `claude mcp add --scope user memwal -- npx -y @mysten-incubation/memwal-mcp`; on other clients add the equivalent mcp.json entry. Then ask the agent to run memwal_login to sign in.

The Walrus Memory MCP server exposes your portable Walrus Memory as Model Context Protocol tools, so an AI agent can decide when to save and recall memories on its own. It works with any MCP-aware client, and on Claude Code, Codex, Cursor, and Antigravity it can be installed as a plugin that adds automatic memory through lifecycle hooks.

MCP Vs plugin

There are two ways to use Walrus Memory. The difference is whether you also get the lifecycle hooks:

Component	Plugin	MCP-only
Walrus Memory MCP: memory tools (memwal_remember, memwal_recall, …)	✓	✓
Lifecycle hooks: automatic recall/save reminders	✓	✗

• Plugin bundles the MCP server and lifecycle hooks. The SessionStart hook tells the agent to prefer the memwal_* tools over any built-in or local memory feature, and when to save without being asked. Available on Claude Code, Codex, Antigravity, and Cursor.
• MCP-only gives the agent the memory tools on every MCP client. The tool descriptions encourage proactive use, so agents often do save and recall on their own. Treat that as best-effort: it varies by client and model, and on a client that ships its own memory feature the built-in one commonly wins.

Saving without being asked is on once you agree to it: memwal-mcp login asks the question in your terminal the first time, and on a fresh install nothing is saved unprompted until you answer. Saved memories are permanent, Walrus is immutable storage, which is why the question comes first. Change the answer any time with memwal-mcp auto-save on|off (or MEMWAL_AUTO_SAVE in your client's env block). Recall, and anything you explicitly ask to be remembered, work either way. Credentials, passwords, API keys, tokens, private keys, seed phrases, authorization headers, and URLs with an embedded user:password, are excluded in both modes and stripped before a memory is written, because Walrus storage is append-only and a stored secret cannot be deleted.

note

Prefer the plugin wherever you can install it. It is the tested path for reliable automatic save and recall, and it needs no extra instructions from you. On MCP-only clients, paste the client's instruction block (see Claude Desktop) to get closer to the same behavior.

Fastest path: let your agent set it up

Paste this into the AI client you want to connect:

Source: mcp/overview.md

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

The agent identifies the client, writes the right config or runs the right install command, signs you in, and verifies the memory tools. Use the per-client table below if you would rather do it by hand.

Which install path for your client

What the user actually does differs per client. Pick your row:

Client	Automatic memory (hooks)	What you do
Claude Code	✓ Plugin	Code tab: use the Claude Code plugin setup with the explicit HTTPS marketplace URL; regular Claude Desktop/web chat: use the OAuth connector
Codex	✓ Plugin	codex plugin marketplace add MystenLabs/MemWal, then codex plugin add memwal@memwal-plugins, then trust the hooks through /hooks
Antigravity	✓ Plugin	npx degit MystenLabs/MemWal/packages/mcp/plugin ~/.gemini/config/plugins/memwal
Cursor	✓ Plugin	npx -y degit MystenLabs/MemWal/packages/mcp/plugin ~/.cursor/plugins/local/memwal
Claude Desktop	✗ MCP-only	Regular chat: use the OAuth connector; local MCP is optional. The Code tab uses Claude Code.
OpenCode	✗ MCP-only	Edit the OpenCode MCP config
ChatGPT desktop app	✓ Plugin	Ships Codex, so follow Codex
ChatGPT web (Connectors)	✗ Not supported	n/a

On the plugin rows, that command is the whole setup. The plugin's hooks carry the memory instructions, so you do not need to add routing text to CLAUDE.md, AGENTS.md, or a system prompt yourself.

note

"ChatGPT" means two different things here. The macOS ChatGPT desktop app ships Codex (/Applications/ChatGPT.app/Contents/Resources/codex) and reads the same ~/.codex/config.toml, so the Codex plugin install works there unchanged.

ChatGPT web connectors are not supported. Walrus Memory's remote Streamable HTTP transport needs two custom headers, but the Connectors UI exposes only a single bearer field and cannot supply the required x-memwal-account-id header.

Available tools

Tool	Description
memwal_remember	Save a durable fact for the user (preference, decision, constraint, identity).
memwal_remember_bulk	Save several distinct facts in one call.
memwal_recall	Semantic search across stored memories for relevant context.
memwal_analyze	Extract and save multiple facts from a passage of text.
memwal_restore	Rebuild the search index from Walrus when recall is unexpectedly empty.
memwal_health	Fast connectivity check (no search or decryption).
memwal_login	Connect this client to your account through browser wallet sign-in.
memwal_logout	Remove the saved credentials from this machine.

memwal_recall prints both score = 1 - cosine distance (higher = more similar) and the raw distance (lower = more similar), which is the wire and SDK field. Its optional maxDistance cutoff is expressed in distance, not score.

See Reference for full parameters, CLI flags, and transports.

How it works

The npm package (@mysten-incubation/memwal-mcp) runs locally next to your MCP client and bridges every memory tool call to the Walrus Memory relayer, which handles embeddings, Seal encryption, and Walrus storage.

Source: mcp/overview.md

• First run (no credentials): the server still starts and exposes memwal_login, so the agent signs you in inline instead of failing with a vague startup error. The login tool returns a clickable URL (valid 5 minutes); after you approve in the browser, the next tool call picks up the credentials automatically.
• Credential file: login writes ~/.memwal/credentials.json (mode 0600) containing your delegate key and account metadata. The delegate private key is a sensitive, long-lived credential; treat it like an API key.
• Local vs remote tools: the package handles memwal_login / memwal_logout locally (they never reach the relayer) and forwards all memory tools (memwal_remember, memwal_recall, …) to the relayer over an authenticated session.
• Logout deletes only the local credential file. To fully revoke access, also remove the delegate key from the dashboard.

See Reference for the credential file contents, transports (stdio vs HTTP), and runtime safety details.

Client-specific setup

Claude Code

Plugin (automatic memory) or MCP-only

Codex

Plugin (automatic memory) or MCP-only

Cursor

Plugin or MCP-only

Claude Desktop

MCP-only

Antigravity

Plugin or MCP-only

OpenCode

MCP-only

Reference

Tools, CLI flags, transports, self-hosting

Verify your setup

Ask the agent in any conversation:

What MCP tools do you have available?

You should see the memwal_* tools. Then state a durable fact (for example, a preferred package manager) and confirm the agent saves it with memwal_remember and recalls it in a later session.

Quick recovery

If memwal_recall returns nothing although you saved before (a new machine, a fresh relayer, or after switching servers), run memwal_restore <namespace> to rebuild the search index from the durable Walrus blobs, then recall again.