memento-mcp 0.3.12 → 0.3.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memento-mcp",
-  "version": "0.3.12",
+  "version": "0.3.14",
   "mcpName": "io.github.myrakrusemark/memento-protocol",
   "description": "The Memento Protocol — persistent memory for AI agents",
   "type": "module",
@@ -22,6 +22,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
     "dotenv": "^16.6.1",
+    "sharp": "^0.34.5",
     "zod": "^3.24.2"
   },
   "files": [

package/scripts/memento-userprompt-recall.sh

@@ -3,6 +3,8 @@
 # JSON output: systemMessage (user sees count) + additionalContext (model sees details).
 #
 # Calls /v1/context endpoint for memories + skip list matches.
+# Supports image search: detects pasted images (Claude Code image cache) and
+# file paths in the message, downscales to 224x224, sends to /v1/context.
 
 set -o pipefail
 
@@ -60,6 +62,7 @@ MEMENTO_WS="${MEMENTO_WORKSPACE:-default}"
 
 INPUT=$(cat)
 USER_MESSAGE=$(echo "$INPUT" | jq -r '.prompt // empty' 2>/dev/null)
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)
 
 if [ -z "$USER_MESSAGE" ] || [ ${#USER_MESSAGE} -lt 10 ]; then
     exit 0
@@ -67,16 +70,97 @@ fi
 
 QUERY="${USER_MESSAGE:0:500}"
 
+# --- Image detection ---
+# Collect up to 3 images from two sources:
+#   1. Claude Code image cache (pasted/dropped images, recent only)
+#   2. File paths mentioned in the message text
+IMAGE_PATHS=()
+
+# Prong 1: Claude Code image cache — pasted images cached in ~/.claude/image-cache/{session_id}/
+if [ -n "$SESSION_ID" ]; then
+    IMAGE_CACHE="$HOME/.claude/image-cache/$SESSION_ID"
+    if [ -d "$IMAGE_CACHE" ]; then
+        while IFS= read -r img; do
+            IMAGE_PATHS+=("$img")
+        done < <(find "$IMAGE_CACHE" -maxdepth 1 -name "*.png" -newermt '5 seconds ago' 2>/dev/null | head -3)
+    fi
+fi
+
+# Prong 2: File paths in message text (explicit image references)
+if [ ${#IMAGE_PATHS[@]} -lt 3 ]; then
+    REMAINING_SLOTS=$(( 3 - ${#IMAGE_PATHS[@]} ))
+    while IFS= read -r img; do
+        if [ -f "$img" ]; then
+            IMAGE_PATHS+=("$img")
+        fi
+    done < <(echo "$USER_MESSAGE" | grep -oE '(/[^ ]+\.(jpg|jpeg|png|gif|webp))' | head -"$REMAINING_SLOTS")
+fi
+
+# Build images JSON array (base64-encoded, downscaled to 224x224)
+IMAGES_JSON=""
+if [ ${#IMAGE_PATHS[@]} -gt 0 ] && command -v convert &>/dev/null; then
+    IMAGES_JSON=$(python3 -c "
+import subprocess, base64, json, sys, os
+
+paths = sys.argv[1:]
+images = []
+for p in paths:
+    if not os.path.isfile(p):
+        continue
+    ext = os.path.splitext(p)[1].lower()
+    mime_map = {'.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.png': 'image/png', '.gif': 'image/gif', '.webp': 'image/webp'}
+    mimetype = mime_map.get(ext, 'image/jpeg')
+    try:
+        result = subprocess.run(
+            ['convert', p, '-resize', '224x224^', '-gravity', 'center', '-extent', '224x224', '-quality', '80', 'jpeg:-'],
+            capture_output=True, timeout=5
+        )
+        if result.returncode == 0 and len(result.stdout) > 0:
+            b64 = base64.b64encode(result.stdout).decode()
+            images.append({'data': b64, 'mimetype': 'image/jpeg'})
+    except Exception:
+        pass
+
+if images:
+    print(json.dumps(images))
+else:
+    print('')
+" "${IMAGE_PATHS[@]}" 2>/dev/null)
+fi
+
 # Toast: start retrieving
 "$TOAST" memento "⏳ Retrieving memories..." &>/dev/null
 
+# Build request body with optional images
+REQUEST_BODY=$(python3 -c "
+import json, sys
+
+message = sys.argv[1]
+images_json = sys.argv[2] if len(sys.argv) > 2 else ''
+
+body = {
+    'message': message,
+    'include': ['memories', 'skip_list']
+}
+
+if images_json:
+    try:
+        images = json.loads(images_json)
+        if images:
+            body['images'] = images
+    except Exception:
+        pass
+
+print(json.dumps(body))
+" "$QUERY" "$IMAGES_JSON")
+
 # Call Memento SaaS /v1/context
 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 "$REQUEST_BODY" \
     "$MEMENTO_API/v1/context" 2>/dev/null \
 | python3 -c "
 import json, sys

package/src/cli.js

@@ -120,9 +120,7 @@ before compaction. Trust the hooks. Focus on writing good memories.`;
 
 const HEADLESS_CMDS = {
   "claude-code": (prompt) => ["claude", "-p", "--dangerously-skip-permissions", prompt],
-  "codex":       (prompt) => ["codex", "exec", prompt],
   "gemini":      (prompt) => ["gemini", prompt],
-  "opencode":    (prompt) => ["opencode", "run", prompt],
 };
 
 function buildIntegrationPrompt(blob) {
@@ -162,13 +160,16 @@ function runAgentHeadless(agentKey, prompt) {
 // ---------------------------------------------------------------------------
 
 function parseFlags(argv) {
-  const flags = { nonInteractive: false, apiKey: null };
+  const flags = { nonInteractive: false, apiKey: null, agent: 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++;
+    } else if (argv[i] === "--agent" && argv[i + 1]) {
+      flags.agent = argv[i + 1];
+      i++;
     }
   }
   // Also check environment variable
@@ -244,29 +245,6 @@ function writeMcpJson(cwd) {
   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 });
@@ -277,22 +255,6 @@ function writeGeminiJson(cwd) {
   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",
@@ -301,38 +263,31 @@ const AGENTS = {
     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,
+    hasHooks: true,
     nextSteps: "Run `gemini` in this directory — memento tools load automatically.",
   },
-  opencode: {
-    name: "OpenCode",
-    detect: (cwd) => fs.existsSync(path.join(cwd, "opencode.json")),
-    configWriter: writeOpencodeJson,
+  manual: {
+    name: "I'll set up my agent myself",
+    detect: () => false,
+    configWriter: () => "(skipped — manual setup)",
     hasHooks: false,
-    nextSteps: "Run `opencode` in this directory — memento tools load automatically.",
+    nextSteps: "Point your agent's MCP config at: npx -y memento-mcp",
   },
 };
 
 // Exported for testing
-export { AGENTS, writeMcpJson, writeCodexToml, writeGeminiJson, writeOpencodeJson };
+export { AGENTS, writeMcpJson, writeGeminiJson };
 
 // ---------------------------------------------------------------------------
 // CLI
 // ---------------------------------------------------------------------------
 
 async function runInit(flags = {}) {
-  const { nonInteractive = false, apiKey: flagApiKey = null } = flags;
+  const { nonInteractive = false, apiKey: flagApiKey = null, agent: flagAgent = null } = flags;
   const cwd = process.cwd();
   const projectName = path.basename(cwd);
 
@@ -420,16 +375,25 @@ async function runInit(flags = {}) {
 
   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)`);
+    if (flagAgent) {
+      // Validate --agent value
+      if (!AGENTS[flagAgent]) {
+        const valid = Object.keys(AGENTS).join(", ");
+        console.error(`  Error: unknown agent "${flagAgent}". Valid agents: ${valid}`);
+        process.exit(1);
+      }
+      selectedAgents = [flagAgent];
+      console.log(`  Agent: ${AGENTS[flagAgent].name} (--agent flag)`);
+    } else {
+      // 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];
@@ -464,8 +428,6 @@ async function runInit(flags = {}) {
   }
 
   const hasClaude = selectedAgents.includes("claude-code");
-
-  // 5. Hooks — if any hook-supporting agent is selected (Claude Code, Gemini CLI)
   const hasGemini = selectedAgents.includes("gemini");
   const hasHookAgent = hasClaude || hasGemini;
 
@@ -531,7 +493,6 @@ async function runInit(flags = {}) {
   created.push(".memento.json");
 
   // 7. Copy hook scripts — gated on any hook-supporting agent
-  const hasCodex = selectedAgents.includes("codex");
   const anyHookEnabled =
     enableUserPrompt || enableStop || enablePreCompact || enableSessionStart;
 
@@ -549,9 +510,6 @@ async function runInit(flags = {}) {
       enableSessionStart && "memento-sessionstart-identity.sh",
     ].filter(Boolean);
 
-    // Also copy Codex notify script if Codex is selected
-    if (hasCodex) scriptFiles.push("memento-codex-notify.sh");
-
     for (const name of scriptFiles) {
       const src = path.join(pkgScriptsDir, name);
       if (!fs.existsSync(src)) continue; // skip if script doesn't exist yet
@@ -604,31 +562,7 @@ async function runInit(flags = {}) {
     }
   }
 
-  // 8c. Codex CLI notify — .codex/config.toml (fire-and-forget, post-turn memory storage)
-  if (hasCodex) {
-    const pkgScriptsDir = path.resolve(__dirname, "..", "scripts");
-    const localScriptsDir = path.join(cwd, ".memento", "scripts");
-    // Ensure the notify script is copied (may not have been copied above if no hook agent)
-    const notifySrc = path.join(pkgScriptsDir, "memento-codex-notify.sh");
-    const notifyDest = path.join(localScriptsDir, "memento-codex-notify.sh");
-    if (fs.existsSync(notifySrc) && !fs.existsSync(notifyDest)) {
-      fs.mkdirSync(localScriptsDir, { recursive: true });
-      fs.copyFileSync(notifySrc, notifyDest);
-      fs.chmodSync(notifyDest, 0o755);
-    }
-    const notifyScript = notifyDest;
-    const codexTomlPath = path.join(cwd, ".codex", "config.toml");
-    let tomlContent = "";
-    try { tomlContent = fs.readFileSync(codexTomlPath, "utf-8"); } catch { /* doesn't exist yet */ }
-    if (!tomlContent.includes("notify")) {
-      const notifyLine = `\nnotify = ["bash", "${notifyScript}"]\n`;
-      const separator = tomlContent && !tomlContent.endsWith("\n") ? "\n" : "";
-      fs.writeFileSync(codexTomlPath, tomlContent + separator + notifyLine);
-      created.push(".codex/config.toml (notify)");
-    }
-  }
-
-  // 9. Per-agent config files
+  // 8c. Per-agent config files
   for (const agentKey of selectedAgents) {
     const agent = AGENTS[agentKey];
     const result = agent.configWriter(cwd);
@@ -641,16 +575,15 @@ async function runInit(flags = {}) {
   if (appendToGitignore(cwd, ".memento/scripts/")) gitignoreUpdated = true;
   if (gitignoreUpdated) created.push(".gitignore (updated)");
 
-  // 11. Summary
+  // 10. 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 (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)",
+    ".gemini/settings.json (hooks)": "hooks registered with Gemini CLI",
+    "(skipped — manual setup)": "MCP config skipped (manual setup)",
     ".gitignore (updated)": "credentials excluded from git",
   };
   const colWidth = Math.max(...created.map((f) => f.length)) + 2;
@@ -669,6 +602,14 @@ async function runInit(flags = {}) {
   }
   console.log("  Your agent will wake up remembering.\n");
 
+  // Show non-interactive equivalent
+  if (!nonInteractive) {
+    const parts = ["npx memento-mcp init -y"];
+    if (apiKey) parts.push(`--api-key ${apiKey}`);
+    parts.push(`--agent ${selectedAgents[0]}`);
+    console.log(`  Non-interactive equivalent:\n    ${parts.join(" ")}\n`);
+  }
+
   // 12. Auto-integrate agent instructions
   const primaryAgent = selectedAgents[0];
   const prompt = buildIntegrationPrompt(INSTRUCTIONS_BLOB);
@@ -797,23 +738,6 @@ async function runUpdate() {
     }
   }
 
-  // Codex CLI — ensure notify is configured
-  const hasCodex = agents.includes("codex")
-    || fs.existsSync(path.join(cwd, ".codex"));
-  if (hasCodex) {
-    const notifyScript = path.join(localScriptsDir, "memento-codex-notify.sh");
-    const codexTomlPath = path.join(cwd, ".codex", "config.toml");
-    let tomlContent = "";
-    try { tomlContent = fs.readFileSync(codexTomlPath, "utf-8"); } catch { /* doesn't exist yet */ }
-    if (!tomlContent.includes("notify") && fs.existsSync(notifyScript)) {
-      const notifyLine = `\nnotify = ["bash", "${notifyScript}"]\n`;
-      const separator = tomlContent && !tomlContent.endsWith("\n") ? "\n" : "";
-      fs.mkdirSync(path.dirname(codexTomlPath), { recursive: true });
-      fs.writeFileSync(codexTomlPath, tomlContent + separator + notifyLine);
-      registeredHooks.push("Codex CLI → .codex/config.toml (notify)");
-    }
-  }
-
   console.log(`\n  ✓ Memento hooks updated to v${pkgVersion}\n`);
   console.log("  Updated scripts:");
   for (const name of updated) {
@@ -882,16 +806,22 @@ if (isMain) {
   Memento Protocol CLI
 
   Usage:
-    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.
-
-  Supports Claude Code, Codex, Gemini CLI, and OpenCode.
+    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 -y --agent gemini     Non-interactive with specific agent
+    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)
+
+  Flags:
+    -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
+
+  The -y flag enables fully non-interactive setup. Combine with --agent
+  to select a specific agent (defaults to auto-detect, then claude-code).
+
+  Supports Claude Code, Gemini CLI, and manual setup for any agent.
 `);
     process.exit(1);
   }

package/src/index.js

@@ -257,11 +257,13 @@ Use tags generously — they power recall. Set expiration for time-sensitive fac
 
 server.tool(
   "memento_recall",
-  `Search stored memories by keyword, tag, or type. Use this before starting work on any topic — someone may have already figured it out.
+  `Search stored memories by keyword, tag, type, or image similarity. Use this before starting work on any topic — someone may have already figured it out.
 
-Results are ranked by relevance (keyword match + recency + access frequency). Each recall increments the memory's access count, reinforcing important memories and letting unused ones decay naturally.`,
+Results are ranked by relevance (keyword match + semantic similarity + recency + access frequency). Each recall increments the memory's access count, reinforcing important memories and letting unused ones decay naturally.
+
+Supports image search: provide image_path to find visually similar memories. Can combine text query + image for multi-modal search.`,
   {
-    query: z.string().describe("Search query (matched against memory content)"),
+    query: z.string().optional().describe("Search query (matched against memory content). Required unless image_path is provided."),
     tags: z.array(z.string()).optional().describe("Filter by tags (matches any)"),
     type: z
       .string()
@@ -269,9 +271,57 @@ Results are ranked by relevance (keyword match + recency + access frequency). Ea
       .describe("Filter by type: fact, decision, observation, instruction"),
     limit: z.number().optional().describe("Max results (default: 10)"),
     workspace: z.string().optional().describe('Omit to search your own workspace. Set to a workspace name (e.g. "fathom") to search that workspace instead.'),
+    image_path: z.string().optional().describe(
+      "Path to an image file to search by visual similarity. Can combine with query for multi-modal search."
+    ),
   },
-  async ({ query, tags, type, limit, workspace }) => {
-    const result = await storage.recallMemories(null, { query, tags, type, limit, workspace });
+  async ({ query, tags, type, limit, workspace, image_path }) => {
+    if (!query && !image_path) {
+      return {
+        content: [{ type: "text", text: 'At least one of "query" or "image_path" is required.' }],
+        isError: true,
+      };
+    }
+
+    // Process image if provided
+    let images;
+    if (image_path) {
+      const MIME_MAP = { ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".png": "image/png", ".gif": "image/gif", ".webp": "image/webp" };
+      const ext = path.extname(image_path).toLowerCase();
+      const mimetype = MIME_MAP[ext];
+      if (!mimetype) {
+        return {
+          content: [{ type: "text", text: `Unsupported image format: ${ext}. Allowed: .jpg, .jpeg, .png, .gif, .webp` }],
+          isError: true,
+        };
+      }
+
+      let buffer;
+      try {
+        buffer = fs.readFileSync(image_path);
+      } catch (err) {
+        return {
+          content: [{ type: "text", text: `Cannot read image: ${err.message}` }],
+          isError: true,
+        };
+      }
+
+      // Downscale to 224x224 via sharp for efficient embedding
+      try {
+        const sharp = (await import("sharp")).default;
+        buffer = await sharp(buffer)
+          .resize(224, 224, { fit: "cover" })
+          .jpeg({ quality: 80 })
+          .toBuffer();
+      } catch {
+        // If sharp fails, send the original — Nomic resizes internally anyway
+      }
+
+      const data = buffer.toString("base64");
+      images = [{ data, mimetype: "image/jpeg" }];
+    }
+
+    const result = await storage.recallMemories(null, { query, tags, type, limit, workspace, images });
 
     if (result._raw) {
       return {

package/src/storage/hosted.js

@@ -108,7 +108,22 @@ export class HostedStorageAdapter extends StorageInterface {
     return { _raw: true, text, isError: false };
   }
 
-  async recallMemories(_wsPath, { query, tags, type, limit, workspace }) {
+  async recallMemories(_wsPath, { query, tags, type, limit, workspace, images }) {
+    // Use POST when images are present (GET can't carry binary data)
+    if (images?.length > 0) {
+      const body = { images };
+      if (query) body.query = query;
+      if (tags?.length) body.tags = tags;
+      if (type) body.type = type;
+      if (limit) body.limit = limit;
+      // Note: cross-workspace peek not supported for image search
+
+      const json = await this._fetchJson("POST", "/v1/memories/recall", body);
+      if (json.error) return { error: json.error };
+      return { _raw: true, text: json.text, memories: json.memories || [], isError: false };
+    }
+
+    // Existing GET path for text-only recall
     const params = new URLSearchParams({ query, format: "json" });
     if (tags?.length) params.set("tags", tags.join(","));
     if (type) params.set("type", type);