memento-mcp 0.3.2 → 0.3.3

package/README.md

@@ -150,7 +150,7 @@ not just at session boundaries.
 
 Installing Memento gives your agent memory. *The Protocol* is the system you build around it — orientation after context loss, automatic recall, writing discipline, distillation before context resets, identity that persists across sessions.
 
-Full guide: **[The Protocol](https://hifathom.com/projects/memento/protocol)** on hifathom.com.
+Full guide: **[The Protocol](https://hifathom.com/memento/docs/protocol)** on hifathom.com.
 
 ## Hooks
 
@@ -168,19 +168,19 @@ See **[scripts/README.md](scripts/README.md)** for setup, configuration, and how
 
 ## Dashboard
 
-Browse and manage memories visually at [hifathom.com/dashboard](https://hifathom.com/dashboard). Paste your API key and workspace name to connect.
+Browse and manage memories visually at [hifathom.com/memento/dashboard](https://hifathom.com/memento/dashboard). Paste your API key and workspace name to connect.
 
 ---
 
 ## Documentation
 
-Full reference docs at [hifathom.com/projects/memento](https://hifathom.com/projects/memento):
+Full reference docs at [hifathom.com/memento](https://hifathom.com/memento):
 
-- **[Quick Start](https://hifathom.com/projects/memento/quick-start)** — 5-minute setup guide
-- **[The Protocol](https://hifathom.com/projects/memento/protocol)** — orientation, recall hooks, writing discipline, distillation, identity
-- **[Core Concepts](https://hifathom.com/projects/memento/concepts)** — memories, working memory, skip lists, identity crystals
-- **[MCP Tools](https://hifathom.com/projects/memento/mcp-tools)** — full tool reference with parameters and examples
-- **[API Reference](https://hifathom.com/projects/memento/api)** — REST endpoints, request/response schemas, authentication
+- **[Quick Start](https://hifathom.com/memento/docs/quick-start)** — 5-minute setup guide
+- **[The Protocol](https://hifathom.com/memento/docs/protocol)** — orientation, recall hooks, writing discipline, distillation, identity
+- **[Core Concepts](https://hifathom.com/memento/docs/concepts)** — memories, working memory, skip lists, identity crystals
+- **[MCP Tools](https://hifathom.com/memento/docs/mcp-tools)** — full tool reference with parameters and examples
+- **[API Reference](https://hifathom.com/memento/docs/api)** — REST endpoints, request/response schemas, authentication
 - **[Self-Hosting](docs/self-hosting.md)** — deploy your own instance with Cloudflare Workers + Turso
 
 ---

package/docs/self-hosting.md

@@ -82,5 +82,5 @@ Workers AI and Vectorize are included in the Cloudflare Workers free tier.
 
 - You manage your own Turso databases and Cloudflare account
 - You handle upgrades by pulling from the repo and redeploying
-- No usage dashboard at hifathom.com (you'd use Cloudflare's dashboard)
+- No usage dashboard at hifathom.com/memento/dashboard (you'd use Cloudflare's dashboard)
 - Signup endpoint creates keys in your control plane database

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memento-mcp",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "mcpName": "io.github.myrakrusemark/memento-protocol",
   "description": "The Memento Protocol — persistent memory for AI agents",
   "type": "module",

package/scripts/memento-sessionstart-identity.sh

@@ -99,9 +99,33 @@ PID3=$!
 
 wait $PID1 $PID2 $PID3 2>/dev/null
 
-# Build output from the three responses
+# Version check (non-blocking, best-effort)
+# Read installed version from .memento/version (written by init/update)
+VERSION_FILE=""
+_vd="$(pwd)"
+while true; do
+    if [ -f "$_vd/.memento/version" ]; then
+        VERSION_FILE="$_vd/.memento/version"
+        break
+    fi
+    _vp="$(dirname "$_vd")"
+    [ "$_vp" = "$_vd" ] && break
+    _vd="$_vp"
+done
+
+export LOCAL_VERSION=""
+export LATEST_VERSION=""
+if [ -n "$VERSION_FILE" ]; then
+    LOCAL_VERSION=$(cat "$VERSION_FILE" 2>/dev/null | tr -d '[:space:]')
+    if [ -n "$LOCAL_VERSION" ]; then
+        LATEST_VERSION=$(curl -s --max-time 2 "https://registry.npmjs.org/memento-mcp/latest" 2>/dev/null \
+            | python3 -c "import json,sys; print(json.load(sys.stdin).get('version',''))" 2>/dev/null || echo "")
+    fi
+fi
+
+# Build output from the three responses + version check
 python3 -c "
-import json, sys
+import json, sys, os
 
 sections = []
 
@@ -155,6 +179,12 @@ if not sections:
 context = '\n\n'.join(sections)
 context += '\n\nREMINDER: If Memento MCP tools are not loaded, run: ToolSearch query=\"+memento\" max_results=20'
 
+# 4. Version check — append update notice if newer version available
+local_ver = os.environ.get('LOCAL_VERSION', '').strip()
+latest_ver = os.environ.get('LATEST_VERSION', '').strip()
+if local_ver and latest_ver and local_ver != latest_ver:
+    context += f'\n\nMemento update available: v{local_ver} → v{latest_ver}. Run: npx memento-mcp update'
+
 print(json.dumps({
     'hookSpecificOutput': {
         'hookEventName': 'SessionStart',
@@ -163,7 +193,11 @@ print(json.dumps({
 }))
 " "$IDENTITY_TMP" "$ACTIVE_TMP" "$SKIP_TMP" 2>/dev/null
 
-# Toast: done
-"$TOAST" memento "✓ Identity loaded" &>/dev/null
+# Toast: done (with update notice if applicable)
+if [ -n "$LATEST_VERSION" ] && [ -n "$LOCAL_VERSION" ] && [ "$LATEST_VERSION" != "$LOCAL_VERSION" ]; then
+    "$TOAST" memento "⬆ Memento v${LATEST_VERSION} available" &>/dev/null
+else
+    "$TOAST" memento "✓ Identity loaded" &>/dev/null
+fi
 
 exit 0

package/scripts/memento-stop-recall.sh

@@ -78,13 +78,13 @@ QUERY="${ASSISTANT_MSG:0:500}"
 # Toast: start retrieving
 "$TOAST" memento "⏳ Autonomous recall..." &>/dev/null
 
-# Call Memento /v1/context
-RESULT=$(curl -s --max-time 3 \
+# Call Memento /v1/context (with auto_extract for passive memory formation)
+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\"]}" \
+    -d "{\"message\": $(echo "$QUERY" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))'), \"include\": [\"memories\", \"skip_list\"], \"auto_extract\": true, \"extract_role\": \"assistant\", \"extract_content\": $(echo "$ASSISTANT_MSG" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')}" \
     "$MEMENTO_API/v1/context" 2>/dev/null \
 | python3 -c "
 import json, sys
@@ -111,35 +111,60 @@ try:
         for s in skip_matches:
             lines.append(f'  ⚠ SKIP: {s[\"item\"]} — {s[\"reason\"]} (expires: {s[\"expires\"]})')
 
+    # Auto-extracted memories
+    extracted = data.get('extracted', [])
+    if extracted:
+        lines.append('')
+        lines.append('MEMORIES STORED:')
+        for e in extracted:
+            etags = [t for t in e.get('tags', []) if t != 'source:auto-extract']
+            etag_str = f' [{\", \".join(etags)}]' if etags else ''
+            lines.append(f'  {e[\"id\"]} ({e.get(\"type\", \"observation\")}){etag_str} — {e[\"content\"]}')
+
+    # Output: recall_count \t extracted_count \t detail
+    extracted_count = len(extracted)
     detail = '\n'.join(lines)
-    print(f'{count}\t{detail}')
+    print(f'{count}\t{extracted_count}\t{detail}')
 except Exception:
-    print('0\t')
+    print('0\t0\t')
 " 2>/dev/null)
 
-# Parse
+# Parse count, extracted count, and detail
 SAAS_COUNT=$(echo "$RESULT" | head -1 | cut -f1)
-SAAS_DETAIL=$(echo "$RESULT" | head -1 | cut -f2-)
+EXTRACTED_COUNT=$(echo "$RESULT" | head -1 | cut -f2)
+SAAS_DETAIL=$(echo "$RESULT" | head -1 | cut -f3-)
 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
+    if [ -n "$EXTRACTED_COUNT" ] && [ "$EXTRACTED_COUNT" != "0" ]; then
+        "$TOAST" memento "✓ ${EXTRACTED_COUNT} memories stored" &>/dev/null
+    else
+        "$TOAST" memento "✓ No memories matched" &>/dev/null
+        exit 0
+    fi
+else
+    if [ -n "$EXTRACTED_COUNT" ] && [ "$EXTRACTED_COUNT" != "0" ]; then
+        "$TOAST" memento "✓ ${SAAS_COUNT} recalled, ${EXTRACTED_COUNT} stored" &>/dev/null
+    else
+        "$TOAST" memento "✓ ${SAAS_COUNT} memories recalled" &>/dev/null
+    fi
 fi
 
-# Toast: result
-"$TOAST" memento "✓ ${SAAS_COUNT} memories recalled" &>/dev/null
+# Build summary line
+SUMMARY="Autonomous Recall: ${SAAS_COUNT} memories"
+if [ -n "$EXTRACTED_COUNT" ] && [ "$EXTRACTED_COUNT" != "0" ]; then
+    SUMMARY="${SUMMARY}, ${EXTRACTED_COUNT} memories stored"
+fi
 
 # Block the Stop so Claude continues — the reason becomes Claude's next instruction.
-REASON="Autonomous Recall: ${SAAS_COUNT} memories surfaced from your last response.
+REASON="${SUMMARY} surfaced from your last response.
 ${SAAS_DETAIL}
 
 You have absorbed these memories into context. If any recalled memory is stale, wrong, or overlaps with others — update, delete, or consolidate it now. Otherwise continue naturally."
 
-SUMMARY="Autonomous Recall: ${SAAS_COUNT} memories"
 python3 -c "
 import json, sys
 print(json.dumps({

package/scripts/memento-userprompt-recall.sh

@@ -70,13 +70,13 @@ QUERY="${USER_MESSAGE:0:500}"
 # Toast: start retrieving
 "$TOAST" memento "⏳ Retrieving memories..." &>/dev/null
 
-# Call Memento SaaS /v1/context
-SAAS_OUTPUT=$(curl -s --max-time 3 \
+# Call Memento SaaS /v1/context (with auto_extract for passive memory formation)
+SAAS_OUTPUT=$(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\"]}" \
+    -d "{\"message\": $(echo "$QUERY" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))'), \"include\": [\"memories\", \"skip_list\"], \"auto_extract\": true, \"extract_role\": \"user\", \"extract_content\": $(echo "$USER_MESSAGE" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')}" \
     "$MEMENTO_API/v1/context" 2>/dev/null \
 | python3 -c "
 import json, sys
@@ -105,16 +105,28 @@ try:
         for s in skip_matches:
             lines.append(f'  ⚠ SKIP: {s[\"item\"]} — {s[\"reason\"]} (expires: {s[\"expires\"]})')
 
-    # Output count and detail as tab-separated on first line, rest follows
+    # Auto-extracted memories
+    extracted = data.get('extracted', [])
+    if extracted:
+        lines.append('')
+        lines.append('MEMORIES STORED:')
+        for e in extracted:
+            etags = [t for t in e.get('tags', []) if t != 'source:auto-extract']
+            etag_str = f' [{\", \".join(etags)}]' if etags else ''
+            lines.append(f'  {e[\"id\"]} ({e.get(\"type\", \"observation\")}){etag_str} — {e[\"content\"]}')
+
+    # Output: recall_count \t extracted_count \t detail
+    extracted_count = len(extracted)
     detail = '\n'.join(lines)
-    print(f'{count}\t{detail}')
+    print(f'{count}\t{extracted_count}\t{detail}')
 except Exception:
-    print('0\t')
+    print('0\t0\t')
 " 2>/dev/null)
 
-# Parse count and detail
+# Parse count, extracted count, and detail
 SAAS_COUNT=$(echo "$SAAS_OUTPUT" | head -1 | cut -f1)
-SAAS_DETAIL=$(echo "$SAAS_OUTPUT" | head -1 | cut -f2-)
+EXTRACTED_COUNT=$(echo "$SAAS_OUTPUT" | head -1 | cut -f2)
+SAAS_DETAIL=$(echo "$SAAS_OUTPUT" | head -1 | cut -f3-)
 # Append any remaining lines (skip warnings etc.)
 REMAINING=$(echo "$SAAS_OUTPUT" | tail -n +2)
 if [ -n "$REMAINING" ]; then
@@ -122,18 +134,30 @@ if [ -n "$REMAINING" ]; then
 fi
 
 if [ -z "$SAAS_COUNT" ] || [ "$SAAS_COUNT" = "0" ]; then
-    "$TOAST" memento "✓ No memories matched" &>/dev/null
-    exit 0
+    if [ -n "$EXTRACTED_COUNT" ] && [ "$EXTRACTED_COUNT" != "0" ]; then
+        "$TOAST" memento "✓ ${EXTRACTED_COUNT} memories stored" &>/dev/null
+    else
+        "$TOAST" memento "✓ No memories matched" &>/dev/null
+        exit 0
+    fi
+else
+    if [ -n "$EXTRACTED_COUNT" ] && [ "$EXTRACTED_COUNT" != "0" ]; then
+        "$TOAST" memento "✓ ${SAAS_COUNT} recalled, ${EXTRACTED_COUNT} stored" &>/dev/null
+    else
+        "$TOAST" memento "✓ ${SAAS_COUNT} memories recalled" &>/dev/null
+    fi
 fi
 
-# Toast: result
-"$TOAST" memento "✓ ${SAAS_COUNT} memories recalled" &>/dev/null
+# Build summary line
+SUMMARY="Memento Recall: ${SAAS_COUNT} memories"
+if [ -n "$EXTRACTED_COUNT" ] && [ "$EXTRACTED_COUNT" != "0" ]; then
+    SUMMARY="${SUMMARY}, ${EXTRACTED_COUNT} memories stored"
+fi
 
-DETAIL_TEXT="Memento Recall: ${SAAS_COUNT} memories"
+DETAIL_TEXT="$SUMMARY"
 DETAIL_TEXT="$DETAIL_TEXT"$'\n'"$SAAS_DETAIL"
 DETAIL_TEXT="$DETAIL_TEXT"$'\n'$'\n'"REMINDER: If Memento MCP tools are not loaded, run: ToolSearch query=\"+memento\" max_results=20"
 
-SUMMARY="Memento Recall: ${SAAS_COUNT} memories"
 python3 -c "
 import json, sys
 summary = sys.argv[1]

package/src/cli.js

@@ -9,6 +9,7 @@ import readline from "node:readline";
 import fs from "node:fs";
 import path from "node:path";
 import https from "node:https";
+import { execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { DEFAULTS } from "./config.js";
 
@@ -92,6 +93,91 @@ function httpsPost(url, body) {
   });
 }
 
+// ---------------------------------------------------------------------------
+// Instructions blob — used by headless integration and fallback print
+// ---------------------------------------------------------------------------
+
+const INSTRUCTIONS_BLOB = `## Memento Protocol
+
+Working memory is managed by Memento. MCP tools available:
+\`memento_store\`, \`memento_recall\`, \`memento_item_list\`,
+\`memento_skip_add\`, \`memento_skip_check\`.
+
+**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?
+
+Use \`memento_store\` when you learn something worth keeping.
+Use \`memento_skip_add\` for things to explicitly not re-investigate.
+Use \`memento_recall\` to search memories by keyword or tag.
+Hooks run automatically — recall before responses, distillation
+before compaction. Trust the hooks. Focus on writing good memories.`;
+
+// ---------------------------------------------------------------------------
+// Headless agent integration
+// ---------------------------------------------------------------------------
+
+const HEADLESS_CMDS = {
+  "claude-code": (prompt) => ["claude", "-p", prompt],
+  "codex":       (prompt) => ["codex", "exec", prompt],
+  "gemini":      (prompt) => ["gemini", prompt],
+  "opencode":    (prompt) => ["opencode", "run", prompt],
+};
+
+function buildIntegrationPrompt(blob) {
+  return [
+    "The following instructions were generated by memento-mcp init for this project.",
+    "Add them to the file where you store persistent behavioral instructions",
+    "(e.g. CLAUDE.md for Claude Code). If the file exists, read it first and",
+    "integrate the new section without removing existing content. If a section",
+    "with the same heading already exists, replace it. If no instructions file",
+    "exists yet, create one.",
+    "",
+    "--- INSTRUCTIONS ---",
+    blob,
+    "--- END ---",
+  ].join("\n");
+}
+
+function runAgentHeadless(agentKey, prompt) {
+  const cmdBuilder = HEADLESS_CMDS[agentKey];
+  if (!cmdBuilder) return null;
+  const [cmd, ...args] = cmdBuilder(prompt);
+  try {
+    const result = execFileSync(cmd, args, {
+      cwd: process.cwd(),
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "inherit"],
+      timeout: 60000,
+    });
+    return result;
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// CLI flag parsing
+// ---------------------------------------------------------------------------
+
+function parseFlags(argv) {
+  const flags = { nonInteractive: false, apiKey: null };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "-y" || argv[i] === "--yes") {
+      flags.nonInteractive = true;
+    } else if (argv[i] === "--api-key" && argv[i + 1]) {
+      flags.apiKey = argv[i + 1];
+      i++;
+    }
+  }
+  // Also check environment variable
+  if (!flags.apiKey && process.env.MEMENTO_API_KEY) {
+    flags.apiKey = process.env.MEMENTO_API_KEY;
+  }
+  return flags;
+}
+
 // ---------------------------------------------------------------------------
 // File writers
 // ---------------------------------------------------------------------------
@@ -232,14 +318,14 @@ export { AGENTS, writeMcpJson, writeCodexToml, writeGeminiJson, writeOpencodeJso
 // CLI
 // ---------------------------------------------------------------------------
 
-async function runInit() {
+async function runInit(flags = {}) {
+  const { nonInteractive = false, apiKey: flagApiKey = null } = flags;
   const cwd = process.cwd();
   const projectName = path.basename(cwd);
 
-  const rl = readline.createInterface({
-    input: process.stdin,
-    output: process.stdout,
-  });
+  const rl = nonInteractive
+    ? null
+    : readline.createInterface({ input: process.stdin, output: process.stdout });
 
   console.log(`
             ▗
@@ -251,12 +337,29 @@ async function runInit() {
 `);
 
   // 1. Workspace name
-  const workspace = await ask(rl, "Workspace name", projectName);
+  const workspace = nonInteractive
+    ? projectName
+    : await ask(rl, "Workspace name", projectName);
 
   // 2. API key
-  let apiKey = await ask(rl, "API key (leave blank to sign up)");
+  let apiKey = flagApiKey || "";
+  if (!nonInteractive) {
+    apiKey = await ask(rl, "API key (leave blank to sign up)");
+  }
   if (!apiKey) {
-    const email = await ask(rl, "Email for account recovery (optional)");
+    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 };
@@ -267,73 +370,84 @@ async function runInit() {
         console.log(`  API key: ${apiKey}`);
       } else if (resp.error) {
         console.error(`  Signup failed: ${resp.error}`);
-        rl.close();
+        rl?.close();
         process.exit(1);
       } else {
         console.error("  Unexpected response:", JSON.stringify(resp));
-        rl.close();
+        rl?.close();
         process.exit(1);
       }
     } catch (err) {
       console.error(`  Signup failed: ${err.message}`);
-      rl.close();
+      rl?.close();
       process.exit(1);
     }
   }
 
   // 3. Features
-  console.log("\nOptional features:");
-  const enableImages = await askYesNo(
-    rl,
-    "  Enable image attachments? (attach images to memories via memento_store)",
-    false,
-  );
-  const enableIdentity = await askYesNo(
-    rl,
-    "  Enable identity crystal? (persist a first-person identity snapshot across sessions)",
-    false,
-  );
+  let enableImages = false;
+  let enableIdentity = false;
+  if (!nonInteractive) {
+    console.log("\nOptional features:");
+    enableImages = await askYesNo(
+      rl,
+      "  Enable image attachments? (attach images to memories via memento_store)",
+      false,
+    );
+    enableIdentity = await askYesNo(
+      rl,
+      "  Enable identity crystal? (persist a first-person identity snapshot across sessions)",
+      false,
+    );
+  }
 
   // 4. Agent detection + selection
   const agentKeys = Object.keys(AGENTS);
   const detected = agentKeys.filter((key) => AGENTS[key].detect(cwd));
 
-  console.log("\nDetected agents:");
-  const markers = {
-    "claude-code": ".claude/",
-    codex: ".codex/",
-    gemini: ".gemini/",
-    opencode: "opencode.json",
-  };
-  for (const key of agentKeys) {
-    const agent = AGENTS[key];
-    const isDetected = detected.includes(key);
-    const mark = isDetected ? "✓" : " ";
-    const hint = isDetected ? ` (${markers[key]} found)` : "";
-    console.log(`    ${mark} ${agent.name}${hint}`);
-  }
+  let selectedAgents;
+  if (nonInteractive) {
+    // Auto-detect: use first detected agent, or default to claude-code
+    selectedAgents = detected.length > 0 ? [detected[0]] : ["claude-code"];
+    console.log(`  Agent: ${AGENTS[selectedAgents[0]].name} (auto-detected)`);
+  } else {
+    console.log("\nDetected agents:");
+    const markers = {
+      "claude-code": ".claude/",
+      codex: ".codex/",
+      gemini: ".gemini/",
+      opencode: "opencode.json",
+    };
+    for (const key of agentKeys) {
+      const agent = AGENTS[key];
+      const isDetected = detected.includes(key);
+      const mark = isDetected ? "✓" : " ";
+      const hint = isDetected ? ` (${markers[key]} found)` : "";
+      console.log(`    ${mark} ${agent.name}${hint}`);
+    }
 
-  console.log("\n  Configure for which agents?");
-  agentKeys.forEach((key, i) => {
-    const mark = detected.includes(key) ? " ✓" : "";
-    console.log(`    ${i + 1}. ${AGENTS[key].name}${mark}`);
-  });
+    console.log("\n  Configure for which agents?");
+    agentKeys.forEach((key, i) => {
+      const mark = detected.includes(key) ? " ✓" : "";
+      console.log(`    ${i + 1}. ${AGENTS[key].name}${mark}`);
+    });
 
-  const defaultSelection =
-    detected.length > 0
-      ? detected.map((key) => agentKeys.indexOf(key) + 1).join(",")
-      : "1";
-  const selectionStr = await ask(rl, "\n  Enter numbers, comma-separated", defaultSelection);
-
-  const selectedIndices = selectionStr
-    .split(",")
-    .map((s) => parseInt(s.trim(), 10))
-    .filter((n) => n >= 1 && n <= agentKeys.length);
-  const selectedAgents = [...new Set(selectedIndices.map((i) => agentKeys[i - 1]))];
-
-  if (selectedAgents.length === 0) {
-    console.log("  No agents selected. Defaulting to Claude Code.");
-    selectedAgents.push("claude-code");
+    const defaultSelection =
+      detected.length > 0
+        ? detected.map((key) => agentKeys.indexOf(key) + 1).join(",")
+        : "1";
+    const selectionStr = await ask(rl, "\n  Enter numbers, comma-separated", defaultSelection);
+
+    const selectedIndices = selectionStr
+      .split(",")
+      .map((s) => parseInt(s.trim(), 10))
+      .filter((n) => n >= 1 && n <= agentKeys.length);
+    selectedAgents = [...new Set(selectedIndices.map((i) => agentKeys[i - 1]))];
+
+    if (selectedAgents.length === 0) {
+      console.log("  No agents selected. Defaulting to Claude Code.");
+      selectedAgents.push("claude-code");
+    }
   }
 
   const hasClaude = selectedAgents.includes("claude-code");
@@ -345,28 +459,36 @@ async function runInit() {
   let enableSessionStart = false;
 
   if (hasClaude) {
-    console.log("\nClaude Code hooks (automate recall + distillation):");
-    enableUserPrompt = await askYesNo(
-      rl,
-      "  UserPromptSubmit — recall on every message?",
-      true,
-    );
-    enableStop = await askYesNo(rl, "  Stop — autonomous recall after responses?", true);
-    enablePreCompact = await askYesNo(
-      rl,
-      "  PreCompact — distill memories before context compression?",
-      true,
-    );
-    if (enableIdentity) {
-      enableSessionStart = await askYesNo(
+    if (nonInteractive) {
+      // All hooks on by default in non-interactive mode
+      enableUserPrompt = true;
+      enableStop = true;
+      enablePreCompact = true;
+      enableSessionStart = false; // identity not enabled in -y mode
+    } else {
+      console.log("\nClaude Code hooks (automate recall + distillation):");
+      enableUserPrompt = await askYesNo(
         rl,
-        "  SessionStart — inject identity + active items at startup?",
+        "  UserPromptSubmit — recall on every message?",
         true,
       );
+      enableStop = await askYesNo(rl, "  Stop — autonomous recall after responses?", true);
+      enablePreCompact = await askYesNo(
+        rl,
+        "  PreCompact — distill memories before context compression?",
+        true,
+      );
+      if (enableIdentity) {
+        enableSessionStart = await askYesNo(
+          rl,
+          "  SessionStart — inject identity + active items at startup?",
+          true,
+        );
+      }
     }
   }
 
-  rl.close();
+  rl?.close();
 
   // Build config
   const config = {
@@ -418,6 +540,12 @@ async function runInit() {
     }
     created.push(".memento/scripts/");
 
+    // 7b. Write .memento/version for update checks
+    const pkgJsonPath = path.resolve(__dirname, "..", "package.json");
+    const pkgVersion = JSON.parse(fs.readFileSync(pkgJsonPath, "utf8")).version;
+    const versionPath = path.join(cwd, ".memento", "version");
+    fs.writeFileSync(versionPath, pkgVersion + "\n");
+
     // 8. Write .claude/settings.local.json (hooks)
     const hooks = {};
     if (enableUserPrompt) {
@@ -522,7 +650,140 @@ async function runInit() {
   }
   console.log("  Your agent will wake up remembering.\n");
 
-  // 12. CLAUDE.md / AGENTS.md boilerplate
+  // 12. Auto-integrate agent instructions
+  const primaryAgent = selectedAgents[0];
+  const prompt = buildIntegrationPrompt(INSTRUCTIONS_BLOB);
+  const cmdParts = HEADLESS_CMDS[primaryAgent]?.(prompt);
+
+  if (nonInteractive) {
+    // Auto-run headless integration, no prompt
+    if (cmdParts) {
+      console.log(`  Integrating instructions via ${AGENTS[primaryAgent].name}...`);
+      const result = runAgentHeadless(primaryAgent, prompt);
+      if (result !== null) {
+        console.log(result);
+      } else {
+        // Fallback: print the blob
+        console.log("  Agent integration failed — paste these instructions manually:\n");
+        printInstructionsFallback(selectedAgents);
+      }
+    } else {
+      printInstructionsFallback(selectedAgents);
+    }
+  } else {
+    // Interactive: ask with explicit command shown
+    if (cmdParts) {
+      const [cmd, ...args] = cmdParts;
+      const displayCmd = `${cmd} ${args[0]}${args.length > 1 ? " ..." : ""}`;
+      const rl2 = readline.createInterface({ input: process.stdin, output: process.stdout });
+      console.log("─".repeat(60));
+      const integrate = await askYesNo(
+        rl2,
+        `\n  Auto-integrate instructions into your project?\n  This will run: ${displayCmd}\n\n  Proceed?`,
+        true,
+      );
+      rl2.close();
+
+      if (integrate) {
+        console.log(`\n  Running ${AGENTS[primaryAgent].name}...`);
+        const result = runAgentHeadless(primaryAgent, prompt);
+        if (result !== null) {
+          console.log(result);
+        } else {
+          console.log("  Agent integration failed — paste these instructions manually:\n");
+          printInstructionsFallback(selectedAgents);
+        }
+      } else {
+        printInstructionsFallback(selectedAgents);
+      }
+    } else {
+      printInstructionsFallback(selectedAgents);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Update command — copy fresh hook scripts to an existing installation
+// ---------------------------------------------------------------------------
+
+async function runUpdate() {
+  const cwd = process.cwd();
+  const configPath = path.join(cwd, ".memento.json");
+
+  if (!fs.existsSync(configPath)) {
+    console.error(
+      "  Error: .memento.json not found in current directory.\n" +
+        "  Run `npx memento-mcp init` first to set up Memento.\n"
+    );
+    process.exit(1);
+  }
+
+  const pkgJsonPath = path.resolve(__dirname, "..", "package.json");
+  const pkgVersion = JSON.parse(fs.readFileSync(pkgJsonPath, "utf8")).version;
+
+  const pkgScriptsDir = path.resolve(__dirname, "..", "scripts");
+  const localScriptsDir = path.join(cwd, ".memento", "scripts");
+
+  if (!fs.existsSync(localScriptsDir)) {
+    fs.mkdirSync(localScriptsDir, { recursive: true });
+  }
+
+  // Copy all .sh files from package scripts/ to local .memento/scripts/
+  const scriptFiles = fs
+    .readdirSync(pkgScriptsDir)
+    .filter((f) => f.endsWith(".sh"));
+
+  const updated = [];
+  for (const name of scriptFiles) {
+    const src = path.join(pkgScriptsDir, name);
+    const dest = path.join(localScriptsDir, name);
+    fs.copyFileSync(src, dest);
+    fs.chmodSync(dest, 0o755);
+    updated.push(name);
+  }
+
+  // Write .memento/version
+  const versionPath = path.join(cwd, ".memento", "version");
+  fs.writeFileSync(versionPath, pkgVersion + "\n");
+
+  // Ensure SessionStart hook is registered for Claude Code workspaces
+  const config = readJsonFile(configPath) || {};
+  const agents = config.agents || [];
+  const hasClaude = agents.includes("claude-code");
+  let hooksUpdated = false;
+  if (hasClaude) {
+    const settingsPath = path.join(cwd, ".claude", "settings.local.json");
+    const claudeSettings = readJsonFile(settingsPath) || {};
+    const sessionStartCmd = path.join(localScriptsDir, "memento-sessionstart-identity.sh");
+    const existingHooks = claudeSettings.hooks?.["SessionStart"] || [];
+    const hasSessionStart = existingHooks.some((entry) =>
+      entry.hooks?.some((h) => h.command === sessionStartCmd)
+    );
+    if (!hasSessionStart) {
+      claudeSettings.hooks = claudeSettings.hooks || {};
+      claudeSettings.hooks["SessionStart"] = [
+        ...existingHooks,
+        { hooks: [{ type: "command", command: sessionStartCmd, timeout: 10000 }] },
+      ];
+      writeJsonFile(settingsPath, claudeSettings);
+      hooksUpdated = true;
+    }
+  }
+
+  console.log(`\n  ✓ Memento hooks updated to v${pkgVersion}\n`);
+  console.log("  Updated scripts:");
+  for (const name of updated) {
+    console.log(`    ${name}`);
+  }
+  if (hooksUpdated) {
+    console.log("\n  Registered hooks:");
+    console.log("    SessionStart → memento-sessionstart-identity.sh (identity + version check)");
+  }
+  console.log(`\n  Version written to .memento/version`);
+  console.log("  Restart your agent session to pick up changes.\n");
+}
+
+function printInstructionsFallback(selectedAgents) {
   const hasNonClaude = selectedAgents.some((k) => k !== "claude-code");
   const docTarget = hasNonClaude
     ? "your CLAUDE.md, AGENTS.md, or equivalent"
@@ -536,22 +797,7 @@ async function runInit() {
 
   ── paste below this line ──────────────────────────────
 
-## Memento Protocol
-
-Working memory is managed by Memento. MCP tools available:
-\`memento_store\`, \`memento_recall\`, \`memento_item_list\`,
-\`memento_skip_add\`, \`memento_skip_check\`.
-
-**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?
-
-Use \`memento_store\` when you learn something worth keeping.
-Use \`memento_skip_add\` for things to explicitly not re-investigate.
-Use \`memento_recall\` to search memories by keyword or tag.
-Hooks run automatically — recall before responses, distillation
-before compaction. Trust the hooks. Focus on writing good memories.
+${INSTRUCTIONS_BLOB}
 
   ── paste above this line ──────────────────────────────
 `);
@@ -569,7 +815,13 @@ if (isMain) {
   const args = process.argv.slice(2);
 
   if (args[0] === "init") {
-    runInit().catch((err) => {
+    const flags = parseFlags(args.slice(1));
+    runInit(flags).catch((err) => {
+      console.error(err);
+      process.exit(1);
+    });
+  } else if (args[0] === "update") {
+    runUpdate().catch((err) => {
       console.error(err);
       process.exit(1);
     });
@@ -584,11 +836,15 @@ if (isMain) {
   Memento Protocol CLI
 
   Usage:
-    npx memento-mcp init    Set up Memento in the current project
-    npx memento-mcp         Start the MCP server (used by .mcp.json)
+    npx memento-mcp init                Set up Memento in the current project
+    npx memento-mcp init -y             Non-interactive setup (uses defaults)
+    npx memento-mcp init --api-key KEY  Provide API key (skips signup)
+    npx memento-mcp update              Update hook scripts to latest version
+    npx memento-mcp                     Start the MCP server (used by .mcp.json)
+
+  The -y flag enables fully non-interactive setup for CI/scripting.
+  Combine with --api-key to skip auto-signup.
 
-  This creates .memento.json, configures your agent's MCP client,
-  and sets up hooks (Claude Code) — all in one command.
   Supports Claude Code, Codex, Gemini CLI, and OpenCode.
 `);
     process.exit(1);