memento-mcp 0.3.19 → 0.4.0

package/CHANGELOG.md

@@ -6,6 +6,22 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Version
 
 ---
 
+## [0.4.0] - 2026-03-22
+
+### Changed
+- **Combined recall**: UserPromptSubmit hook now reads cached assistant message and makes one `/v1/context` call with both user + assistant context (was two separate API calls per turn).
+- **Stop hook replaced**: `memento-stop-recall.sh` (blocking API call with `decision: 'block'`) replaced by `memento-stop-cache.sh` (fast file write, no API call, no blocking).
+- Default recall limit increased from 5 to 10.
+- Config key `stop-recall` renamed to `stop-cache` in `.memento.json`.
+
+### Migration
+- Run `npx memento-mcp update` to migrate existing installations automatically. The update command removes old stop-recall hooks from agent settings, registers the new stop-cache hook, renames the config key, and deletes the orphaned script.
+
+### Removed
+- `memento-stop-recall.sh` — no longer distributed.
+
+---
+
 ## [0.3.15] - 2026-03-13
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memento-mcp",
-  "version": "0.3.19",
+  "version": "0.4.0",
   "mcpName": "io.github.myrakrusemark/memento-protocol",
   "description": "The Memento Protocol — persistent memory for AI agents",
   "type": "module",
@@ -28,6 +28,7 @@
   "files": [
     "src/",
     "scripts/",
+    "templates/",
     "docs/",
     "LICENSE",
     "README.md",

package/scripts/README.md

@@ -25,8 +25,8 @@ Memento hooks work with three CLI agents. Each has a different hook system, but
 | Script | What it does |
 |--------|-------------|
 | `memento-sessionstart-identity.sh` | Injects identity crystal + version check at session start |
-| `memento-userprompt-recall.sh` | Recalls memories relevant to the user's message |
-| `memento-stop-recall.sh` | Recalls memories from the assistant's own output |
+| `memento-userprompt-recall.sh` | Recalls memories from user message + cached assistant context |
+| `memento-stop-cache.sh` | Caches the assistant's last message for combined recall |
 | `memento-precompact-distill.sh` | Extracts memories from the conversation before context compression |
 | `memento-codex-notify.sh` | Stores post-turn summaries from Codex CLI as memory observations |
 
@@ -105,8 +105,8 @@ Add to `.claude/settings.local.json` (project-level) or `~/.claude/settings.json
       {
         "hooks": [{
           "type": "command",
-          "command": "bash .memento/scripts/memento-stop-recall.sh",
-          "timeout": 5000
+          "command": "bash .memento/scripts/memento-stop-cache.sh",
+          "timeout": 2000
         }]
       }
     ],
@@ -152,8 +152,8 @@ Add to `.gemini/settings.json`:
       {
         "hooks": [{
           "type": "command",
-          "command": "bash .memento/scripts/memento-stop-recall.sh",
-          "timeout": 5000
+          "command": "bash .memento/scripts/memento-stop-cache.sh",
+          "timeout": 2000
         }]
       }
     ],
@@ -203,19 +203,20 @@ Fires before every agent response. Sends the user's message to `/v1/context`, wh
 
 **Output format:** JSON with `systemMessage` (user display) + `hookSpecificOutput.additionalContext` (model context).
 
-### `memento-stop-recall.sh` — Stop / SessionEnd
+### `memento-stop-cache.sh` — Stop / SessionEnd
 
-Fires after every assistant response. Uses the assistant's own output as the recall query — so memories surface during autonomous work, not just on user messages.
+Lightweight caching shim that fires after every assistant response. Writes the assistant's last message to a temp file (`/tmp/memento-last-assistant-{workspace}`) so the UserPromptSubmit hook can build a combined recall query from both messages.
 
-- **Timeout:** 5 seconds
-- **User sees:** "Autonomous Recall: N memories"
-- **Model sees:** Full memory content via the `decision: "block"` mechanism — the `reason` field becomes the model's next instruction
-- **Loop prevention:** Checks `stop_hook_active` flag to prevent infinite recall loops
+- **Timeout:** 2 seconds
+- **No API calls, no blocking, no output**
+- **Loop prevention:** Checks `stop_hook_active` flag (preserved for safety)
 - **Empty responses:** Skipped when the assistant message is empty
+- **Cache format:** Line 1 = epoch timestamp, lines 2+ = raw message text
+- **Cache TTL:** 10 minutes (the userprompt hook ignores stale cache files)
 
-**Output format:** JSON with `decision: "block"`, `reason` (model context), and `systemMessage` (user display). The block mechanism is the only way to inject content into model context from a Stop hook — `additionalContext` is not supported for Stop events.
+**Output format:** None — exits cleanly with no stdout.
 
-**Why this matters:** Without the Stop hook, memories only surface when a human sends a message. For autonomous agents that work independently — running ping routines, doing research, monitoring news — their own memories never get recalled. The Stop hook closes that gap.
+**How it works with userprompt-recall:** The UserPromptSubmit hook reads the cached assistant message, combines it with the current user message (`{user:500} --- {assistant:300}`), and makes a single `/v1/context` call. This replaces the old two-API-call pattern where stop-recall and userprompt-recall each made independent calls.
 
 ### `memento-precompact-distill.sh` — PreCompact / PreCompress
 

package/scripts/memento-stop-cache.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+# Memento stop-cache — lightweight shim that caches the assistant's last message.
+# The UserPromptSubmit hook reads this cache to build a combined recall query.
+# No API calls, no blocking — just a fast file write.
+
+INPUT=$(cat)
+
+# Prevent infinite loops (preserved from stop-recall for safety)
+STOP_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active // false' 2>/dev/null)
+if [ "$STOP_ACTIVE" = "true" ]; then
+    exit 0
+fi
+
+ASSISTANT_MSG=$(echo "$INPUT" | jq -r '.last_assistant_message // empty' 2>/dev/null)
+if [ -z "$ASSISTANT_MSG" ]; then
+    exit 0
+fi
+
+# --- Resolve workspace name from .memento.json or env ---
+MEMENTO_WS="${MEMENTO_WORKSPACE:-}"
+if [ -z "$MEMENTO_WS" ]; then
+    MEMENTO_WS=$(python3 -c "
+import json, os
+d = os.getcwd()
+while True:
+    p = os.path.join(d, '.memento.json')
+    if os.path.isfile(p):
+        with open(p) as f:
+            print(json.load(f).get('workspace', 'default'))
+        break
+    parent = os.path.dirname(d)
+    if parent == d:
+        print('default')
+        break
+    d = parent
+" 2>/dev/null)
+fi
+MEMENTO_WS="${MEMENTO_WS:-default}"
+
+# Write cache: epoch timestamp on line 1, message on lines 2+
+CACHE_FILE="/tmp/memento-last-assistant-${MEMENTO_WS}"
+echo "$(date +%s)" > "$CACHE_FILE"
+echo "$ASSISTANT_MSG" >> "$CACHE_FILE"
+
+exit 0

package/scripts/memento-userprompt-recall.sh

@@ -69,7 +69,25 @@ if [ -z "$USER_MESSAGE" ] || [ ${#USER_MESSAGE} -lt 10 ]; then
     exit 0
 fi
 
-QUERY="${USER_MESSAGE:0:500}"
+# --- Read cached assistant message (written by stop-cache hook) ---
+CACHE_FILE="/tmp/memento-last-assistant-${MEMENTO_WS}"
+CACHED_ASSISTANT=""
+if [ -f "$CACHE_FILE" ]; then
+    CACHE_TS=$(head -1 "$CACHE_FILE")
+    NOW=$(date +%s)
+    AGE=$(( NOW - CACHE_TS ))
+    if [ "$AGE" -lt 600 ]; then
+        CACHED_ASSISTANT=$(tail -n +2 "$CACHE_FILE")
+    fi
+    rm -f "$CACHE_FILE"
+fi
+
+# Build query: user message + cached assistant context (if available)
+if [ -n "$CACHED_ASSISTANT" ]; then
+    QUERY="${USER_MESSAGE:0:500} --- ${CACHED_ASSISTANT:0:300}"
+else
+    QUERY="${USER_MESSAGE:0:500}"
+fi
 
 # --- Image detection ---
 # Collect up to 3 images from two sources:
@@ -202,7 +220,7 @@ try:
 
     memories = data.get('memories', {}).get('matches', [])
     if memories:
-        for m in memories[:${RECALL_LIMIT:-7}]:
+        for m in memories[:${RECALL_LIMIT:-10}]:
             content = m['content']
             t = abbrev.get(m['type'], m['type'])
             lines.append(f'  🔹 {content} [{m[\"id\"]} {t}]')

package/src/cli.js

@@ -97,7 +97,7 @@ function httpsPost(url, body) {
 // ---------------------------------------------------------------------------
 
 function parseFlags(argv) {
-  const flags = { nonInteractive: false, apiKey: null, agent: null };
+  const flags = { nonInteractive: false, apiKey: null, agent: null, provision: false };
   for (let i = 0; i < argv.length; i++) {
     if (argv[i] === "-y" || argv[i] === "--yes") {
       flags.nonInteractive = true;
@@ -107,6 +107,8 @@ function parseFlags(argv) {
     } else if (argv[i] === "--agent" && argv[i + 1]) {
       flags.agent = argv[i + 1];
       i++;
+    } else if (argv[i] === "--provision") {
+      flags.provision = true;
     }
   }
   // Also check environment variable
@@ -153,6 +155,24 @@ function ensureHook(settings, eventName, command, timeout) {
   return true;
 }
 
+/**
+ * Remove a hook entry whose command contains the given substring.
+ * Returns true if something was removed.
+ */
+function removeHook(settings, eventName, commandSubstring) {
+  const existing = settings.hooks?.[eventName] || [];
+  const filtered = existing.filter(
+    (entry) => !entry.hooks?.some((h) => h.command?.includes(commandSubstring))
+  );
+  if (filtered.length === existing.length) return false;
+  if (filtered.length > 0) {
+    settings.hooks[eventName] = filtered;
+  } else {
+    delete settings.hooks[eventName];
+  }
+  return true;
+}
+
 function appendToGitignore(cwd, line) {
   const gitignorePath = path.join(cwd, ".gitignore");
   if (fs.existsSync(gitignorePath)) {
@@ -224,7 +244,9 @@ export { AGENTS, writeMcpJson, writeGeminiJson };
 // ---------------------------------------------------------------------------
 
 async function runInit(flags = {}) {
-  const { nonInteractive = false, apiKey: flagApiKey = null, agent: flagAgent = null } = flags;
+  const { nonInteractive = false, apiKey: flagApiKey = null, agent: flagAgent = null, provision = false } = flags;
+  // Re-attach provision to flags so the signup block can check it
+  flags.provision = provision;
   const cwd = process.cwd();
   const projectName = path.basename(cwd);
 
@@ -253,39 +275,56 @@ async function runInit(flags = {}) {
   }
   if (!apiKey) {
     if (nonInteractive) {
-      // 5-second countdown warning, then auto-signup
-      process.stderr.write(
-        "\n  No API key provided — a new one will be generated.\n" +
-        "  Press Ctrl+C to cancel.\n  "
-      );
-      for (let i = 5; i > 0; i--) {
-        process.stderr.write(`${i}... `);
-        await new Promise((r) => setTimeout(r, 1000));
-      }
-      process.stderr.write("\n\n");
-    }
-    const email = nonInteractive ? "" : await ask(rl, "Email for account recovery (optional)");
-    console.log("\nSigning up...");
-    try {
-      const body = { workspace };
-      if (email) body.email = email;
-      const resp = await httpsPost(`${DEFAULTS.apiUrl}/v1/auth/signup`, body);
-      if (resp.api_key) {
-        apiKey = resp.api_key;
-        console.log(`  API key: ${apiKey}`);
-      } else if (resp.error) {
-        console.error(`  Signup failed: ${resp.error}`);
-        rl?.close();
-        process.exit(1);
+      // In non-interactive mode, skip signup unless --provision is passed
+      // The expected path for container workspaces is MEMENTO_API_KEY env var
+      if (!flags.provision) {
+        console.log("\n  ⚠ No API key provided (--api-key or MEMENTO_API_KEY env var).");
+        console.log("  Skipping signup. Pass --provision to auto-provision a new key.\n");
       } else {
-        console.error("  Unexpected response:", JSON.stringify(resp));
+        // --provision explicitly passed: auto-signup
+        console.log("\nSigning up...");
+        try {
+          const body = { workspace };
+          const resp = await httpsPost(`${DEFAULTS.apiUrl}/v1/auth/signup`, body);
+          if (resp.api_key) {
+            apiKey = resp.api_key;
+            console.log(`  API key: ${apiKey}`);
+          } else if (resp.error) {
+            console.error(`  Signup failed: ${resp.error}`);
+            process.exit(1);
+          } else {
+            console.error("  Unexpected response:", JSON.stringify(resp));
+            process.exit(1);
+          }
+        } catch (err) {
+          console.error(`  Signup failed: ${err.message}`);
+          process.exit(1);
+        }
+      }
+    } else {
+      const email = await ask(rl, "Email for account recovery (optional)");
+      console.log("\nSigning up...");
+      try {
+        const body = { workspace };
+        if (email) body.email = email;
+        const resp = await httpsPost(`${DEFAULTS.apiUrl}/v1/auth/signup`, body);
+        if (resp.api_key) {
+          apiKey = resp.api_key;
+          console.log(`  API key: ${apiKey}`);
+        } else if (resp.error) {
+          console.error(`  Signup failed: ${resp.error}`);
+          rl?.close();
+          process.exit(1);
+        } else {
+          console.error("  Unexpected response:", JSON.stringify(resp));
+          rl?.close();
+          process.exit(1);
+        }
+      } catch (err) {
+        console.error(`  Signup failed: ${err.message}`);
         rl?.close();
         process.exit(1);
       }
-    } catch (err) {
-      console.error(`  Signup failed: ${err.message}`);
-      rl?.close();
-      process.exit(1);
     }
   }
 
@@ -387,7 +426,7 @@ async function runInit(flags = {}) {
         "  Prompt recall — recall on every message?",
         true,
       );
-      enableStop = await askYesNo(rl, "  Stop — autonomous recall after responses?", true);
+      enableStop = await askYesNo(rl, "  Stop — cache assistant message for combined recall?", true);
       enablePreCompact = await askYesNo(
         rl,
         "  PreCompact — distill memories before context compression?",
@@ -416,7 +455,7 @@ async function runInit(flags = {}) {
     },
     hooks: {
       "userprompt-recall": { enabled: enableUserPrompt },
-      "stop-recall": { enabled: enableStop },
+      "stop-cache": { enabled: enableStop },
       "precompact-distill": { enabled: enablePreCompact },
       "sessionstart-identity": { enabled: enableSessionStart },
     },
@@ -441,7 +480,7 @@ async function runInit(flags = {}) {
       "hook-toast.sh",
       "memento-instructions.sh",
       enableUserPrompt && "memento-userprompt-recall.sh",
-      enableStop && "memento-stop-recall.sh",
+      enableStop && "memento-stop-cache.sh",
       enablePreCompact && "memento-precompact-distill.sh",
       enableSessionStart && "memento-sessionstart-identity.sh",
     ].filter(Boolean);
@@ -464,7 +503,7 @@ async function runInit(flags = {}) {
     // Hook script commands (absolute paths)
     const instructionsCmd = path.join(localScriptsDir, "memento-instructions.sh");
     const recallCmd = path.join(localScriptsDir, "memento-userprompt-recall.sh");
-    const stopCmd = path.join(localScriptsDir, "memento-stop-recall.sh");
+    const stopCmd = path.join(localScriptsDir, "memento-stop-cache.sh");
     const precompactCmd = path.join(localScriptsDir, "memento-precompact-distill.sh");
     const sessionStartCmd = path.join(localScriptsDir, "memento-sessionstart-identity.sh");
 
@@ -476,7 +515,7 @@ async function runInit(flags = {}) {
       // Instructions hook always registered (not gated by enableSessionStart)
       changed = ensureHook(settings, "SessionStart", instructionsCmd, 5000) || changed;
       if (enableUserPrompt) changed = ensureHook(settings, "UserPromptSubmit", recallCmd, 5000) || changed;
-      if (enableStop) changed = ensureHook(settings, "Stop", stopCmd, 5000) || changed;
+      if (enableStop) changed = ensureHook(settings, "Stop", stopCmd, 2000) || changed;
       if (enablePreCompact) changed = ensureHook(settings, "PreCompact", precompactCmd, 30000) || changed;
       if (enableSessionStart) changed = ensureHook(settings, "SessionStart", sessionStartCmd, 10000) || changed;
       if (changed) {
@@ -493,7 +532,7 @@ async function runInit(flags = {}) {
       // Instructions hook always registered
       changed = ensureHook(settings, "SessionStart", instructionsCmd, 5000) || changed;
       if (enableUserPrompt) changed = ensureHook(settings, "BeforeAgent", recallCmd, 5000) || changed;
-      if (enableStop) changed = ensureHook(settings, "SessionEnd", stopCmd, 5000) || changed;
+      if (enableStop) changed = ensureHook(settings, "SessionEnd", stopCmd, 2000) || changed;
       if (enablePreCompact) changed = ensureHook(settings, "PreCompress", precompactCmd, 30000) || changed;
       if (enableSessionStart) changed = ensureHook(settings, "SessionStart", sessionStartCmd, 10000) || changed;
       if (changed) {
@@ -510,6 +549,25 @@ async function runInit(flags = {}) {
     created.push(result);
   }
 
+  // 9b. CLAUDE.md — append Memento portable section
+  const claudeMdPath = path.join(cwd, "CLAUDE.md");
+  const mementoTemplatePath = path.resolve(__dirname, "..", "templates", "CLAUDE-SECTION.md");
+  try {
+    const section = fs.readFileSync(mementoTemplatePath, "utf-8");
+    if (fs.existsSync(claudeMdPath)) {
+      const existing = fs.readFileSync(claudeMdPath, "utf-8");
+      if (existing.includes("Memento MCP")) {
+        console.log("  · CLAUDE.md (already has memento section)");
+      } else {
+        fs.appendFileSync(claudeMdPath, "\n" + section);
+        created.push("CLAUDE.md (memento section appended)");
+      }
+    } else {
+      fs.writeFileSync(claudeMdPath, section);
+      created.push("CLAUDE.md (created with memento section)");
+    }
+  } catch { /* template not found — skip silently */ }
+
   // 10. Add .memento.json and .memento/scripts/ to .gitignore
   let gitignoreUpdated = false;
   if (appendToGitignore(cwd, ".memento.json")) gitignoreUpdated = true;
@@ -524,6 +582,8 @@ async function runInit(flags = {}) {
     ".mcp.json": "MCP server registered (Claude Code)",
     ".gemini/settings.json": "MCP server registered (Gemini CLI)",
     ".gemini/settings.json (hooks)": "hooks registered with Gemini CLI",
+    "CLAUDE.md (memento section appended)": "portable Memento instructions",
+    "CLAUDE.md (created with memento section)": "portable Memento instructions",
     "(skipped — manual setup)": "MCP config skipped (manual setup)",
     ".gitignore (updated)": "credentials excluded from git",
   };
@@ -606,16 +666,34 @@ async function runUpdate() {
   // Hook script paths
   const instructionsCmd = path.join(localScriptsDir, "memento-instructions.sh");
   const recallCmd = path.join(localScriptsDir, "memento-userprompt-recall.sh");
-  const stopCmd = path.join(localScriptsDir, "memento-stop-recall.sh");
+  const stopCmd = path.join(localScriptsDir, "memento-stop-cache.sh");
   const precompactCmd = path.join(localScriptsDir, "memento-precompact-distill.sh");
   const sessionStartCmd = path.join(localScriptsDir, "memento-sessionstart-identity.sh");
 
-  // Hook enabled flags (default to true for recall/stop/precompact if not specified)
+  // Hook enabled flags — check both old "stop-recall" and new "stop-cache" keys
   const enableUserPrompt = hooks["userprompt-recall"]?.enabled !== false;
-  const enableStop = hooks["stop-recall"]?.enabled !== false;
+  const enableStop = (hooks["stop-cache"]?.enabled ?? hooks["stop-recall"]?.enabled) !== false;
   const enablePreCompact = hooks["precompact-distill"]?.enabled !== false;
   const enableSessionStart = hooks["sessionstart-identity"]?.enabled && features.identity;
 
+  // --- Migration: stop-recall → stop-cache ---
+  const migrations = [];
+
+  // Migrate .memento.json config key
+  if (hooks["stop-recall"] !== undefined) {
+    config.hooks["stop-cache"] = config.hooks["stop-recall"];
+    delete config.hooks["stop-recall"];
+    writeJsonFile(configPath, config);
+    migrations.push(".memento.json: stop-recall → stop-cache");
+  }
+
+  // Delete orphaned stop-recall script
+  const oldStopPath = path.join(localScriptsDir, "memento-stop-recall.sh");
+  if (fs.existsSync(oldStopPath)) {
+    fs.unlinkSync(oldStopPath);
+    migrations.push("Deleted .memento/scripts/memento-stop-recall.sh");
+  }
+
   const registeredHooks = [];
 
   // Claude Code
@@ -625,9 +703,11 @@ async function runUpdate() {
     const settingsPath = path.join(cwd, ".claude", "settings.local.json");
     const settings = readJsonFile(settingsPath) || {};
     let changed = false;
+    // Remove old stop-recall hook
+    changed = removeHook(settings, "Stop", "memento-stop-recall.sh") || changed;
     changed = ensureHook(settings, "SessionStart", instructionsCmd, 5000) || changed;
     if (enableUserPrompt) changed = ensureHook(settings, "UserPromptSubmit", recallCmd, 5000) || changed;
-    if (enableStop) changed = ensureHook(settings, "Stop", stopCmd, 5000) || changed;
+    if (enableStop) changed = ensureHook(settings, "Stop", stopCmd, 2000) || changed;
     if (enablePreCompact) changed = ensureHook(settings, "PreCompact", precompactCmd, 30000) || changed;
     if (enableSessionStart) changed = ensureHook(settings, "SessionStart", sessionStartCmd, 10000) || changed;
     if (changed) {
@@ -643,9 +723,11 @@ async function runUpdate() {
     const settingsPath = path.join(cwd, ".gemini", "settings.json");
     const settings = readJsonFile(settingsPath) || {};
     let changed = false;
+    // Remove old stop-recall hook
+    changed = removeHook(settings, "SessionEnd", "memento-stop-recall.sh") || changed;
     changed = ensureHook(settings, "SessionStart", instructionsCmd, 5000) || changed;
     if (enableUserPrompt) changed = ensureHook(settings, "BeforeAgent", recallCmd, 5000) || changed;
-    if (enableStop) changed = ensureHook(settings, "SessionEnd", stopCmd, 5000) || changed;
+    if (enableStop) changed = ensureHook(settings, "SessionEnd", stopCmd, 2000) || changed;
     if (enablePreCompact) changed = ensureHook(settings, "PreCompress", precompactCmd, 30000) || changed;
     if (enableSessionStart) changed = ensureHook(settings, "SessionStart", sessionStartCmd, 10000) || changed;
     if (changed) {
@@ -655,6 +737,13 @@ async function runUpdate() {
   }
 
   console.log(`\n  ✓ Memento hooks updated to v${pkgVersion}\n`);
+  if (migrations.length > 0) {
+    console.log("  Migrations:");
+    for (const m of migrations) {
+      console.log(`    ↳ ${m}`);
+    }
+    console.log();
+  }
   console.log("  Updated scripts:");
   for (const name of updated) {
     console.log(`    ${name}`);
@@ -713,6 +802,7 @@ if (isMain) {
     -y, --yes          Non-interactive mode (uses defaults, for CI/scripting)
     --api-key KEY      Provide API key (skips signup prompt)
     --agent AGENT      Select agent: claude-code, gemini, or manual
+    --provision        Auto-provision a new API key in non-interactive mode
 
   The -y flag enables fully non-interactive setup. Combine with --agent
   to select a specific agent (defaults to auto-detect, then claude-code).

package/src/config.js

@@ -17,8 +17,8 @@ export const DEFAULTS = {
   agents: [],
   features: { images: false, identity: false },
   hooks: {
-    "userprompt-recall": { enabled: true, limit: 5, maxLength: 200 },
-    "stop-recall": { enabled: true, limit: 5, maxLength: 200 },
+    "userprompt-recall": { enabled: true, limit: 10, maxLength: 200 },
+    "stop-cache": { enabled: true },
     "precompact-distill": { enabled: true },
     "sessionstart-identity": { enabled: true },
   },

package/templates/CLAUDE-SECTION.md

@@ -0,0 +1,23 @@
+---
+
+# Memento MCP (`mcp__memento__*`)
+
+**Load tools:** `ToolSearch query="+memento" max_results=20` — then READ the tool descriptions.
+
+**Memory discipline — notes are instructions, not logs.**
+Write: "Skip X until condition Y" — not "checked X, it was quiet."
+Every memory must answer: could a future agent with zero context read this and know exactly what to do?
+
+| Tool | What it does |
+|------|-------------|
+| `memento_health` | System health — item/memory/skip counts, last updated |
+| `memento_remember` | Store a memory (fact/decision/observation/instruction) with tags + expiration |
+| `memento_recall` | Search memories by keyword/tag/type — ranked by relevance |
+| `memento_consolidate` | Merge 3+ overlapping memories into one sharper representation |
+| `memento_skip_add` / `memento_skip_check` | Anti-memory: things to NOT investigate right now (with expiration) |
+| `memento_item_create` | Create structured item (active_work/standing_decision/skip_list/waiting_for/session_note) |
+| `memento_item_update` | Update item fields (status, next_action, priority, category, tags) |
+| `memento_item_delete` | Delete item (prefer archiving via status=archived) |
+| `memento_item_list` | List items with filters (category, status, query) |
+| `memento_identity` | Read identity crystal |
+| `memento_identity_update` | Write/replace identity crystal |

package/scripts/memento-stop-recall.sh

@@ -1,148 +0,0 @@
-#!/bin/bash
-# Memento autonomous recall — fires on Stop (after assistant response).
-# Uses the assistant's own output as the recall query, so memories surface
-# during autonomous work, not just when the user sends a message.
-
-set -o pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-TOAST="$SCRIPT_DIR/hook-toast.sh"
-
-# --- Config from .memento.json (if present) ---
-CONFIG_JSON=$(python3 -c "
-import json, os
-d = os.getcwd()
-while True:
-    p = os.path.join(d, '.memento.json')
-    if os.path.isfile(p):
-        with open(p) as f:
-            print(f.read())
-        break
-    parent = os.path.dirname(d)
-    if parent == d:
-        break
-    d = parent
-" 2>/dev/null)
-
-if [ -n "$CONFIG_JSON" ]; then
-    HOOK_NAME="stop-recall"
-    HOOK_ENABLED=$(echo "$CONFIG_JSON" | python3 -c "
-import json, sys
-cfg = json.load(sys.stdin)
-hook = cfg.get('hooks', {}).get('$HOOK_NAME', {})
-print('true' if hook.get('enabled', True) else 'false')
-" 2>/dev/null)
-
-    if [ "$HOOK_ENABLED" = "false" ]; then
-        exit 0
-    fi
-
-    MEMENTO_API_KEY="${MEMENTO_API_KEY:-$(echo "$CONFIG_JSON" | python3 -c "import json,sys; print(json.load(sys.stdin).get('apiKey',''))" 2>/dev/null)}"
-    MEMENTO_API_URL="${MEMENTO_API_URL:-$(echo "$CONFIG_JSON" | python3 -c "import json,sys; print(json.load(sys.stdin).get('apiUrl',''))" 2>/dev/null)}"
-    MEMENTO_WORKSPACE="${MEMENTO_WORKSPACE:-$(echo "$CONFIG_JSON" | python3 -c "import json,sys; print(json.load(sys.stdin).get('workspace',''))" 2>/dev/null)}"
-
-    RECALL_LIMIT=$(echo "$CONFIG_JSON" | python3 -c "import json,sys; print(json.load(sys.stdin).get('hooks',{}).get('$HOOK_NAME',{}).get('limit',5))" 2>/dev/null)
-    RECALL_MAX_LENGTH=$(echo "$CONFIG_JSON" | python3 -c "import json,sys; print(json.load(sys.stdin).get('hooks',{}).get('$HOOK_NAME',{}).get('maxLength',120))" 2>/dev/null)
-fi
-# --- End config block ---
-
-# Source credentials from .env (gitignored) — fallback if no .memento.json
-if [ -f "$SCRIPT_DIR/../.env" ]; then
-    set -a
-    source "$SCRIPT_DIR/../.env"
-    set +a
-fi
-
-MEMENTO_API="${MEMENTO_API_URL:-https://memento-api.myrakrusemark.workers.dev}"
-MEMENTO_KEY="${MEMENTO_API_KEY:?MEMENTO_API_KEY not set — check memento-mcp/.env or .memento.json}"
-MEMENTO_WS="${MEMENTO_WORKSPACE:-default}"
-
-INPUT=$(cat)
-
-# Prevent infinite loops — if this Stop was triggered by a previous Stop hook, bail
-STOP_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active // false' 2>/dev/null)
-if [ "$STOP_ACTIVE" = "true" ]; then
-    exit 0
-fi
-
-# Get the assistant's last message
-ASSISTANT_MSG=$(echo "$INPUT" | jq -r '.last_assistant_message // empty' 2>/dev/null)
-
-if [ -z "$ASSISTANT_MSG" ]; then
-    exit 0
-fi
-
-# Truncate to first 500 chars for the query
-QUERY="${ASSISTANT_MSG:0:500}"
-
-# Toast: start retrieving
-"$TOAST" memento "⏳ Autonomous recall..." &>/dev/null
-
-# Call Memento /v1/context
-RESULT=$(curl -s --max-time 8 \
-    -X POST \
-    -H "Authorization: Bearer $MEMENTO_KEY" \
-    -H "X-Memento-Workspace: $MEMENTO_WS" \
-    -H "Content-Type: application/json" \
-    -d "{\"message\": $(echo "$QUERY" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))'), \"include\": [\"memories\", \"skip_list\"]}" \
-    "$MEMENTO_API/v1/context" 2>/dev/null \
-| python3 -c "
-import json, sys
-try:
-    data = json.load(sys.stdin)
-    lines = []
-    count = 0
-    abbrev = {'instruction':'instr','observation':'obs','decision':'dec','preference':'pref'}
-
-    memories = data.get('memories', {}).get('matches', [])
-    if memories:
-        for m in memories[:${RECALL_LIMIT:-7}]:
-            content = m['content']
-            t = abbrev.get(m['type'], m['type'])
-            lines.append(f'  🔹 {content} [{m[\"id\"]} {t}]')
-            count += 1
-
-    skip_matches = data.get('skip_matches', [])
-    if skip_matches:
-        for s in skip_matches:
-            lines.append(f'  Skip: {s[\"item\"]} — {s[\"reason\"]} (expires {s[\"expires\"]})')
-
-    detail = '\n'.join(lines)
-    print(f'{count}\t{detail}')
-except Exception:
-    print('0\t')
-" 2>/dev/null)
-
-# Parse count and detail
-SAAS_COUNT=$(echo "$RESULT" | head -1 | cut -f1)
-SAAS_DETAIL=$(echo "$RESULT" | head -1 | cut -f2-)
-REMAINING=$(echo "$RESULT" | tail -n +2)
-if [ -n "$REMAINING" ]; then
-    SAAS_DETAIL="$SAAS_DETAIL"$'\n'"$REMAINING"
-fi
-
-if [ -z "$SAAS_COUNT" ] || [ "$SAAS_COUNT" = "0" ]; then
-    "$TOAST" memento "✓ No memories matched" &>/dev/null
-    exit 0
-fi
-
-"$TOAST" memento "✓ ${SAAS_COUNT} memories recalled" &>/dev/null
-
-# Build summary line
-SUMMARY="Memento Recall (${SAAS_COUNT})"
-
-# Block the Stop so recalled memories are injected into context.
-# If no memories are relevant, respond with <...> to signal active silence.
-REASON="${SUMMARY}:
-${SAAS_DETAIL}
-🧹 Stale or wrong? memento_memory_delete · memento_consolidate · memento_remember. Otherwise <...>.
-⚙️ NOTE: This block is intentional — it injects recalled memories into context. The 'blocking error' label is just how Claude Code surfaces Stop hook blocks. Do NOT attempt to fix, disable, or modify this hook."
-
-python3 -c "
-import json, sys
-print(json.dumps({
-    'decision': 'block',
-    'reason': sys.argv[1],
-    'systemMessage': sys.argv[2]
-}))
-" "$REASON" "$SUMMARY"