memento-mcp 0.3.13 → 0.3.15

package/CHANGELOG.md

@@ -6,6 +6,13 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Version
 
 ---
 
+## [0.3.15] - 2026-03-13
+
+### Changed
+- Renamed `memento_store` → `memento_remember` for cognitive language consistency — pairs with `memento_recall`.
+
+---
+
 ## [Unreleased]
 
 ### Added
@@ -16,7 +23,7 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Version
 - `source:distill` tag renamed to `source:distill:llama-3.1-8b` to encode model provenance. The `claude-code` path tags memories `source:distill:claude-code`.
 
 ### Removed
-- **Passive memory extraction (auto_extract)** — removed conversation buffer, auto-extraction from `/v1/context`, and buffer fallback from `/v1/extract`. Smart models know when to store via `memento_store`; passive extraction produced noisy, low-signal memories. The `memento_extract` tool and `/v1/extract` route still work with explicit transcripts. The `conversation_buffer` table is no longer created for new workspaces.
+- **Passive memory extraction (auto_extract)** — removed conversation buffer, auto-extraction from `/v1/context`, and buffer fallback from `/v1/extract`. Smart models know when to store via `memento_remember`; passive extraction produced noisy, low-signal memories. The `memento_extract` tool and `/v1/extract` route still work with explicit transcripts. The `conversation_buffer` table is no longer created for new workspaces.
 
 ---
 
@@ -85,7 +92,7 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Version
 
 ### Added
 - Initial release
-- MCP server with `memento_init`, `memento_read`, `memento_update`, `memento_store`, `memento_recall`, `memento_skip_add`, `memento_skip_check`, `memento_health`
+- MCP server with `memento_init`, `memento_read`, `memento_update`, `memento_remember`, `memento_recall`, `memento_skip_add`, `memento_skip_check`, `memento_health`
 - SaaS API on Cloudflare Workers + Turso edge database
 - Semantic search via `bge-small-en-v1.5` embeddings in Cloudflare Vectorize
 - Free tier: 100 memories, 20 items, 1 workspace

package/README.md

@@ -101,7 +101,7 @@ The MCP server connects at startup. Restart so it picks up the new config.
 
 ```text
 > memento_health()              # verify connection
-> memento_store(                # store your first memory
+> memento_remember(             # store your first memory
     content: "API uses /v2 endpoints. Auth is Bearer token in header.",
     type: "instruction",
     tags: ["api", "auth"]
@@ -126,7 +126,7 @@ On session start:
 3. `memento_recall` with current task context — find relevant past memories
 
 During work — actively manage your own memories:
-- `memento_store` when you learn something, make a decision, or discover a pattern
+- `memento_remember` when you learn something, make a decision, or discover a pattern
 - `memento_recall` before starting any subtask — someone may have already figured it out
 - `memento_item_update` as you make progress — don't wait until the end
 - `memento_item_create` when new work emerges

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memento-mcp",
-  "version": "0.3.13",
+  "version": "0.3.15",
   "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-stop-recall.sh

@@ -135,7 +135,7 @@ SUMMARY="Memento Recall (${SAAS_COUNT})"
 # If no memories are relevant, respond with <...> to signal active silence.
 REASON="${SUMMARY}:
 ${SAAS_DETAIL}
-Stale or wrong? memento_memory_delete · memento_consolidate · memento_store. Otherwise <...>."
+Stale or wrong? memento_memory_delete · memento_consolidate · memento_remember. Otherwise <...>."
 
 python3 -c "
 import json, sys

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,8 @@ MEMENTO_WS="${MEMENTO_WORKSPACE:-default}"
 
 INPUT=$(cat)
 USER_MESSAGE=$(echo "$INPUT" | jq -r '.prompt // empty' 2>/dev/null)
+TRANSCRIPT_PATH=$(echo "$INPUT" | jq -r '.transcript_path // 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 +71,126 @@ fi
 
 QUERY="${USER_MESSAGE:0:500}"
 
+# --- Image detection ---
+# Collect up to 3 images from two sources:
+#   1. Claude Code image cache (pasted/dropped images, detected via marker file)
+#   2. File paths mentioned in the message text
+IMAGE_PATHS=()
+
+# Prong 1: Claude Code image cache — pasted images cached in ~/.claude/image-cache/{conversation_id}/
+# The conversation UUID comes from transcript_path (basename minus .jsonl), NOT session_id.
+CONV_ID=""
+if [ -n "$TRANSCRIPT_PATH" ]; then
+    CONV_ID=$(basename "$TRANSCRIPT_PATH" .jsonl)
+fi
+
+# Try conversation ID first, fall back to session_id
+IMAGE_CACHE=""
+if [ -n "$CONV_ID" ] && [ -d "$HOME/.claude/image-cache/$CONV_ID" ]; then
+    IMAGE_CACHE="$HOME/.claude/image-cache/$CONV_ID"
+elif [ -n "$SESSION_ID" ] && [ -d "$HOME/.claude/image-cache/$SESSION_ID" ]; then
+    IMAGE_CACHE="$HOME/.claude/image-cache/$SESSION_ID"
+fi
+
+if [ -n "$IMAGE_CACHE" ]; then
+    # Track seen images via marker file to detect newly pasted ones.
+    # Each image is numbered sequentially (1.png, 2.png, ...).
+    MARKER="/tmp/memento-img-seen-$(echo "$IMAGE_CACHE" | md5sum | cut -c1-16)"
+    LAST_SEEN=0
+    if [ -f "$MARKER" ]; then
+        LAST_SEEN=$(cat "$MARKER" 2>/dev/null || echo 0)
+    fi
+
+    CURRENT_COUNT=$(ls "$IMAGE_CACHE"/*.png 2>/dev/null | wc -l)
+
+    if [ "$CURRENT_COUNT" -gt "$LAST_SEEN" ]; then
+        # New images detected — grab the ones we haven't seen
+        for i in $(seq $((LAST_SEEN + 1)) "$CURRENT_COUNT"); do
+            if [ -f "$IMAGE_CACHE/$i.png" ] && [ ${#IMAGE_PATHS[@]} -lt 3 ]; then
+                IMAGE_PATHS+=("$IMAGE_CACHE/$i.png")
+            fi
+        done
+    fi
+
+    # Update marker to current count
+    echo "$CURRENT_COUNT" > "$MARKER"
+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

@@ -100,7 +100,7 @@ function httpsPost(url, body) {
 const INSTRUCTIONS_BLOB = `## Memento Protocol
 
 Working memory is managed by Memento. MCP tools available:
-\`memento_store\`, \`memento_recall\`, \`memento_item_list\`,
+\`memento_remember\`, \`memento_recall\`, \`memento_item_list\`,
 \`memento_skip_add\`, \`memento_skip_check\`.
 
 **Memory discipline — notes are instructions, not logs.**
@@ -108,7 +108,7 @@ 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_remember\` 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
@@ -359,7 +359,7 @@ async function runInit(flags = {}) {
     console.log("\nOptional features:");
     enableImages = await askYesNo(
       rl,
-      "  Enable image attachments? (attach images to memories via memento_store)",
+      "  Enable image attachments? (attach images to memories via memento_remember)",
       false,
     );
     enableIdentity = await askYesNo(

package/src/index.js

@@ -169,11 +169,11 @@ Sections: active_work, standing_decisions, skip_list, session_notes.`,
 );
 
 // ---------------------------------------------------------------------------
-// Tool: memento_store
+// Tool: memento_remember
 // ---------------------------------------------------------------------------
 
 server.tool(
-  "memento_store",
+  "memento_remember",
   `Store a discrete memory — a fact, decision, observation, or instruction — with tags and optional expiration.
 
 IMPORTANT: Write memories as instructions, not logs.
@@ -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);