@mysten-incubation/memwal-mcp 0.0.4 → 0.0.5-dev.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mysten-incubation/memwal-mcp",
-    "version": "0.0.4",
+    "version": "0.0.5-dev.0",
     "description": "Walrus Memory MCP client — single-binary stdio MCP server that bridges Cursor / Claude Desktop / Antigravity / Claude Code to the Walrus Memory relayer. Handles browser-based wallet login on first run.",
     "type": "module",
     "engines": {
@@ -36,6 +36,7 @@
     },
     "files": [
         "dist",
+        "plugin",
         "README.md"
     ],
     "keywords": [

package/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "memwal",
+  "version": "0.0.5",
+  "description": "Automatic Walrus Memory for Claude Code — proactive recall and durable-fact saving via the MemWal MCP + lifecycle hooks.",
+  "author": {
+    "name": "Mysten Labs"
+  },
+  "homepage": "https://memory.walrus.xyz",
+  "repository": "https://github.com/MystenLabs/MemWal",
+  "license": "Apache-2.0",
+  "keywords": ["memory", "mcp", "walrus", "sui", "semantic-search"]
+}

package/plugin/.codex-mcp.json

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

package/plugin/.codex-plugin/plugin.json

@@ -0,0 +1,29 @@
+{
+  "name": "memwal",
+  "version": "0.0.5",
+  "description": "Persistent Walrus Memory for Codex. Remembers decisions, preferences, and project context across sessions.",
+  "author": {
+    "name": "Mysten Labs",
+    "url": "https://memory.walrus.xyz"
+  },
+  "homepage": "https://memory.walrus.xyz",
+  "repository": "https://github.com/MystenLabs/MemWal",
+  "license": "Apache-2.0",
+  "keywords": ["memory", "personalization", "mcp", "walrus", "semantic-search"],
+  "mcpServers": "./.codex-mcp.json",
+  "hooks": "./hooks/codex-hooks.json",
+  "interface": {
+    "displayName": "MemWal",
+    "shortDescription": "Portable, encrypted memory layer for AI coding workflows",
+    "longDescription": "MemWal adds long-term, user-owned memory to Codex. Store decisions, preferences, and session context; memories are encrypted with SEAL and stored on Walrus, and retrieved via semantic search so Codex always has the right context.",
+    "developerName": "Mysten Labs",
+    "category": "Productivity",
+    "capabilities": ["Read", "Write"],
+    "websiteURL": "https://memory.walrus.xyz",
+    "defaultPrompt": [
+      "Search my memories for recent project decisions",
+      "Remember that I prefer pnpm and TypeScript strict mode",
+      "What do you know about my coding preferences?"
+    ]
+  }
+}

package/plugin/.cursor-mcp.json

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

package/plugin/.cursor-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "memwal",
+  "version": "0.0.5",
+  "description": "Automatic Walrus Memory for Cursor — proactive recall and durable-fact saving via the MemWal MCP + lifecycle hooks.",
+  "author": { "name": "Mysten Labs" },
+  "homepage": "https://memory.walrus.xyz",
+  "repository": "https://github.com/MystenLabs/MemWal",
+  "license": "Apache-2.0",
+  "keywords": ["memory", "mcp", "walrus", "semantic-search"],
+  "hooks": "./hooks/cursor-hooks.json",
+  "mcpServers": ".cursor-mcp.json"
+}

package/plugin/hooks/codex-hooks.json

@@ -0,0 +1,41 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/scripts/on_session_start.mjs\"",
+            "statusMessage": "Loading Walrus Memory context...",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/scripts/on_user_prompt.mjs\"",
+            "statusMessage": "Checking memory relevance...",
+            "timeout": 12
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/scripts/on_post_tool.mjs\"",
+            "timeout": 12
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugin/hooks/cursor-hooks.json

@@ -0,0 +1,24 @@
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [
+      {
+        "command": "node \"${CURSOR_PLUGIN_ROOT}/scripts/on_session_start.mjs\"",
+        "matcher": "startup|resume|compact"
+      }
+    ],
+    "beforeSubmitPrompt": [
+      {
+        "command": "node \"${CURSOR_PLUGIN_ROOT}/scripts/on_user_prompt.mjs\"",
+        "timeout": 8
+      }
+    ],
+    "postToolUse": [
+      {
+        "command": "node \"${CURSOR_PLUGIN_ROOT}/scripts/on_post_tool.mjs\"",
+        "matcher": "Bash",
+        "timeout": 5
+      }
+    ]
+  }
+}

package/plugin/hooks/hooks.json

@@ -0,0 +1,41 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/on_session_start.mjs\"",
+            "statusMessage": "Loading Walrus Memory context...",
+            "timeout": 8
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/on_user_prompt.mjs\"",
+            "statusMessage": "Checking memory relevance...",
+            "timeout": 8
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/on_post_tool.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugin/hooks.json

@@ -0,0 +1,41 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "name": "memwal-session-start",
+            "type": "command",
+            "command": "node \"${extensionPath}/scripts/on_session_start.mjs\" 2>/dev/null || true"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "name": "memwal-user-prompt",
+            "type": "command",
+            "command": "node \"${extensionPath}/scripts/on_user_prompt.mjs\" 2>/dev/null || true",
+            "timeout": 8
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "name": "memwal-post-tool",
+            "type": "command",
+            "command": "node \"${extensionPath}/scripts/on_post_tool.mjs\" 2>/dev/null || true",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "id": "memwal",
+  "name": "memwal",
+  "version": "0.0.5",
+  "description": "Automatic Walrus Memory for Antigravity — proactive recall and durable-fact saving via the MemWal MCP + lifecycle hooks.",
+  "author": { "name": "Mysten Labs" },
+  "homepage": "https://memory.walrus.xyz",
+  "repository": "https://github.com/MystenLabs/MemWal",
+  "license": "Apache-2.0",
+  "keywords": ["memory", "mcp", "walrus", "sui", "semantic-search"],
+  "contextFileName": "AGENTS.md"
+}

package/plugin/scripts/install_codex_hooks.mjs

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+/**
+ * Install MemWal lifecycle hooks into ~/.codex/hooks.json and register the
+ * MemWal MCP server in ~/.codex/config.toml.
+ *
+ * Codex discovers hooks only at ~/.codex/hooks.json (or <repo>/.codex/hooks.json)
+ * and has no plugin host that auto-wires hooks. This installer reads the
+ * template at hooks/codex-hooks.json, rewrites the ${PLUGIN_ROOT} placeholder
+ * to this plugin's absolute path, and merges the entries into ~/.codex/hooks.json.
+ *
+ * Re-running is idempotent: entries this installer owns (identified by our
+ * hook script filenames) are removed before fresh entries are added.
+ *
+ * Usage:
+ *   node install_codex_hooks.mjs              # install or update
+ *   node install_codex_hooks.mjs --uninstall  # remove MemWal hook entries
+ *
+ * After installing, enable the Codex hooks feature flag in ~/.codex/config.toml:
+ *
+ *   [features]
+ *   codex_hooks = true
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
+const PLUGIN_ROOT = dirname(SCRIPT_DIR);
+
+const CODEX_DIR = join(homedir(), ".codex");
+const HOOKS_FILE = join(CODEX_DIR, "hooks.json");
+const CONFIG_FILE = join(CODEX_DIR, "config.toml");
+const TEMPLATE_FILE = join(PLUGIN_ROOT, "hooks", "codex-hooks.json");
+
+// Entries are "ours" when a hook command references one of our scripts.
+const OWNER_MARKERS = [
+    "on_session_start.mjs",
+    "on_user_prompt.mjs",
+    "on_post_tool.mjs",
+];
+
+function loadTemplate() {
+    const raw = readFileSync(TEMPLATE_FILE, "utf8").replaceAll(
+        "${PLUGIN_ROOT}",
+        PLUGIN_ROOT
+    );
+    return JSON.parse(raw);
+}
+
+function loadExisting() {
+    if (!existsSync(HOOKS_FILE)) return { hooks: {} };
+    try {
+        return JSON.parse(readFileSync(HOOKS_FILE, "utf8"));
+    } catch (e) {
+        console.error(`error: failed to read ${HOOKS_FILE}: ${e.message}`);
+        process.exit(1);
+    }
+}
+
+function isOwned(entry) {
+    for (const hook of entry.hooks || []) {
+        const cmd = hook.command || "";
+        if (OWNER_MARKERS.some((m) => cmd.includes(m))) return true;
+    }
+    return false;
+}
+
+function stripOwned(config) {
+    const hooks = config.hooks || {};
+    for (const event of Object.keys(hooks)) {
+        hooks[event] = (hooks[event] || []).filter((e) => !isOwned(e));
+        if (hooks[event].length === 0) delete hooks[event];
+    }
+    config.hooks = hooks;
+    return config;
+}
+
+function mergeTemplate(config, template) {
+    config.hooks = config.hooks || {};
+    for (const [event, entries] of Object.entries(template.hooks || {})) {
+        config.hooks[event] = (config.hooks[event] || []).concat(entries);
+    }
+    return config;
+}
+
+function writeHooks(config) {
+    mkdirSync(CODEX_DIR, { recursive: true });
+    writeFileSync(HOOKS_FILE, JSON.stringify(config, null, 2) + "\n");
+}
+
+/** Append [mcp_servers.memwal] to config.toml if it isn't registered yet. */
+function ensureMcpRegistered() {
+    mkdirSync(CODEX_DIR, { recursive: true });
+    let content = existsSync(CONFIG_FILE) ? readFileSync(CONFIG_FILE, "utf8") : "";
+    if (content.includes("[mcp_servers.memwal]")) return false;
+    const block =
+        "\n[mcp_servers.memwal]\n" +
+        'command = "npx"\n' +
+        'args = ["-y", "@mysten-incubation/memwal-mcp"]\n';
+    writeFileSync(CONFIG_FILE, (content.trimEnd() + "\n" + block).trimStart());
+    return true;
+}
+
+function featureFlagEnabled() {
+    if (!existsSync(CONFIG_FILE)) return false;
+    return readFileSync(CONFIG_FILE, "utf8")
+        .split("\n")
+        .map((l) => l.split("#", 1)[0].replace(/\s/g, ""))
+        .includes("codex_hooks=true");
+}
+
+function printFeatureFlagHint() {
+    console.log("");
+    console.log("Codex hooks feature flag is not enabled.");
+    console.log(`Add this to ${CONFIG_FILE}:`);
+    console.log("");
+    console.log("  [features]");
+    console.log("  codex_hooks = true");
+    console.log("");
+    console.log("Then restart Codex.");
+}
+
+function main() {
+    const uninstall = process.argv.includes("--uninstall");
+    let config = loadExisting();
+
+    if (uninstall) {
+        config = stripOwned(config);
+        writeHooks(config);
+        console.log(`Removed MemWal hooks from ${HOOKS_FILE}`);
+        console.log(
+            "(The [mcp_servers.memwal] entry in config.toml was left in place — remove it manually if you no longer want the tools.)"
+        );
+        return 0;
+    }
+
+    if (!existsSync(TEMPLATE_FILE)) {
+        console.error(`error: template not found at ${TEMPLATE_FILE}`);
+        return 1;
+    }
+
+    const template = loadTemplate();
+    config = stripOwned(config);
+    config = mergeTemplate(config, template);
+    writeHooks(config);
+
+    const mcpAdded = ensureMcpRegistered();
+
+    console.log(`Installed MemWal hooks into ${HOOKS_FILE}`);
+    console.log(`Plugin path: ${PLUGIN_ROOT}`);
+    console.log("Events: SessionStart, UserPromptSubmit, PostToolUse");
+    console.log(
+        mcpAdded
+            ? `Registered [mcp_servers.memwal] in ${CONFIG_FILE}`
+            : `[mcp_servers.memwal] already present in ${CONFIG_FILE}`
+    );
+
+    if (!featureFlagEnabled()) printFeatureFlagHint();
+    return 0;
+}
+
+process.exit(main());

package/plugin/scripts/lib/hook-io.mjs

@@ -0,0 +1,81 @@
+/**
+ * Shared I/O + throttle helpers for MemWal Claude Code / Codex hooks.
+ *
+ * Pure Node, no dependencies, no network. Every hook reads one JSON object
+ * from stdin, optionally emits a `hookSpecificOutput` directive on stdout,
+ * and always exits 0 — a hook must never block the session.
+ */
+import { readFileSync, existsSync, writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/** Read + parse the hook input JSON from stdin. Returns {} on any error. */
+export function readStdin() {
+    try {
+        const raw = readFileSync(0, "utf8");
+        return raw ? JSON.parse(raw) : {};
+    } catch {
+        return {};
+    }
+}
+
+/** Emit a hook directive. No-op when `additionalContext` is empty. */
+export function emitContext(hookEventName, additionalContext) {
+    if (!additionalContext) return;
+    process.stdout.write(
+        JSON.stringify({
+            hookSpecificOutput: { hookEventName, additionalContext },
+        })
+    );
+}
+
+const STATE_DIR = join(process.env.TMPDIR || tmpdir(), "memwal-hooks");
+
+function ensureDir() {
+    try {
+        mkdirSync(STATE_DIR, { recursive: true });
+    } catch {
+        /* best effort */
+    }
+}
+
+function safe(s) {
+    return String(s || "default")
+        .replace(/[^a-zA-Z0-9_-]/g, "_")
+        .slice(0, 64);
+}
+
+/**
+ * Returns true the FIRST time it is called for a (name, session) pair, then
+ * false thereafter — used to inject a rubric or banner only once per session.
+ */
+export function firstTime(name, sessionId) {
+    ensureDir();
+    const f = join(STATE_DIR, `${safe(name)}_${safe(sessionId)}`);
+    if (existsSync(f)) return false;
+    try {
+        writeFileSync(f, "1");
+    } catch {
+        /* best effort */
+    }
+    return true;
+}
+
+/** Increment and return a per-(name, session) counter. */
+export function bumpCounter(name, sessionId) {
+    ensureDir();
+    const f = join(STATE_DIR, `count_${safe(name)}_${safe(sessionId)}`);
+    let n = 0;
+    try {
+        n = parseInt(readFileSync(f, "utf8"), 10) || 0;
+    } catch {
+        /* missing -> 0 */
+    }
+    n += 1;
+    try {
+        writeFileSync(f, String(n));
+    } catch {
+        /* best effort */
+    }
+    return n;
+}

package/plugin/scripts/lib/signals.mjs

@@ -0,0 +1,38 @@
+/**
+ * Heuristic signal detection over user input / tool output. No network, no
+ * LLM — cheap regexes only. The agent (guided by the now-agentic tool
+ * descriptions) makes the final call; these just decide when to *remind* it.
+ */
+
+// User is referencing earlier context / asking to resume.
+const RECALL_INTENT =
+    /\b(remember when|last time|previously|earlier|where (did|were) we|pick up where|catch me up|as i (said|mentioned|told you)|like i said|we (already|previously) (did|decided|discussed|set up)|my (usual|preferred|preference|setup|config|stack))\b/i;
+
+// User is stating a durable fact / preference / correction worth saving.
+const REMEMBER_INTENT =
+    /\b(remember (this|that)|don'?t forget|note that|for future reference|keep in mind|from now on|going forward|i (prefer|like|love|hate|always|never|usually|use|work with|am|m)\b|my name is|call me|i'?m (using|on)|we (use|prefer|standardi[sz]e on))\b/i;
+
+// Strong error markers in command output.
+// No trailing \b: markers ending in `:` (panic:, fatal:) or `]` (error[E0432])
+// are followed by a non-word char, so a closing \b would never match them.
+const ERROR_STRONG =
+    /\b(traceback \(most recent|panic:|fatal:|segmentation fault|unhandled (exception|rejection)|error\[[A-Z]?\d+\]|cannot find module|command not found|permission denied|no such file)/i;
+const ERROR_PAIR = /(^|\s)(error:|exception:|failed:|fail:|err!)/gi;
+
+/** True when the user's message references past context worth recalling. */
+export function detectRecall(text) {
+    return !!text && RECALL_INTENT.test(text);
+}
+
+/** True when the user's message states a durable fact worth remembering. */
+export function detectRemember(text) {
+    return !!text && REMEMBER_INTENT.test(text);
+}
+
+/** True when command output looks like an error/traceback. */
+export function detectError(text) {
+    if (!text) return false;
+    if (ERROR_STRONG.test(text)) return true;
+    const m = text.match(ERROR_PAIR);
+    return !!m && m.length >= 2;
+}

package/plugin/scripts/on_post_tool.mjs

@@ -0,0 +1,45 @@
+/**
+ * PostToolUse hook (Bash) — when a command's output looks like an error,
+ * remind the agent it can recall prior fixes and save the resolution.
+ *
+ * Heuristic only: no fetch, no network. Always exits 0.
+ */
+import { readStdin, emitContext } from "./lib/hook-io.mjs";
+import { detectError } from "./lib/signals.mjs";
+
+const input = readStdin();
+const output = extractToolOutput(input);
+
+// Ignore short / empty output — not enough to reason about.
+if (!output || output.length < 50) process.exit(0);
+
+if (detectError(output)) {
+    emitContext(
+        "PostToolUse",
+        "That command produced an error. Consider calling memwal_recall to check for a prior fix to a similar error; once you resolve it, save the fix with memwal_remember so it's available next time."
+    );
+}
+
+process.exit(0);
+
+/** Best-effort extraction of a tool's textual output across hook-input shapes. */
+function extractToolOutput(input) {
+    const r =
+        input.tool_response ??
+        input.tool_result ??
+        input.response ??
+        input.output ??
+        "";
+    if (typeof r === "string") return r;
+    if (r && typeof r === "object") {
+        if (typeof r.stdout === "string" || typeof r.stderr === "string") {
+            return `${r.stdout || ""}\n${r.stderr || ""}`;
+        }
+        try {
+            return JSON.stringify(r);
+        } catch {
+            return "";
+        }
+    }
+    return "";
+}

package/plugin/scripts/on_session_start.mjs

@@ -0,0 +1,18 @@
+/**
+ * SessionStart hook — announce that Walrus Memory is active and remind the
+ * agent how/when to use it. No fetch, no network.
+ */
+import { readStdin, emitContext } from "./lib/hook-io.mjs";
+
+readStdin(); // drain stdin; we don't need any field today
+const ns = process.env.MEMWAL_NAMESPACE || "default";
+
+const context = [
+    `Walrus Memory is this user's memory system, exposed via the memwal_* tools (namespace: ${ns}).`,
+    "Use it as the PRIMARY place to store and recall durable facts — prefer the memwal_* tools over any built-in or local memory feature, so the user's memory stays portable and persistent on Walrus.",
+    "When you learn a durable fact (preference, decision, constraint, correction, identity), save it with memwal_remember (or memwal_remember_bulk for several at once); before tasks that reference past work or the user's preferences, recall with memwal_recall.",
+    "If memwal_recall unexpectedly returns nothing for a namespace you've used before, run memwal_restore to rebuild the index from Walrus.",
+].join(" ");
+
+emitContext("SessionStart", context);
+process.exit(0);

package/plugin/scripts/on_user_prompt.mjs

@@ -0,0 +1,41 @@
+/**
+ * UserPromptSubmit hook — decide, from the user's input, whether the agent
+ * should recall context or save a fact, and inject a short directive saying so.
+ *
+ * Heuristic only: no fetch, no network. The agent does the actual tool call.
+ */
+import { readStdin, emitContext, firstTime } from "./lib/hook-io.mjs";
+import { detectRecall, detectRemember } from "./lib/signals.mjs";
+
+const input = readStdin();
+const prompt = (input.prompt || "").toString();
+const sessionId = input.session_id || "default";
+
+// Skip very short prompts (acks, single words) — nothing useful to act on.
+if (prompt.trim().length < 20) process.exit(0);
+
+const parts = [];
+
+if (detectRecall(prompt)) {
+    parts.push(
+        "The user is referencing earlier work or context. Before answering, call memwal_recall (Walrus Memory) with a focused query — use the memwal_* tools, not any built-in memory, so recall stays portable."
+    );
+}
+
+if (detectRemember(prompt)) {
+    parts.push(
+        "The user just stated a durable fact or preference. Save it with memwal_remember (or memwal_remember_bulk for several distinct facts) — prefer the memwal_* tools over any built-in memory so the fact persists on Walrus across sessions and agents."
+    );
+}
+
+// When no strong signal fired, inject the general rubric once per session so
+// the agent knows the tools exist, when to reach for them, and to prefer them
+// over any built-in memory feature.
+if (parts.length === 0 && firstTime("rubric", sessionId)) {
+    parts.push(
+        "Walrus Memory (the memwal_* tools) is this user's primary memory system — prefer it over any built-in memory. Call memwal_recall proactively when the user references past work, decisions, or preferences; save durable facts with memwal_remember (or memwal_remember_bulk for several) as you learn them — you don't need to be asked."
+    );
+}
+
+emitContext("UserPromptSubmit", parts.join(" "));
+process.exit(0);