From df4d51db40d56ad20e155c6df23e0ee127d43f4e Mon Sep 17 00:00:00 2001 From: Harry Phan Date: Wed, 12 Aug 2026 12:28:23 +0700 Subject: [PATCH] Port newer plugin content from walrus-memory-plugin Selectively brings over what the CommandOSSLabs/walrus-memory-plugin repo added on top of this repo's existing bundle: slash commands, the setup skill, and per-client usage docs. Marks the hosted custom-connector doc and setup-skill section as experimental and not production-ready, since the remote MCP OAuth work it depends on (MystenLabs/MemWal PR 584) is still under security review. Leaves the pre-existing hooks.json duplication and the branding attribution question unresolved, per the open items noted in the plugin README. --- docs/usage/claude-code.md | 64 +++++++++++++++++++++ docs/usage/codex.md | 91 ++++++++++++++++++++++++++++++ docs/usage/hosted-connector.md | 34 +++++++++++ docs/usage/other-clients.md | 94 +++++++++++++++++++++++++++++++ plugin/.claude-plugin/plugin.json | 20 +++++-- plugin/.mcp.json | 10 +++- plugin/README.md | 59 +++++++++++++++++++ plugin/commands/analyze.md | 15 +++++ plugin/commands/health.md | 15 +++++ plugin/commands/logout.md | 15 +++++ plugin/commands/recall.md | 15 +++++ plugin/commands/remember.md | 15 +++++ plugin/commands/restore.md | 15 +++++ plugin/commands/setup.md | 15 +++++ plugin/skills/setup/SETUP.md | 83 +++++++++++++++++++++++++++ plugin/skills/setup/SKILL.md | 57 +++++++++++++++++++ 16 files changed, 612 insertions(+), 5 deletions(-) create mode 100644 docs/usage/claude-code.md create mode 100644 docs/usage/codex.md create mode 100644 docs/usage/hosted-connector.md create mode 100644 docs/usage/other-clients.md create mode 100644 plugin/README.md create mode 100644 plugin/commands/analyze.md create mode 100644 plugin/commands/health.md create mode 100644 plugin/commands/logout.md create mode 100644 plugin/commands/recall.md create mode 100644 plugin/commands/remember.md create mode 100644 plugin/commands/restore.md create mode 100644 plugin/commands/setup.md create mode 100644 plugin/skills/setup/SETUP.md create mode 100644 plugin/skills/setup/SKILL.md diff --git a/docs/usage/claude-code.md b/docs/usage/claude-code.md new file mode 100644 index 0000000..1109bbf --- /dev/null +++ b/docs/usage/claude-code.md @@ -0,0 +1,64 @@ +# Claude Code Setup + +Claude Code is the primary target for this plugin package. It supports the plugin manifest, MCP config, skills, slash commands, and lifecycle hooks. + +## Local Review + +From the plugin repo root: + +```bash +claude plugin validate . --strict +claude --plugin-dir . +``` + +Restart Claude Code or run: + +```text +/reload-plugins +``` + +Then verify: + +```text +/plugin +/mcp +``` + +Expected: + +- Plugin namespace: `memwal` +- MCP server: `memwal` +- Tools: `memwal_login`, `memwal_health`, `memwal_remember`, `memwal_remember_bulk`, `memwal_recall`, `memwal_analyze`, `memwal_restore`, `memwal_logout` + +## Connect + +```text +/memwal:setup +``` + +Or: + +```text +Connect Walrus Memory. +``` + +Claude should call `memwal_health`, then `memwal_login` if credentials are missing. + +## Verify Memory + +```text +/memwal:health +/memwal:remember Walrus Memory Claude Code plugin setup was verified. +/memwal:recall Claude Code plugin setup verified +``` + +## Slash Commands + +- `/memwal:setup`: connect and verify Walrus Memory. +- `/memwal:health`: check connection and credential state. +- `/memwal:remember`: save one durable fact. +- `/memwal:recall`: search memory. +- `/memwal:analyze`: extract durable facts from text and save them. +- `/memwal:restore`: rebuild a namespace search index. +- `/memwal:logout`: remove local credentials. + diff --git a/docs/usage/codex.md b/docs/usage/codex.md new file mode 100644 index 0000000..d8f86f7 --- /dev/null +++ b/docs/usage/codex.md @@ -0,0 +1,91 @@ +# Codex Setup And Testing + +Codex does not install Claude Code plugins directly, but it can run the same Walrus Memory MCP server. + +Use MCP-only for the fastest test. Use optional hooks if you cloned this repo and want memory nudges on session start, prompt submit, and command errors. + +## Option A: MCP-Only + +Add to `~/.codex/config.toml`: + +```toml +[mcp_servers.memwal] +command = "npx" +args = ["-y", "@mysten-incubation/memwal-mcp", "--label", "Codex"] +``` + +Optional namespace: + +```toml +[mcp_servers.memwal] +command = "npx" +args = ["-y", "@mysten-incubation/memwal-mcp", "--label", "Codex", "--namespace", "work"] +``` + +Restart Codex. + +Inside a new Codex task, verify the MCP tools: + +```text +What MCP tools do you have available? +``` + +Expected tools: + +- `memwal_login` +- `memwal_logout` +- `memwal_health` +- `memwal_remember` +- `memwal_remember_bulk` +- `memwal_recall` +- `memwal_analyze` +- `memwal_restore` + +Run login: + +```text +Call memwal_login and help me connect Walrus Memory. +``` + +After the browser flow completes: + +```text +Call memwal_health. +Remember that Codex successfully connected to Walrus Memory through the plugin repo test. +Recall Codex Walrus Memory plugin repo test. +``` + +## Option B: MCP + Codex Hooks + +Clone the plugin repo: + +```bash +git clone https://github.com/CommandOSSLabs/walrus-memory-plugin.git +cd walrus-memory-plugin +``` + +Install hooks and register MCP: + +```bash +node scripts/install_codex_hooks.mjs +``` + +Enable hooks in `~/.codex/config.toml`: + +```toml +[features] +codex_hooks = true +``` + +Restart Codex. + +The installer is idempotent. Re-running it updates hook paths. + +Uninstall hooks: + +```bash +node scripts/install_codex_hooks.mjs --uninstall +``` + +Do not combine Option A with Option B unless you remove duplicate `[mcp_servers.memwal]` entries. + diff --git a/docs/usage/hosted-connector.md b/docs/usage/hosted-connector.md new file mode 100644 index 0000000..8bb6b04 --- /dev/null +++ b/docs/usage/hosted-connector.md @@ -0,0 +1,34 @@ +# Hosted Claude Custom Connector + +> **Status: experimental, not production-ready.** The remote MCP OAuth work this +> connector depends on ([MystenLabs/MemWal#584](https://github.com/MystenLabs/MemWal/pull/584)) +> is still under active security review. Do not present this flow as ready to end +> users, and do not claim `tools/list` or memory-tool calls have been verified +> working end to end against the hosted endpoint. Use the local stdio + delegate-key +> setup (`docs/usage/claude-code.md`, `docs/usage/codex.md`, `docs/usage/other-clients.md`) +> instead until that PR is merged and the live smoke test is confirmed. + +This repo is for the local plugin package. The hosted Claude custom connector is a separate remote MCP surface that uses OAuth. + +Once the OAuth work above is accepted, the expected connector URL for Claude's native custom connector UI is: + +```text +https://relayer.dev.memwal.ai/api/mcp +``` + +Discovery endpoints: + +```text +https://relayer.dev.memwal.ai/.well-known/oauth-authorization-server +https://relayer.dev.memwal.ai/.well-known/oauth-protected-resource +``` + +Expected flow, once ready: + +1. Add `https://relayer.dev.memwal.ai/api/mcp` in Claude's connector UI. +2. Claude discovers OAuth metadata. +3. The browser opens the Walrus Memory consent page. +4. The user connects a wallet and approves access. +5. Claude can call `tools/list` and memory tools without manual delegate keys or custom headers. + +This hosted connector flow is independent of the Claude Code marketplace plugin, which uses local stdio MCP and delegate-key custom-header auth. diff --git a/docs/usage/other-clients.md b/docs/usage/other-clients.md new file mode 100644 index 0000000..5a58b11 --- /dev/null +++ b/docs/usage/other-clients.md @@ -0,0 +1,94 @@ +# Other MCP Clients + +The Claude Code plugin bundle is not installed directly by OpenCode, Cursor, Claude Desktop, or most other IDEs. Those clients should use the same Walrus Memory MCP server through their MCP configuration. + +## OpenCode + +Add to `~/.config/opencode/opencode.json`: + +```json +{ + "mcp": { + "memwal": { + "type": "local", + "command": ["npx", "-y", "@mysten-incubation/memwal-mcp", "--label", "OpenCode"], + "enabled": true + } + } +} +``` + +Optional namespace: + +```json +{ + "mcp": { + "memwal": { + "type": "local", + "command": ["npx", "-y", "@mysten-incubation/memwal-mcp", "--label", "OpenCode"], + "environment": { + "MEMWAL_NAMESPACE": "work" + }, + "enabled": true + } + } +} +``` + +Restart OpenCode, then ask the agent to call `memwal_login`. + +## Cursor + +Add to `~/.cursor/mcp.json`: + +```json +{ + "mcpServers": { + "memwal": { + "command": "npx", + "args": ["-y", "@mysten-incubation/memwal-mcp", "--label", "Cursor"] + } + } +} +``` + +Optional namespace: + +```json +{ + "mcpServers": { + "memwal": { + "command": "npx", + "args": ["-y", "@mysten-incubation/memwal-mcp", "--label", "Cursor"], + "env": { + "MEMWAL_NAMESPACE": "work" + } + } + } +} +``` + +Restart Cursor and verify the `memwal` server is connected in Cursor's MCP settings. + +## Claude Desktop + +Add to Claude Desktop's config: + +- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` +- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json` + +```json +{ + "mcpServers": { + "memwal": { + "command": "npx", + "args": ["-y", "@mysten-incubation/memwal-mcp", "--label", "Claude Desktop"] + } + } +} +``` + +If the file already has other top-level keys, add `mcpServers` as a sibling instead of replacing the file. + +Fully quit and reopen Claude Desktop, then ask the agent to call `memwal_login`. + diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json index 42adc3e..165fb37 100644 --- a/plugin/.claude-plugin/plugin.json +++ b/plugin/.claude-plugin/plugin.json @@ -1,12 +1,24 @@ { "name": "memwal", - "version": "0.0.6", - "description": "Automatic Walrus Memory for Claude Code — proactive recall and durable-fact saving via the MemWal MCP + lifecycle hooks.", + "displayName": "Walrus Memory", + "version": "0.0.7", + "description": "Walrus Memory for Claude Code: MCP tools, delegate-key setup guidance, slash commands, and lifecycle hooks for durable encrypted memory.", "author": { "name": "Mysten Labs" }, "homepage": "https://memory.walrus.xyz", - "repository": "https://github.com/MystenLabs/MemWal", + "repository": "https://github.com/CommandOSSLabs/walrus-memory-mcp", "license": "Apache-2.0", - "keywords": ["memory", "mcp", "walrus", "sui", "semantic-search"] + "keywords": [ + "claude-code", + "memory", + "mcp", + "walrus", + "sui", + "semantic-search" + ], + "mcpServers": "./.mcp.json", + "skills": "./skills/", + "commands": "./commands/", + "hooks": "./hooks/hooks.json" } diff --git a/plugin/.mcp.json b/plugin/.mcp.json index 6051f56..a2fb5d7 100644 --- a/plugin/.mcp.json +++ b/plugin/.mcp.json @@ -2,7 +2,15 @@ "mcpServers": { "memwal": { "command": "npx", - "args": ["-y", "@mysten-incubation/memwal-mcp"] + "args": [ + "-y", + "@mysten-incubation/memwal-mcp", + "--label", + "Claude Code Plugin" + ], + "env": { + "MEMWAL_CLIENT_LABEL": "Claude Code Plugin" + } } } } diff --git a/plugin/README.md b/plugin/README.md new file mode 100644 index 0000000..504fe5e --- /dev/null +++ b/plugin/README.md @@ -0,0 +1,59 @@ +# Walrus Memory — Claude Code plugin + +This directory packages the Walrus Memory MCP server (from the repo root) as a Claude Code +marketplace plugin, and also ships MCP configs for Codex, Cursor, and Antigravity. + +## What is included + +- Claude Code plugin manifest: `.claude-plugin/plugin.json` +- MCP server config: `.mcp.json` +- Slash commands: `commands/` +- Setup skill: `skills/setup/` +- Lifecycle hooks: `hooks/hooks.json` +- Optional Codex hook installer: `scripts/install_codex_hooks.mjs` + +## Quick start (Claude Code local review) + +```bash +claude plugin validate . --strict +claude --plugin-dir . +``` + +Inside Claude Code: + +```text +/memwal:setup +/memwal:health +/memwal:remember I use Walrus Memory from Claude Code. +/memwal:recall Claude Code Walrus Memory setup +``` + +## Codex (MCP-only testing) + +Add this to `~/.codex/config.toml`: + +```toml +[mcp_servers.memwal] +command = "npx" +args = ["-y", "@mysten-incubation/memwal-mcp", "--label", "Codex"] +``` + +See `docs/usage/codex.md` at the repo root for the full setup and testing guide. + +## Detailed guides + +- Claude Code: `../docs/usage/claude-code.md` +- Codex: `../docs/usage/codex.md` +- OpenCode, Cursor, Claude Desktop: `../docs/usage/other-clients.md` +- Hosted Claude custom connector (**experimental, not production-ready** — see the warning + in that doc): `../docs/usage/hosted-connector.md` + +## Known open items (not resolved by this port) + +- The published `@mysten-incubation/memwal-mcp` npm package and this repo's `plugin/` + directory still carry two slightly different hook manifests + (`plugin/hooks.json` vs `plugin/hooks/hooks.json`). Establishing one canonical + source is tracked separately — see the Notion task for + "Add Claude custom-connector compatibility to remote MCP". +- Plugin manifest attribution (`author: "Mysten Labs"` in a CommandOSSLabs-owned repo) + has not been formally confirmed with Mysten Labs branding/ownership approval. diff --git a/plugin/commands/analyze.md b/plugin/commands/analyze.md new file mode 100644 index 0000000..ba56d59 --- /dev/null +++ b/plugin/commands/analyze.md @@ -0,0 +1,15 @@ +--- +description: Extract durable facts from text and save them to Walrus Memory. +argument-hint: +--- + +Use `memwal_analyze` to extract durable facts from the text below and save them as separate Walrus Memory entries. + +Do not save secrets, private keys, access tokens, passwords, or one-time codes. + +Text: + +```text +$ARGUMENTS +``` + diff --git a/plugin/commands/health.md b/plugin/commands/health.md new file mode 100644 index 0000000..86c5b08 --- /dev/null +++ b/plugin/commands/health.md @@ -0,0 +1,15 @@ +--- +description: Check whether Walrus Memory is connected and healthy. +argument-hint: [optional note] +--- + +Call `memwal_health` and summarize the result. + +If credentials are missing, tell the user to run `/memwal:setup` or call `memwal_login`. + +Optional context: + +```text +$ARGUMENTS +``` + diff --git a/plugin/commands/logout.md b/plugin/commands/logout.md new file mode 100644 index 0000000..be50e42 --- /dev/null +++ b/plugin/commands/logout.md @@ -0,0 +1,15 @@ +--- +description: Disconnect this client from Walrus Memory. +argument-hint: [confirm logout] +--- + +Call `memwal_logout` to remove local Walrus Memory credentials for this client. + +Before calling it, confirm the user really wants to disconnect, because they will need to run `/memwal:setup` or `memwal_login` again before using memory tools. + +User note: + +```text +$ARGUMENTS +``` + diff --git a/plugin/commands/recall.md b/plugin/commands/recall.md new file mode 100644 index 0000000..f016a0a --- /dev/null +++ b/plugin/commands/recall.md @@ -0,0 +1,15 @@ +--- +description: Search Walrus Memory for relevant prior context. +argument-hint: +--- + +Search Walrus Memory with `memwal_recall` for context relevant to the user's query below. + +Use a focused semantic query. After recalling, summarize only the useful findings and say when no relevant memory was found. + +Recall query: + +```text +$ARGUMENTS +``` + diff --git a/plugin/commands/remember.md b/plugin/commands/remember.md new file mode 100644 index 0000000..10338eb --- /dev/null +++ b/plugin/commands/remember.md @@ -0,0 +1,15 @@ +--- +description: Save a durable fact, decision, preference, constraint, or project note to Walrus Memory. +argument-hint: +--- + +Save the following durable fact to Walrus Memory using `memwal_remember`. + +If `$ARGUMENTS` is empty, ask the user what they want remembered. Do not save secrets, private keys, access tokens, passwords, or one-time codes. + +Memory to save: + +```text +$ARGUMENTS +``` + diff --git a/plugin/commands/restore.md b/plugin/commands/restore.md new file mode 100644 index 0000000..3eb6e4e --- /dev/null +++ b/plugin/commands/restore.md @@ -0,0 +1,15 @@ +--- +description: Rebuild Walrus Memory search index for a namespace. +argument-hint: +--- + +Use `memwal_restore` to rebuild the Walrus Memory search index for this namespace. + +If `$ARGUMENTS` is empty, ask the user which namespace to restore before calling the tool. + +Namespace: + +```text +$ARGUMENTS +``` + diff --git a/plugin/commands/setup.md b/plugin/commands/setup.md new file mode 100644 index 0000000..2f3c276 --- /dev/null +++ b/plugin/commands/setup.md @@ -0,0 +1,15 @@ +--- +description: Connect Walrus Memory and verify the MCP tools are ready. +argument-hint: [optional setup question] +--- + +Use the Walrus Memory setup skill and MCP tools to connect this client. + +First call `memwal_health` if the tool is available. If credentials are missing, call `memwal_login` and guide the user through the browser wallet flow. After login, verify with `memwal_health`. + +If `$ARGUMENTS` is not empty, address this setup question too: + +```text +$ARGUMENTS +``` + diff --git a/plugin/skills/setup/SETUP.md b/plugin/skills/setup/SETUP.md new file mode 100644 index 0000000..7ad68c1 --- /dev/null +++ b/plugin/skills/setup/SETUP.md @@ -0,0 +1,83 @@ +# Walrus Memory Setup Skill + +Use this skill when a user asks to connect, test, troubleshoot, or configure Walrus Memory. + +This setup path uses local stdio MCP plus delegate-key custom-header auth through `@mysten-incubation/memwal-mcp`. It is separate from the hosted Claude custom-connector OAuth endpoint (see the warning below). + +## Fast Path + +1. Check whether the `memwal` MCP server is connected. +2. Call `memwal_health`. +3. If credentials are missing, call `memwal_login`. +4. Guide the user through the browser wallet flow. +5. Call `memwal_health` again. +6. Test save and recall with `memwal_remember` and `memwal_recall`. + +Credentials are stored locally at: + +```text +~/.memwal/credentials.json +``` + +Do not ask the user to paste this file into chat. + +## Commands + +Claude Code slash commands included: + +- `/memwal:setup` +- `/memwal:health` +- `/memwal:remember` +- `/memwal:recall` +- `/memwal:analyze` +- `/memwal:restore` +- `/memwal:logout` + +MCP tools available to Claude Code, Codex, OpenCode, Cursor, Claude Desktop, and other MCP clients: + +- `memwal_login` +- `memwal_logout` +- `memwal_health` +- `memwal_remember` +- `memwal_remember_bulk` +- `memwal_recall` +- `memwal_analyze` +- `memwal_restore` + +## Detailed Guides + +- Claude Code: `docs/usage/claude-code.md` +- Codex: `docs/usage/codex.md` +- OpenCode, Cursor, Claude Desktop: `docs/usage/other-clients.md` +- Hosted Claude custom connector: `docs/usage/hosted-connector.md` — **experimental, not production-ready, see the warning there** + +## Hosted Connector URL (experimental — do not present as ready) + +> **This flow is not yet secure or complete.** The OAuth authorization work behind it +> ([MystenLabs/MemWal#584](https://github.com/MystenLabs/MemWal/pull/584)) is still under +> active security review as of this writing. Do not tell a user this path is ready for +> production use, and do not claim `tools/list` or memory-tool calls have been verified +> working end to end. If a user asks about the hosted Claude custom connector, point them +> to the local stdio + delegate-key setup above instead, or explicitly flag this path as +> experimental/blocked. + +For reference, once the OAuth work above is accepted, Claude's native hosted custom connector UI will use: + +```text +https://relayer.dev.memwal.ai/api/mcp +``` + +Discovery endpoints: + +```text +https://relayer.dev.memwal.ai/.well-known/oauth-authorization-server +https://relayer.dev.memwal.ai/.well-known/oauth-protected-resource +``` + +## Troubleshooting + +- MCP server missing: restart the client and check the MCP config path. +- Login completed but tools still fail: restart the client so the MCP process reloads credentials. +- No Walrus Memory account: rerun `memwal_login`; the browser flow creates the account and delegate key. +- Too many delegate keys: revoke an unused key in the Walrus Memory dashboard, then retry setup. +- Recall returns nothing: run `memwal_restore` for the namespace and retry recall. diff --git a/plugin/skills/setup/SKILL.md b/plugin/skills/setup/SKILL.md new file mode 100644 index 0000000..d08b3dc --- /dev/null +++ b/plugin/skills/setup/SKILL.md @@ -0,0 +1,57 @@ +--- +name: setup +description: Set up Walrus Memory for Claude Code using the bundled MCP server and current delegate-key header authentication. Use when the user asks to connect, install, authenticate, create an account, create a delegate key, log in, verify setup, or troubleshoot Walrus Memory credentials. +--- + +# Walrus Memory Setup + +Use this skill to help a Claude Code user finish Walrus Memory setup with the plugin's bundled MCP server. + +## What This Plugin Uses + +This plugin uses the current Walrus Memory MCP package and delegate-key header authentication. It does not depend on the hosted Claude custom-connector OAuth flow. + +The plugin starts this MCP server: + +```json +{ + "mcpServers": { + "memwal": { + "command": "npx", + "args": ["-y", "@mysten-incubation/memwal-mcp", "--label", "Claude Code Plugin"] + } + } +} +``` + +Credentials are stored locally at `~/.memwal/credentials.json` with file mode `0600`. + +## Setup Flow + +1. Check whether the MCP server is connected. + - Ask the user to run `/mcp` if you cannot see MCP tool status. + - The server name should be `memwal`. + +2. If tools are available, call `memwal_health`. + - If it reports missing credentials, call `memwal_login`. + - If `memwal_login` is not available because the MCP server is not loaded, ask the user to restart Claude Code after installing/enabling the plugin. + +3. During login, the browser opens the Walrus Memory app. + - The user connects a Sui wallet. + - If no Walrus Memory account exists, the app walks the user through account creation. + - The app registers a delegate key labeled `Claude Code Plugin`. + - The local MCP package saves delegate-key credentials to `~/.memwal/credentials.json`. + +4. After login, verify with `memwal_health`. + +5. Test end-to-end: + - Save a harmless setup fact with `memwal_remember`. + - Recall it with `memwal_recall`. + +## Troubleshooting + +- If the browser flow finishes but Claude Code still says credentials are missing, restart Claude Code so the MCP process reloads. +- If the wallet already has 20 delegate keys, ask the user to open the Walrus Memory dashboard and revoke an unused key. +- If the user needs a clean login, call `memwal_logout`, then call `memwal_login` again. +- If recall returns nothing for memories that should exist, call `memwal_restore` with the relevant namespace. +