memento-mcp 0.2.5 → 0.3.1

package/README.md

@@ -10,7 +10,7 @@ AI agents have anterograde amnesia — every session starts blank. The Memento P
 npx memento-mcp init
 ```
 
-This creates `.memento.json`, configures Claude Code hooks, and sets up the MCP server — all in one command. Restart Claude Code to load the new config.
+This creates `.memento.json`, detects your agent (Claude Code, Codex, Gemini CLI, OpenCode), writes the correct MCP config, and sets up hooks (Claude Code only) — all in one command.
 
 ---
 
@@ -43,29 +43,55 @@ Save the `api_key` from the response — you'll need it next.
 
 ### Step 2: Configure your MCP client
 
-**Claude Code (project-level):** Create `.mcp.json` in your project root.
+**Claude Code** — `.mcp.json` in your project root (or `~/.claude.json` globally):
 
-**Claude Code (global):** Add to `~/.claude.json` under `"mcpServers"`.
+```json
+{
+  "mcpServers": {
+    "memento": {
+      "command": "npx",
+      "args": ["-y", "memento-mcp"]
+    }
+  }
+}
+```
+
+**OpenAI Codex** — `.codex/config.toml`:
+
+```toml
+[mcp_servers.memento]
+command = "npx"
+args = ["-y", "memento-mcp"]
+```
 
-**Claude Desktop:** Add to your `claude_desktop_config.json`.
+**Gemini CLI** — `.gemini/settings.json`:
 
 ```json
 {
   "mcpServers": {
     "memento": {
-      "command": "node",
-      "args": ["/home/you/memento-protocol/src/index.js"],
-      "env": {
-        "MEMENTO_API_KEY": "mp_live_your_key_here",
-        "MEMENTO_API_URL": "https://memento-api.myrakrusemark.workers.dev",
-        "MEMENTO_WORKSPACE": "my-project"
-      }
+      "command": "npx",
+      "args": ["-y", "memento-mcp"]
+    }
+  }
+}
+```
+
+**OpenCode** — `opencode.json`:
+
+```json
+{
+  "mcp": {
+    "memento": {
+      "type": "local",
+      "command": ["npx", "-y", "memento-mcp"],
+      "enabled": true
     }
   }
 }
 ```
 
-> **Tip:** Replace the path with the actual absolute path to `src/index.js` in your clone. Run `echo "$(pwd)/src/index.js"` from inside the repo to get it.
+Set credentials via `.memento.json` (created by `npx memento-mcp init`) or environment variables `MEMENTO_API_KEY`, `MEMENTO_API_URL`, `MEMENTO_WORKSPACE`.
 
 ### Step 3: Restart your client
 

package/package.json

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

package/scripts/hook-toast.sh

@@ -0,0 +1,140 @@
+#!/bin/bash
+# hook-toast.sh — tmux popup notifications for agent hooks.
+#
+# Usage:
+#   hook-toast.sh <system> <message>          # one-shot toast (auto-closes after 2s)
+#   hook-toast.sh <system> --status <id>      # start a multi-stage toast (poll mode)
+#   hook-toast.sh --update <id> <message>     # update a running toast
+#   hook-toast.sh --close <id>                # close a running toast (after delay)
+#
+# Built-in systems: fathom, memento
+#   fathom  → 📝 purple (colour141)
+#   memento → 🧠 teal (colour37)
+#
+# Any other system name works too — gets a default icon and grey border.
+#
+# Multi-stage example (PreCompact):
+#   hook-toast.sh memento --status precompact
+#   hook-toast.sh --update precompact "⏳ Getting context..."
+#   hook-toast.sh --update precompact "⏳ Extracting memories..."
+#   hook-toast.sh --update precompact "✓ Stored 7 memories"
+#   hook-toast.sh --close precompact
+
+TOAST_DIR="/tmp/hook-toast"
+mkdir -p "$TOAST_DIR"
+
+# Bail silently if not in tmux
+if ! tmux info &>/dev/null; then
+    exit 0
+fi
+
+get_style() {
+    case "$1" in
+        memento) echo "colour37" ;;
+        fathom)  echo "colour141" ;;
+        *)       echo "colour245" ;;
+    esac
+}
+
+get_icon() {
+    case "$1" in
+        memento) echo "🧠" ;;
+        fathom)  echo "📝" ;;
+        *)       echo "📌" ;;
+    esac
+}
+
+get_title() {
+    case "$1" in
+        memento) echo "Memento" ;;
+        fathom)  echo "Fathom" ;;
+        *)       echo "$1" ;;
+    esac
+}
+
+# One-shot toast
+toast_oneshot() {
+    local system="$1"
+    local message="$2"
+    local colour icon title
+    colour=$(get_style "$system")
+    icon=$(get_icon "$system")
+    title=$(get_title "$system")
+
+    (tmux display-popup -x R -y 0 -w 42 -h 3 \
+        -s "fg=$colour" -T " $icon $title " -E \
+        "echo '  $message'; sleep 2" &>/dev/null &)
+}
+
+# Start a multi-stage toast (polling status file)
+toast_start() {
+    local system="$1"
+    local id="$2"
+    local status_file="$TOAST_DIR/$id"
+    local colour icon title
+    colour=$(get_style "$system")
+    icon=$(get_icon "$system")
+    title=$(get_title "$system")
+
+    echo "⏳ Starting..." > "$status_file"
+
+    (tmux display-popup -x R -y 0 -w 42 -h 3 \
+        -s "fg=$colour" -T " $icon $title " -E "
+        LAST=''
+        while [ -f '$status_file' ]; do
+            MSG=\$(cat '$status_file' 2>/dev/null)
+            if [ \"\$MSG\" != \"\$LAST\" ]; then
+                clear
+                echo \"  \$MSG\"
+                LAST=\"\$MSG\"
+            fi
+            case \"\$MSG\" in ✓*|✗*) sleep 2; break ;; esac
+            sleep 0.2
+        done
+    " &>/dev/null &)
+}
+
+# Update a running toast
+toast_update() {
+    local id="$1"
+    local message="$2"
+    echo "$message" > "$TOAST_DIR/$id"
+}
+
+# Close a running toast (remove status file — popup exits on next poll)
+toast_close() {
+    local id="$1"
+    # Give the popup time to display the final message
+    sleep 2
+    rm -f "$TOAST_DIR/$id"
+}
+
+# --- Argument parsing ---
+case "${1:-}" in
+    --update)
+        toast_update "$2" "$3"
+        ;;
+    --close)
+        toast_close "$2"
+        ;;
+    --*)
+        echo "Unknown option: $1" >&2
+        exit 1
+        ;;
+    "")
+        echo "Usage: hook-toast.sh <system> <message>" >&2
+        echo "       hook-toast.sh <system> --status <id>" >&2
+        echo "       hook-toast.sh --update <id> <message>" >&2
+        echo "       hook-toast.sh --close <id>" >&2
+        exit 1
+        ;;
+    *)
+        SYSTEM="$1"
+        shift
+        if [ "${1:-}" = "--status" ]; then
+            toast_start "$SYSTEM" "$2"
+        else
+            toast_oneshot "$SYSTEM" "$*"
+        fi
+        ;;
+esac

package/scripts/memento-precompact-distill.sh

@@ -8,17 +8,27 @@
 set -o pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+TOAST="$SCRIPT_DIR/hook-toast.sh"
+
+# Toast: start multi-stage
+"$TOAST" memento --status distill &>/dev/null
+"$TOAST" --update distill "⏳ Getting context..." &>/dev/null
+
 INPUT=$(cat)
 
 TRANSCRIPT_PATH=$(echo "$INPUT" | jq -r '.transcript_path' | sed "s|~|$HOME|")
 
 # Only distill if transcript exists and has content
 if [ ! -f "$TRANSCRIPT_PATH" ]; then
+    "$TOAST" --update distill "✗ No transcript found" &>/dev/null
+    ("$TOAST" --close distill &>/dev/null &)
     exit 0
 fi
 
 LINE_COUNT=$(wc -l < "$TRANSCRIPT_PATH")
 if [ "$LINE_COUNT" -lt 2 ]; then
+    "$TOAST" --update distill "✓ Skipped (tiny conversation)" &>/dev/null
+    ("$TOAST" --close distill &>/dev/null &)
     exit 0
 fi
 
@@ -79,9 +89,14 @@ else
 fi
 
 if [ ${#TRANSCRIPT_TEXT} -lt 200 ]; then
+    "$TOAST" --update distill "✓ Skipped (too short)" &>/dev/null
+    ("$TOAST" --close distill &>/dev/null &)
     exit 0  # Too short to distill anything useful
 fi
 
+# Toast: extracting
+"$TOAST" --update distill "⏳ Extracting memories..." &>/dev/null
+
 DISTILL_MODEL="${DISTILL_MODEL:-llama}"
 
 # claude-code path: run extraction locally via claude -p, push to /v1/memories/ingest
@@ -166,9 +181,15 @@ print(json.dumps({'memories': parsed, 'source': 'distill:claude-code'}))
             -d "$INGEST_PAYLOAD" \
             "$MEMENTO_API/v1/memories/ingest" > /dev/null 2>&1
 
+        "$TOAST" --update distill "✓ Stored ${MEMORY_COUNT} memories" &>/dev/null
+        ("$TOAST" --close distill &>/dev/null &)
+
         python3 -c "import json,sys; print(json.dumps({'systemMessage': sys.argv[1]}))" \
             "Memento Distill (claude-code): ${MEMORY_COUNT} memories — ${TYPE_BREAKDOWN}"
     else
+        "$TOAST" --update distill "✓ No memories extracted" &>/dev/null
+        ("$TOAST" --close distill &>/dev/null &)
+
         python3 -c "import json,sys; print(json.dumps({'systemMessage': sys.argv[1]}))" \
             "Memento Distill (claude-code): no memories extracted"
     fi
@@ -206,9 +227,15 @@ MEMORY_COUNT=$(echo "$DISTILL_SUMMARY" | cut -d'|' -f1)
 TYPE_BREAKDOWN=$(echo "$DISTILL_SUMMARY" | cut -d'|' -f2)
 
 if [ "${MEMORY_COUNT:-0}" -gt 0 ] 2>/dev/null; then
+    "$TOAST" --update distill "✓ Stored ${MEMORY_COUNT} memories" &>/dev/null
+    ("$TOAST" --close distill &>/dev/null &)
+
     python3 -c "import json,sys; print(json.dumps({'systemMessage': sys.argv[1]}))" \
         "Memento Distill: ${MEMORY_COUNT} memories — ${TYPE_BREAKDOWN}"
 else
+    "$TOAST" --update distill "✓ No memories extracted" &>/dev/null
+    ("$TOAST" --close distill &>/dev/null &)
+
     python3 -c "import json,sys; print(json.dumps({'systemMessage': sys.argv[1]}))" \
         "Memento Distill: no memories extracted"
 fi

package/scripts/memento-sessionstart-identity.sh

@@ -10,6 +10,7 @@
 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 "
@@ -80,6 +81,9 @@ ACTIVE_TMP=$(mktemp)
 SKIP_TMP=$(mktemp)
 trap 'rm -f "$IDENTITY_TMP" "$ACTIVE_TMP" "$SKIP_TMP"' EXIT
 
+# Toast: loading identity
+"$TOAST" memento "⏳ Loading identity..." &>/dev/null
+
 # Fetch all three endpoints in parallel
 curl -s --max-time 3 -H "$AUTH_HEADER" -H "$WS_HEADER" \
     "$MEMENTO_API/v1/identity" > "$IDENTITY_TMP" 2>/dev/null &
@@ -159,4 +163,7 @@ print(json.dumps({
 }))
 " "$IDENTITY_TMP" "$ACTIVE_TMP" "$SKIP_TMP" 2>/dev/null
 
+# Toast: done
+"$TOAST" memento "✓ Identity loaded" &>/dev/null
+
 exit 0

package/scripts/memento-stop-recall.sh

@@ -6,6 +6,7 @@
 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 "
@@ -74,6 +75,9 @@ 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 3 \
     -X POST \
@@ -122,9 +126,13 @@ if [ -n "$REMAINING" ]; then
 fi
 
 if [ -z "$SAAS_COUNT" ] || [ "$SAAS_COUNT" = "0" ]; then
+    "$TOAST" memento "✓ No memories matched" &>/dev/null
     exit 0
 fi
 
+# Toast: result
+"$TOAST" memento "✓ ${SAAS_COUNT} memories recalled" &>/dev/null
+
 # Block the Stop so Claude continues — the reason becomes Claude's next instruction.
 REASON="Autonomous Recall: ${SAAS_COUNT} memories surfaced from your last response.
 ${SAAS_DETAIL}

package/scripts/memento-userprompt-recall.sh

@@ -7,6 +7,7 @@
 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 "
@@ -66,6 +67,9 @@ fi
 
 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 \
     -X POST \
@@ -118,9 +122,13 @@ if [ -n "$REMAINING" ]; then
 fi
 
 if [ -z "$SAAS_COUNT" ] || [ "$SAAS_COUNT" = "0" ]; then
+    "$TOAST" memento "✓ No memories matched" &>/dev/null
     exit 0
 fi
 
+# Toast: result
+"$TOAST" memento "✓ ${SAAS_COUNT} memories recalled" &>/dev/null
+
 DETAIL_TEXT="Memento Recall: ${SAAS_COUNT} memories"
 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"

package/src/cli.js

@@ -96,6 +96,14 @@ function httpsPost(url, body) {
 // File writers
 // ---------------------------------------------------------------------------
 
+function readJsonFile(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
 function writeJsonFile(filePath, data) {
   const dir = path.dirname(filePath);
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
@@ -103,14 +111,7 @@ function writeJsonFile(filePath, data) {
 }
 
 function mergeJsonFile(filePath, data) {
-  let existing = {};
-  if (fs.existsSync(filePath)) {
-    try {
-      existing = JSON.parse(fs.readFileSync(filePath, "utf8"));
-    } catch {
-      // Corrupt file — overwrite
-    }
-  }
+  const existing = readJsonFile(filePath) || {};
   const merged = deepMerge(existing, data);
   writeJsonFile(filePath, merged);
 }
@@ -127,6 +128,106 @@ function appendToGitignore(cwd, line) {
   return true;
 }
 
+// ---------------------------------------------------------------------------
+// Agent registry — per-agent MCP config writers
+// ---------------------------------------------------------------------------
+
+const MCP_SERVER_ENTRY = {
+  command: "npx",
+  args: ["-y", "memento-mcp"],
+};
+
+function writeMcpJson(cwd) {
+  const filePath = path.join(cwd, ".mcp.json");
+  const existing = readJsonFile(filePath) || {};
+  deepMerge(existing, { mcpServers: { memento: MCP_SERVER_ENTRY } });
+  writeJsonFile(filePath, existing);
+  return ".mcp.json";
+}
+
+function writeCodexToml(cwd) {
+  const dir = path.join(cwd, ".codex");
+  fs.mkdirSync(dir, { recursive: true });
+  const filePath = path.join(dir, "config.toml");
+
+  let content = "";
+  try {
+    content = fs.readFileSync(filePath, "utf8");
+  } catch {
+    /* file doesn't exist */
+  }
+
+  // Skip if memento section already exists
+  if (/\[mcp_servers\.memento\]/.test(content)) {
+    return ".codex/config.toml (already configured)";
+  }
+
+  const section = `\n[mcp_servers.memento]\ncommand = "npx"\nargs = ["-y", "memento-mcp"]\n`;
+  const separator = content && !content.endsWith("\n") ? "\n" : "";
+  fs.writeFileSync(filePath, content + separator + section);
+  return ".codex/config.toml";
+}
+
+function writeGeminiJson(cwd) {
+  const dir = path.join(cwd, ".gemini");
+  fs.mkdirSync(dir, { recursive: true });
+  const filePath = path.join(dir, "settings.json");
+  const existing = readJsonFile(filePath) || {};
+  deepMerge(existing, { mcpServers: { memento: MCP_SERVER_ENTRY } });
+  writeJsonFile(filePath, existing);
+  return ".gemini/settings.json";
+}
+
+function writeOpencodeJson(cwd) {
+  const filePath = path.join(cwd, "opencode.json");
+  const existing = readJsonFile(filePath) || {};
+  deepMerge(existing, {
+    mcp: {
+      memento: {
+        type: "local",
+        command: ["npx", "-y", "memento-mcp"],
+        enabled: true,
+      },
+    },
+  });
+  writeJsonFile(filePath, existing);
+  return "opencode.json";
+}
+
+const AGENTS = {
+  "claude-code": {
+    name: "Claude Code",
+    detect: (cwd) => fs.existsSync(path.join(cwd, ".claude")),
+    configWriter: writeMcpJson,
+    hasHooks: true,
+    nextSteps: "Restart Claude Code to activate.",
+  },
+  codex: {
+    name: "OpenAI Codex",
+    detect: (cwd) => fs.existsSync(path.join(cwd, ".codex")),
+    configWriter: writeCodexToml,
+    hasHooks: false,
+    nextSteps: "Run `codex` in this directory — memento tools load automatically.",
+  },
+  gemini: {
+    name: "Gemini CLI",
+    detect: (cwd) => fs.existsSync(path.join(cwd, ".gemini")),
+    configWriter: writeGeminiJson,
+    hasHooks: false,
+    nextSteps: "Run `gemini` in this directory — memento tools load automatically.",
+  },
+  opencode: {
+    name: "OpenCode",
+    detect: (cwd) => fs.existsSync(path.join(cwd, "opencode.json")),
+    configWriter: writeOpencodeJson,
+    hasHooks: false,
+    nextSteps: "Run `opencode` in this directory — memento tools load automatically.",
+  },
+};
+
+// Exported for testing
+export { AGENTS, writeMcpJson, writeCodexToml, writeGeminiJson, writeOpencodeJson };
+
 // ---------------------------------------------------------------------------
 // CLI
 // ---------------------------------------------------------------------------
@@ -193,26 +294,76 @@ async function runInit() {
     false,
   );
 
-  // 4. Hooks
-  console.log("\nClaude Code hooks (automate recall + distillation):");
-  const enableUserPrompt = await askYesNo(
-    rl,
-    "  UserPromptSubmit — recall on every message?",
-    true
-  );
-  const enableStop = await askYesNo(rl, "  Stop — autonomous recall after responses?", true);
-  const enablePreCompact = await askYesNo(
-    rl,
-    "  PreCompact — distill memories before context compression?",
-    true
-  );
+  // 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}`);
+  }
+
+  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 hasClaude = selectedAgents.includes("claude-code");
+
+  // 5. Hooks — only if Claude Code selected
+  let enableUserPrompt = false;
+  let enableStop = false;
+  let enablePreCompact = false;
   let enableSessionStart = false;
-  if (enableIdentity) {
-    enableSessionStart = await askYesNo(
+
+  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,
-      "  SessionStart — inject identity + active items at startup?",
-      true
+      "  PreCompact — distill memories before context compression?",
+      true,
     );
+    if (enableIdentity) {
+      enableSessionStart = await askYesNo(
+        rl,
+        "  SessionStart — inject identity + active items at startup?",
+        true,
+      );
+    }
   }
 
   rl.close();
@@ -221,6 +372,7 @@ async function runInit() {
   const config = {
     apiKey,
     workspace,
+    agents: selectedAgents,
     features: {
       images: enableImages,
       identity: enableIdentity,
@@ -235,21 +387,23 @@ async function runInit() {
 
   const created = [];
 
-  // 5. Write .memento.json
+  // 6. Write .memento.json
   const configPath = path.join(cwd, ".memento.json");
   writeJsonFile(configPath, config);
   created.push(".memento.json");
 
-  // 6. Copy hook scripts into .memento/scripts/ for stable paths
-  //    (pointing into the npx cache would break on cache clear or update)
-  const anyHookEnabled = enableUserPrompt || enableStop || enablePreCompact || enableSessionStart;
-  if (anyHookEnabled) {
+  // 7. Copy hook scripts + write Claude Code settings — gated on hasClaude
+  const anyHookEnabled =
+    enableUserPrompt || enableStop || enablePreCompact || enableSessionStart;
+
+  if (hasClaude && anyHookEnabled) {
     const pkgScriptsDir = path.resolve(__dirname, "..", "scripts");
     const localScriptsDir = path.join(cwd, ".memento", "scripts");
     if (!fs.existsSync(localScriptsDir))
       fs.mkdirSync(localScriptsDir, { recursive: true });
 
     const scriptFiles = [
+      "hook-toast.sh",
       enableUserPrompt && "memento-userprompt-recall.sh",
       enableStop && "memento-stop-recall.sh",
       enablePreCompact && "memento-precompact-distill.sh",
@@ -264,7 +418,7 @@ async function runInit() {
     }
     created.push(".memento/scripts/");
 
-    // 7. Write .claude/settings.local.json (hooks)
+    // 8. Write .claude/settings.local.json (hooks)
     const hooks = {};
     if (enableUserPrompt) {
       hooks.UserPromptSubmit = [
@@ -305,14 +459,16 @@ async function runInit() {
         },
       ];
     }
-
     if (enableSessionStart) {
       hooks.SessionStart = [
         {
           hooks: [
             {
               type: "command",
-              command: path.join(localScriptsDir, "memento-sessionstart-identity.sh"),
+              command: path.join(
+                localScriptsDir,
+                "memento-sessionstart-identity.sh",
+              ),
               timeout: 10000,
             },
           ],
@@ -325,30 +481,29 @@ async function runInit() {
     created.push(".claude/settings.local.json");
   }
 
-  // 8. Write .mcp.json
-  const mcpPath = path.join(cwd, ".mcp.json");
-  mergeJsonFile(mcpPath, {
-    mcpServers: {
-      memento: {
-        command: "npx",
-        args: ["-y", "memento-mcp"],
-      },
-    },
-  });
-  created.push(".mcp.json");
+  // 9. Per-agent config files
+  for (const agentKey of selectedAgents) {
+    const agent = AGENTS[agentKey];
+    const result = agent.configWriter(cwd);
+    created.push(result);
+  }
 
-  // 9. Add .memento.json and .memento/scripts/ to .gitignore
+  // 10. Add .memento.json and .memento/scripts/ to .gitignore
   let gitignoreUpdated = false;
   if (appendToGitignore(cwd, ".memento.json")) gitignoreUpdated = true;
   if (appendToGitignore(cwd, ".memento/scripts/")) gitignoreUpdated = true;
   if (gitignoreUpdated) created.push(".gitignore (updated)");
 
-  // 10. Summary
+  // 11. Summary
   const labels = {
     ".memento.json": "workspace config + credentials",
     ".memento/scripts/": "hook scripts (recall + distillation)",
     ".claude/settings.local.json": "hooks registered with Claude Code",
-    ".mcp.json": "MCP server registered",
+    ".mcp.json": "MCP server registered (Claude Code)",
+    ".codex/config.toml": "MCP server registered (Codex)",
+    ".codex/config.toml (already configured)": "MCP server (Codex, skipped)",
+    ".gemini/settings.json": "MCP server registered (Gemini CLI)",
+    "opencode.json": "MCP server registered (OpenCode)",
     ".gitignore (updated)": "credentials excluded from git",
   };
   const colWidth = Math.max(...created.map((f) => f.length)) + 2;
@@ -358,14 +513,25 @@ async function runInit() {
     const label = labels[f] || "";
     console.log(`    ${f.padEnd(colWidth)}${label}`);
   }
-  console.log("\n  Restart Claude Code to activate.");
+
+  // Per-agent next steps
+  console.log("\n  Next steps:");
+  for (const agentKey of selectedAgents) {
+    const agent = AGENTS[agentKey];
+    console.log(`    · ${agent.name}: ${agent.nextSteps}`);
+  }
   console.log("  Your agent will wake up remembering.\n");
 
-  // 11. CLAUDE.md boilerplate
+  // 12. CLAUDE.md / AGENTS.md boilerplate
+  const hasNonClaude = selectedAgents.some((k) => k !== "claude-code");
+  const docTarget = hasNonClaude
+    ? "your CLAUDE.md, AGENTS.md, or equivalent"
+    : "your CLAUDE.md";
+
   console.log("─".repeat(60));
   console.log(`
-  One more step: paste the following into your CLAUDE.md,
-  or hand it to Claude and ask it to add it. This teaches
+  One more step: paste the following into ${docTarget},
+  or hand it to your agent and ask it to add it. This teaches
   your agent the memory discipline Memento expects.
 
   ── paste below this line ──────────────────────────────
@@ -392,32 +558,39 @@ before compaction. Trust the hooks. Focus on writing good memories.
 }
 
 // ---------------------------------------------------------------------------
-// Entrypoint
+// Entrypoint — only run when this module is the entry point (not imported)
 // ---------------------------------------------------------------------------
 
-const args = process.argv.slice(2);
+const isMain =
+  process.argv[1] &&
+  (process.argv[1].endsWith("/cli.js") || process.argv[1].endsWith("memento-mcp"));
 
-if (args[0] === "init") {
-  runInit().catch((err) => {
-    console.error(err);
-    process.exit(1);
-  });
-} else if (args.length === 0) {
-  // No args — start the MCP server (this is what .mcp.json invokes)
-  // Must call main() explicitly because the isMainModule guard in index.js
-  // checks process.argv[1] which still points to cli.js, not index.js.
-  const { main } = await import("./index.js");
-  await main();
-} else {
-  console.log(`
+if (isMain) {
+  const args = process.argv.slice(2);
+
+  if (args[0] === "init") {
+    runInit().catch((err) => {
+      console.error(err);
+      process.exit(1);
+    });
+  } else if (args.length === 0) {
+    // No args — start the MCP server (this is what .mcp.json invokes)
+    // Must call main() explicitly because the isMainModule guard in index.js
+    // checks process.argv[1] which still points to cli.js, not index.js.
+    const { main } = await import("./index.js");
+    await main();
+  } else {
+    console.log(`
   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)
 
-  This creates .memento.json, configures Claude Code hooks,
-  and sets up the MCP server — all in one command.
+  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);
+    process.exit(1);
+  }
 }

package/src/config.js

@@ -14,6 +14,7 @@ import path from "node:path";
 export const DEFAULTS = {
   apiUrl: "https://memento-api.myrakrusemark.workers.dev",
   workspace: "default",
+  agents: [],
   features: { images: false, identity: false },
   hooks: {
     "userprompt-recall": { enabled: true, limit: 5, maxLength: 200 },
@@ -69,5 +70,7 @@ export function resolveConfig(startDir = process.cwd()) {
     hooks[key] = { ...defaults, ...(fileConfig.hooks?.[key] || {}) };
   }
 
-  return { apiKey, apiUrl, workspace, features, hooks };
+  const agents = fileConfig.agents || DEFAULTS.agents;
+
+  return { apiKey, apiUrl, workspace, agents, features, hooks };
 }