Promote staging → main

.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "name": "memwal",
       "source": "./packages/mcp/plugin",
       "description": "Automatic Walrus Memory — proactive recall and durable-fact saving via the MemWal MCP + lifecycle hooks.",
-      "version": "0.0.13"
+      "version": "0.0.14"
     }
   ]
 }

.cursor-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "name": "memwal",
       "source": "./packages/mcp/plugin",
       "description": "Automatic Walrus Memory — proactive recall and durable-fact saving via the MemWal MCP + lifecycle hooks.",
-      "version": "0.0.13"
+      "version": "0.0.14"
     }
   ]
 }

.github/ISSUE_TEMPLATE/bug.yml

@@ -10,7 +10,7 @@ body:
 
         Do not paste delegate private keys, mnemonics, or other secrets.
 
-        If this is a security finding, use a [private advisory](https://github.com/MystenLabs/MemWal/security/advisories/new) instead of this form.
+        If this is a security finding, email [security@mystenlabs.com](mailto:security@mystenlabs.com). Do not use this form. See our [security policy](https://github.com/MystenLabs/MemWal/security/policy).
 
   - type: dropdown
     id: surface

.github/ISSUE_TEMPLATE/config.yml

@@ -10,5 +10,5 @@ contact_links:
     url: https://discord.gg/walrusprotocol
     about: Questions and builder support that are not a bug or a feature request.
   - name: Report a security vulnerability
-    url: https://github.com/MystenLabs/MemWal/security/advisories/new
-    about: Private advisory. Do not file a public issue for security findings.
+    url: https://github.com/MystenLabs/MemWal/security/policy
+    about: Email security@mystenlabs.com. Do not report security issues through GitHub or Discord.

.github/workflows/check-mcp-pin.yml

@@ -0,0 +1,64 @@
+name: Check MCP launcher pin
+
+# The plugin launcher installs whatever `mcpPackageVersion` in
+# packages/mcp/plugin/plugin.json names, so a pin npm does not carry breaks every
+# fresh plugin install until someone edits the manifest. Whether a version exists
+# is a fact about npm rather than about this repository, so no unit test can hold
+# it — trusted-launcher.test.mjs checks the shape of the pin and its relationship
+# to `version`, and this checks that the thing actually exists.
+#
+# Its own workflow rather than a job in test.yml for the same reason as
+# check-model-ids: the failure can arrive with no commit attached. The `dev`
+# dist-tag moves whenever a push to `dev` touches packages/mcp, and that number is
+# never committed back, so the manifest drifts on its own. test.yml has no
+# schedule trigger.
+#
+# The registry endpoint is public, so this needs no token and no environment.
+
+on:
+  pull_request:
+    # Only when the pin, the check, or the launcher that reads the pin moves.
+    # Every other PR would be taking a network dependency on npm for nothing.
+    paths:
+      - "packages/mcp/plugin/plugin.json"
+      - "packages/mcp/plugin/scripts/lib/mcp-launch.mjs"
+      - "scripts/check-mcp-pin.mjs"
+      - ".github/workflows/check-mcp-pin.yml"
+  push:
+    branches: [main, staging, dev]
+    paths:
+      - "packages/mcp/plugin/plugin.json"
+      - "scripts/check-mcp-pin.mjs"
+      - ".github/workflows/check-mcp-pin.yml"
+  schedule:
+    # Catches the drift nobody pushed: a dist-tag that moved under a manifest
+    # that did not. Reads nothing shared, so it needs no bench-account offset.
+    - cron: "0 9 * * 1"
+  workflow_dispatch:
+
+concurrency:
+  group: check-mcp-pin-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+  contents: read
+
+jobs:
+  mcp-pin:
+    name: Launcher pin is published
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      # No install step: the check is dependency-free and talks to the public
+      # registry over fetch.
+      - name: Check the launcher pin against npm
+        run: node scripts/check-mcp-pin.mjs

README.md

@@ -57,6 +57,8 @@ await memwal.restore("demo");
 
 ## Contributing
 
+Report security issues by email to [security@mystenlabs.com](mailto:security@mystenlabs.com). Do not report security issues through GitHub or Discord. See [SECURITY.md](SECURITY.md).
+
 We want to be explicit about this while Walrus Memory is in beta: feedback, bug reports, docs fixes,
 examples, and implementation contributions are all welcome.
 

SECURITY.md

@@ -0,0 +1,10 @@
+# Security Policy
+
+We appreciate your participation in keeping Walrus Memory secure. This document describes how to report
+security vulnerabilities.
+
+## Reporting a Vulnerability
+
+Report security issues by email to
+[security@mystenlabs.com](mailto:security@mystenlabs.com).
+**Do not report security issues through GitHub or Discord.**

apps/app/public/skills/setup

@@ -26,14 +26,13 @@ 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.
+1. Identify the AI client and mode before checking local prerequisites. Regular
+   Claude Desktop chat and Claude web use **Claude OAuth Connector** below.
+   The **Code tab inside Claude Desktop** uses the Claude Code plugin path;
+   it is not the same setup as regular Desktop chat. If the mode is unclear,
+   ask which tab the user wants to use. Other local clients use Local MCP
+   Server. Clients using explicit account/key headers use Remote MCP
+   (header-capable clients). The ChatGPT desktop app uses the Codex 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.
@@ -65,7 +64,38 @@ user explicitly asks for developer integration.
     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
+## Claude OAuth Connector (Claude Desktop chat and Claude web)
+
+Use this path for regular Claude chat when custom connectors are available.
+Production supports OAuth at `https://relayer.memory.walrus.xyz/api/mcp`.
+No local Node.js, `claude` CLI, config-file edits, or manually copied delegate
+key are needed. Skip the local requirements and terminal login sections.
+
+1. Ask the user to open Claude's **Settings → Connectors → Add custom connector**
+   and enter `https://relayer.memory.walrus.xyz/api/mcp`.
+2. Follow the browser consent flow with a Sui wallet that owns the Walrus Memory
+   account. If needed, the flow guides account creation. Explain the scopes
+   shown on the consent screen: `memwal:read` reads memories, `memwal:write`
+   saves them, and `offline_access` allows token refresh. The relayer holds an
+   encrypted delegate private key for this flow. Let the user review and
+   approve the wallet authorization themselves.
+3. Return to Claude, enable the connector for the conversation if needed, and
+   verify memory tools by saving and recalling a neutral setup-check fact.
+   If authorization expires, reconnect through Claude's connector settings;
+   do not prescribe a local `npx` login or require local-only login tools.
+
+This provides memory tools in chat, not the Code plugin's lifecycle hooks.
+Do not claim it installs the plugin in the Code tab. If the user wants local
+credentials instead, offer the explicit Claude Desktop local MCP option below.
+If custom connectors are unavailable, report that limitation before offering
+another route; do not silently switch to local installation.
+
+Full consent and disconnect details:
+https://docs.wal.app/walrus-memory/mcp/claude-connector
+Removing the connector alone does not remove the onchain delegate; the user
+can revoke that delegate from the Walrus Memory dashboard.
+
+## Requirements (local MCP and header authentication only)
 
 For local MCP clients, check Node.js:
 
@@ -87,7 +117,7 @@ wallet. The sign-in flow writes persistent credentials to:
 
 Those credentials are what survive MCP server restarts.
 
-## Recommended Login
+## Recommended Login (local MCP and header authentication only)
 
 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
@@ -166,10 +196,11 @@ and merge:
 }
 ```
 
-### Claude Desktop
+### Claude Desktop local MCP (optional)
 
-Use the config file below. Claude Desktop's Settings > Connectors UI only
-supports OAuth remote servers and does not work for Walrus Memory.
+For regular chat, prefer the Claude OAuth Connector section above. Use this
+local alternative only when the user chooses it; it requires Node.js 20+.
+This config does not install the plugin for the Code tab.
 
 Edit:
 
@@ -239,11 +270,27 @@ 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`.
+This includes the Code tab inside Claude Desktop. Claude's current Desktop
+plugin UI can install plugins without a terminal: open the `+` menu beside the
+prompt, choose **Plugins → Add plugin**, select MemWal from a configured
+marketplace, then use **Manage plugins** to confirm it is enabled. If the MemWal
+marketplace is not listed, add it with the terminal commands below. Do not paste
+`/plugin` commands into chat as plain text; that can make the agent edit settings
+without installing the plugin.
+
+Having the desktop app installed does not guarantee that the `claude` CLI is
+available in a shell. For the terminal route, check `node --version`,
+`npm --version`, and `claude --version` first. If a prerequisite is missing,
+explain the exact blocker and point to https://nodejs.org/ or
+https://code.claude.com/docs/en/setup. Do not create `enabledPlugins` entries
+as a substitute for a verified install. If the user only needs regular chat,
+offer the OAuth connector instead; it does not add Code hooks.
+
+Run the following as separate commands in a terminal, stopping on the first
+failed command:
 
 ```bash
-claude plugin marketplace add MystenLabs/MemWal
+claude plugin marketplace add https://github.com/MystenLabs/MemWal.git
 claude plugin install memwal@memwal-plugins -s user
 claude plugin list
 claude mcp list
@@ -253,14 +300,25 @@ claude mcp list
 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:
+The slash commands are only for an interactive Claude Code session that
+actually exposes `/plugin`; they are not chat instructions. The Desktop UI path
+above is preferred when available. If `/plugin` is unavailable, use the
+terminal route instead:
 
 ```text
-/plugin marketplace add MystenLabs/MemWal
+/plugin marketplace add https://github.com/MystenLabs/MemWal.git
 /plugin install memwal@memwal-plugins
 ```
 
+A delegate key is not required to install the plugin. After installation,
+fully quit and reopen Claude Code, then ask it to run `memwal_login` and follow
+the browser sign-in. Verify the plugin is enabled, the MCP server is connected,
+and a memory can be saved and recalled before reporting success.
+
+If adding the HTTPS source reports an existing marketplace with a different
+source, inspect `claude plugin marketplace list` and explain the conflict;
+do not remove an existing marketplace or configuration without review.
+
 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".
@@ -320,13 +378,22 @@ Add an MCP server with:
 - command: `npx`
 - args: `["-y", "@mysten-incubation/memwal-mcp"]`
 
+## Permissions during local setup
+
+Explain shell-command approvals and the plugin/config files being changed.
+These instructions do not require reading Desktop files or controlling Apple
+Music. If an unrelated OS permission prompt appears, stop and identify the
+exact command and prompt before advising the user to grant access. Do not
+request broad filesystem or automation access as a generic installation fix.
+Do not attribute a prompt to Claude or MemWal without evidence.
+
 ## 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
+## Verify Tools (local MCP)
 
 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,
@@ -378,7 +445,8 @@ If the tools support a `namespace` argument, use a setup-only namespace such as
 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.
+cannot use this header-authentication path. Claude Desktop/web should use the
+OAuth connector above, which does not require custom headers.
 
 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
@@ -418,8 +486,8 @@ cat ~/.memwal/credentials.json
 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
+If the client cannot attach both custom headers, this header-authentication
+path is unavailable. For Claude Desktop/web, use OAuth instead. 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.
 
@@ -434,14 +502,20 @@ this skill for the same client.
 | `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` is missing or `claude plugin` is not recognized | Check CLI availability and version; the Desktop app alone does not guarantee a shell CLI. Install/update Claude Code for the plugin route, or offer OAuth for regular chat. Do not claim a config edit completed installation. |
 | 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
 
+For OAuth, report connector authorization and save/recall verification status.
+Do not require a local restart, credentials file, plugin, or Node.js. If the
+user has not completed consent or tools have not been verified, say what is
+still pending. Automatic save/recall in regular chat is best-effort, not the
+Code plugin's lifecycle-hook behavior.
+
 Keep the final response short and make the restart the first thing the user
 sees whenever a restart is required.
 

apps/app/src/pages/ConnectMcp.test.tsx

@@ -116,10 +116,16 @@ describe('MCP sign-in hand-off', () => {
         expect(screen.getByText(/Nothing answered on your computer/i)).toBeInTheDocument()
         expect(screen.getByText(/stopped waiting after this tab was already open/i)).toBeInTheDocument()
         expect(screen.queryByText(/opened too late/i)).not.toBeInTheDocument()
-        expect(screen.getByText(/Sign in again and open the new link straight away/i)).toBeInTheDocument()
-        expect(screen.getByText(/left running through the wallet prompt/i)).toBeInTheDocument()
-        expect(screen.getByText(/unused key from this attempt is already on your account/i)).toBeInTheDocument()
         expect(screen.queryByText(/usually works/i)).not.toBeInTheDocument()
+        // The key is registered and saved by the client that started this
+        // sign-in, so a restart reclaims it. Signing in again cannot register
+        // it twice, and removing it from the dashboard throws it away.
+        expect(screen.getByText(/Restart your MCP client within 24 hours/i)).toBeInTheDocument()
+        expect(screen.getByText(/only if you mean to abandon it/i)).toBeInTheDocument()
+        expect(
+            screen.queryByText(/Remove it from the dashboard if you are not using it/i),
+        ).not.toBeInTheDocument()
+        expect(screen.queryByText(/Sign in again and open the new link straight away/i)).not.toBeInTheDocument()
     })
 
     it('explains an expired link when preflight cannot reach the listener', async () => {