From 6c654153142161a69d98061c7280cf59b6ce4ab3 Mon Sep 17 00:00:00 2001 From: Harry Phan Date: Tue, 15 Sep 2026 17:19:04 +0700 Subject: [PATCH] fix(mcp): reload Claude Code plugins in place instead of restarting The setup skill ended every Claude Code install by telling the user to quit with Cmd+Q and reopen. That is not needed: Claude Code applies a newly installed plugin, its MCP server and its lifecycle hooks with /reload-plugins, in the session the user is already in. Restarting is still correct for Claude Desktop, Cursor, Codex and Antigravity, and for a plain `claude mcp add` on Claude Code, so the restart guidance stays for those. Setup rule 8 also told the agent to stop at the first failing command. A sandboxed agent hits EPERM on ~/.claude/settings.json and the .cc-writes temp directory, which is an environment restriction rather than a MemWal fault, and the rule made agents hand the whole install back to the user. Rule 8 now asks for a workaround before a blocker is reported, and a new troubleshooting row documents the manual install: the enabledPlugins entry, the extraKnownMarketplaces entry and the installed_plugins.json v2 record. The final-report template gains a Claude Code variant that leads with /reload-plugins, and a line requiring the agent to disclose any workaround it applied. --- apps/app/public/skills/setup | 75 +++++++++++++++++++++++++++++------- docs/mcp/claude-code.md | 15 +++++--- docs/mcp/quickstart.md | 2 +- docs/mcp/reference.md | 2 + 4 files changed, 74 insertions(+), 20 deletions(-) diff --git a/apps/app/public/skills/setup b/apps/app/public/skills/setup index edecce6a6..b111b48c5 100644 --- a/apps/app/public/skills/setup +++ b/apps/app/public/skills/setup @@ -46,8 +46,16 @@ user explicitly asks for developer integration. 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. +7. Do not ask for a full restart when the client can reload in place. Claude + Code applies a new plugin with `/reload-plugins`, so that one line is the + whole hand-off. Every other client in this document does load MCP servers + at startup, so there you tell the user to fully quit and reopen it. +8. Stop only at a blocker you cannot clear yourself. A failing command is not + automatically a blocker: read the error, and if it is an environment + restriction rather than a MemWal fault, work around it and finish. The + Troubleshooting table below covers the ones seen in the wild, including + sandboxed agents that cannot write the client's config. Report a blocker + with the exact failure only after a workaround has actually been tried. 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, @@ -250,8 +258,22 @@ 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. +enabled. `claude mcp list` should show a connected `memwal` server. + +Claude Code does not need a restart. It loads a newly installed plugin, its +MCP server and its hooks when the user runs: + +```text +/reload-plugins +``` + +That is the only thing to hand back. Do not tell a Claude Code user to quit +with `Cmd+Q`; that instruction belongs to the other clients in this document. +Mention a relaunch only if `/reload-plugins` runs and the `memwal_*` tools +still do not appear. + +If `claude plugin install` fails to write the config, do not stop. See the +sandboxed-agent row in Troubleshooting and finish the install by hand. The slash commands below are only for a human inside an interactive Claude Code session: @@ -322,9 +344,12 @@ Add an MCP server with: ## 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. +Claude Code is the exception: it reloads in place with `/reload-plugins`, so +do not send a Claude Code user through a restart. + +For every other client, fully quit and reopen it 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 @@ -429,12 +454,13 @@ this skill for the same client. | --- | --- | | `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. | +| No Walrus Memory tools after restart | Check the MCP config path and fully restart the client. On Claude Code, run `/reload-plugins` instead; relaunch only if that does not bring the tools in. | | 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. | +| `claude plugin marketplace add` or `claude plugin install` fails with `EPERM` on `settings.json`, `.cc-writes`, or `installed_plugins.json` | The agent is sandboxed and its shell cannot write the Claude Code config, but its file-editing tools usually still can. This is an environment restriction, not a MemWal fault, so do not hand it back to the user. Finish the install by hand with the file tools. Back up `~/.claude/settings.json` first, then add `"memwal@memwal-plugins": true` to its `enabledPlugins` object, and add `memwal-plugins` to `extraKnownMarketplaces` with `{"source": {"source": "github", "repo": "MystenLabs/MemWal"}}` if it is absent. Then write `~/.claude/plugins/installed_plugins.json` as `{"version": 2, "plugins": {"memwal@memwal-plugins": [{"scope": "user", "installPath": "", "version": "", "installedAt": "", "lastUpdated": ""}]}}`, merging into any entries already there. The cache path is `~/.claude/plugins/cache/memwal-plugins/memwal/`; if that folder is missing, clone the marketplace to `~/.claude/plugins/marketplaces/memwal-plugins` and copy `packages/mcp/plugin` into it. Confirm with `claude plugin list` and `claude mcp list`, both of which only read. | | 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 ` to rebuild the search index from Walrus, then retry the recall. | @@ -442,10 +468,27 @@ this skill for the same client. ## Final Report -Keep the final response short and make the restart the first thing the user -sees whenever a restart is required. +Keep the final response short and lead with the one action the user still has +to take, whether that is a reload or a restart. + +On Claude Code, use this shape: + +```text +Walrus Memory is installed. + +Next: run /reload-plugins. No restart needed. + +Login: succeeded. +Plugin: memwal@memwal-plugins, enabled. +After the reload, 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." +``` -If setup changed local MCP config successfully, use this shape: +On every other client, use this shape: ```text Walrus Memory is configured. @@ -466,11 +509,15 @@ them as you chat. There is no sync schedule to configure. Try: Rules for the final response: -- Put the restart instruction before verification details. +- Put the reload or restart instruction before verification details. +- Never tell a Claude Code user to quit and reopen when `/reload-plugins` + would do. - 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?` +- Do not include long verification prompts first. Afterwards, the simplest + check is: `What MCP tools do you have available?` +- If you worked around an environment restriction, say so in one line and name + anything you could not clean up. Do not present a workaround as a failure. diff --git a/docs/mcp/claude-code.md b/docs/mcp/claude-code.md index 160969ebe..9a97469bb 100644 --- a/docs/mcp/claude-code.md +++ b/docs/mcp/claude-code.md @@ -60,8 +60,10 @@ Add MemWal to Claude Code so it recalls context and saves durable facts as you w /plugin install memwal@memwal-plugins ``` - - Restart Claude Code, then ask the agent to run `memwal_login` and open the URL it returns to connect your wallet. MCP-only is not a complete Claude Code setup: without the plugin, the agent often writes Claude's built-in `MEMORY.md` instead of calling `memwal_remember`. + + Run `/reload-plugins`. Claude Code picks up the plugin, its MCP server and its hooks in the session you are already in, so there is no need to quit and reopen. Relaunch only if the `memwal_*` tools still do not appear after the reload. + + Then ask the agent to run `memwal_login` and open the URL it returns to connect your wallet. MCP-only is not a complete Claude Code setup: without the plugin, the agent often writes Claude's built-in `MEMORY.md` instead of calling `memwal_remember`. Claude's system prompt still prefers `MEMORY.md` over MCP instructions. Show this block, get the user's go-ahead, then merge it into `~/.claude/CLAUDE.md` (do not replace the file). If `` ... `` is already there, replace that span only. Turn off Claude's built-in / native memory in account settings if it is on: @@ -81,7 +83,7 @@ Add MemWal to Claude Code so it recalls context and saves durable facts as you w ```bash claude mcp add --scope user memwal -- npx -y @mysten-incubation/memwal-mcp ``` - Restart Claude Code, then ask the agent to run `memwal_login` on first use. + Restart Claude Code so it picks up the new server, then ask the agent to run `memwal_login` on first use. `/reload-plugins` applies plugin installs, not a plain `claude mcp add`. Or connect to the relayer over HTTP directly (no local package): ```bash @@ -165,7 +167,7 @@ Work through these three checks in order; each one isolates a different layer. ## Troubleshooting FAQ **`/mcp` reports memwal as failed or missing.** -Restart Claude Code first; MCP servers load at startup. If it still fails, run `npx -y @mysten-incubation/memwal-mcp --help` in a plain terminal: that surfaces the real error, most often a Node version below 20 or a `PATH` without `npx` in the environment Claude Code inherits. For a full trace, add `MEMWAL_MCP_DEBUG=1` to the server's environment. +Run `/reload-plugins` first if you installed the plugin; that reconnects its MCP server without a restart. For an MCP-only install, restart Claude Code instead, since a plain `claude mcp add` is only read at startup. If it still fails, run `npx -y @mysten-incubation/memwal-mcp --help` in a plain terminal: that surfaces the real error, most often a Node version below 20 or a `PATH` without `npx` in the environment Claude Code inherits. For a full trace, add `MEMWAL_MCP_DEBUG=1` to the server's environment. **`/plugin` commands are not recognized.** Your Claude Code version predates plugin support. Update Claude Code, or use the MCP-only install; the memory tools behave the same, you only lose the automatic-memory hooks. @@ -188,7 +190,10 @@ Ask the agent to run `memwal_logout`, which wipes `~/.memwal/credentials.json`, Every recall runs inside one account and namespace. If you set `MEMWAL_NAMESPACE` (or `--namespace`) after saving, earlier memories live in the previous namespace. If the namespace matches and results are still missing, run `memwal_restore ` to rebuild the search index from Walrus; the stored memories are the source of truth, and you can rebuild the index at any time. **Hooks are not firing.** -The lifecycle hooks ship only with the **plugin** install; MCP-only provides the tools without hooks. Confirm the plugin appears in `/plugin` and restart after installing. +The lifecycle hooks ship only with the **plugin** install; MCP-only provides the tools without hooks. Confirm the plugin appears in `/plugin`, then run `/reload-plugins` so the hooks load into the current session. + +**`claude plugin install` fails with `EPERM` on `settings.json` or `.cc-writes`.** +An agent running in a sandbox often cannot write Claude Code's config from its shell, even though its file-editing tools can. Add `"memwal@memwal-plugins": true` to `enabledPlugins` in `~/.claude/settings.json`, back it up first, and register the install in `~/.claude/plugins/installed_plugins.json` under schema `version: 2`. The [setup skill](https://memory.walrus.xyz/skills/setup) carries the exact shape. `claude plugin list` and `claude mcp list` only read, so they still work for verification. **The agent writes `MEMORY.md` instead of calling `memwal_remember`.** Claude Code's built-in memory is in the system prompt and outranks MCP instructions. Confirm the plugin is enabled, merge the Walrus Memory block into `~/.claude/CLAUDE.md`, and turn off Claude's built-in / native memory in account settings. diff --git a/docs/mcp/quickstart.md b/docs/mcp/quickstart.md index 963d6cffb..fa289774b 100644 --- a/docs/mcp/quickstart.md +++ b/docs/mcp/quickstart.md @@ -58,7 +58,7 @@ Every supported client runs the same local server, `npx -y @mysten-incubation/me | OpenCode | `~/.config/opencode/opencode.json` | Add the [OpenCode block](#config-blocks) below | | Antigravity | Plugin directory or MCP config | `npx degit MystenLabs/MemWal/packages/mcp/plugin ~/.gemini/config/plugins/memwal`, or the [JSON block](#config-blocks); see [Antigravity](/mcp/antigravity) | -After any of these, restart the client (MCP servers load at startup) and ask the agent to run `memwal_login`. +After any of these, restart the client (MCP servers load at startup) and ask the agent to run `memwal_login`. Claude Code is the exception: after a plugin install, `/reload-plugins` applies it in the session you are already in. ### Config blocks diff --git a/docs/mcp/reference.md b/docs/mcp/reference.md index d980edc43..606cc487a 100644 --- a/docs/mcp/reference.md +++ b/docs/mcp/reference.md @@ -476,6 +476,8 @@ Work through the symptom that matches what you see. Quit and relaunch your MCP client. MCP servers only load at startup. If you used `claude mcp add`, run `claude mcp list` to confirm `memwal` is registered before restarting Claude Code. +On Claude Code with the plugin installed, run `/reload-plugins` instead. It loads the plugin, its server and its hooks without a relaunch. + ### Only `memwal_login` shows up Credentials are missing. Ask the agent to call `memwal_login`, or run `npx -y @mysten-incubation/memwal-mcp login --prod` from your terminal.