memento-mcp 0.1.2 → 0.1.3

package/README.md

@@ -104,48 +104,53 @@ Before session ends:
 
 ---
 
-## Hooks
-
-Hooks automate memory at session boundaries — the agent doesn't need to remember to recall or save. Two production-ready scripts are included in `scripts/`.
+## The Protocol
 
-### Setup
+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.
 
-1. **Create a `.env` file** in the repo root (copy from the example):
-
-```bash
-cp .env.example .env
-# Then edit .env with your actual API key and workspace name
-```
+Full guide: **[The Protocol](https://hifathom.com/projects/memento/protocol)** on hifathom.com.
 
-The `.env` file is gitignored. It needs three variables:
+## Hooks
 
-```bash
-MEMENTO_API_KEY=mp_live_your_key_here
-MEMENTO_API_URL=https://memento-api.myrakrusemark.workers.dev
-MEMENTO_WORKSPACE=my-project
-```
+Hooks automate memory at session boundaries — recall on every message, distillation before context loss. Three production-ready scripts are included in `scripts/`.
 
-2. **Make scripts executable** (they should already be, but just in case):
+**Quick setup:**
 
 ```bash
-chmod +x scripts/*.sh
+cp .env.example .env    # add your API key and workspace
+chmod +x scripts/*.sh   # make scripts executable
 ```
 
-3. **Register in Claude Code settings** — add to `.claude/settings.json` (project-level) or `~/.claude/settings.json` (global):
+Then register in `.claude/settings.json` (project-level) or `~/.claude/settings.json` (global):
 
 ```json
 {
   "hooks": {
     "UserPromptSubmit": [
       {
-        "command": "/path/to/memento-protocol/scripts/memento-memory-recall.sh",
-        "timeout": 5000
+        "hooks": [{
+          "type": "command",
+          "command": "/path/to/memento-protocol/scripts/memento-userprompt-recall.sh",
+          "timeout": 5000
+        }]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [{
+          "type": "command",
+          "command": "/path/to/memento-protocol/scripts/memento-stop-recall.sh",
+          "timeout": 5000
+        }]
       }
     ],
     "PreCompact": [
       {
-        "command": "/path/to/memento-protocol/scripts/memento-precompact-distill.sh",
-        "timeout": 30000
+        "hooks": [{
+          "type": "command",
+          "command": "/path/to/memento-protocol/scripts/memento-precompact-distill.sh",
+          "timeout": 30000
+        }]
       }
     ]
   }
@@ -154,23 +159,13 @@ chmod +x scripts/*.sh
 
 Replace `/path/to/memento-protocol` with the actual absolute path to your clone.
 
-### `memento-memory-recall.sh` (UserPromptSubmit)
-
-Fires before every agent response. Sends the user's message to the `/v1/context` endpoint, which returns relevant memories and skip list warnings.
-
-- **Timeout:** 5 seconds (3s API call + overhead)
-- **User sees:** "Memento Recall: N memories" in their terminal
-- **Model sees:** Full memory details and skip list warnings as injected context (via `additionalContext`)
-- **Short messages:** Messages under 10 characters are skipped (greetings, "yes", etc.)
-
-### `memento-precompact-distill.sh` (PreCompact)
-
-Fires before Claude Code compresses the conversation. Parses the full JSONL transcript into readable text, then sends it to `/v1/distill` which extracts key memories, decisions, and observations — so nothing important is lost to compaction.
+| Script | Event | What it does |
+|--------|-------|-------------|
+| `memento-userprompt-recall.sh` | UserPromptSubmit | Recalls memories relevant to the user's message |
+| `memento-stop-recall.sh` | Stop | Recalls memories from the assistant's own output (autonomous work) |
+| `memento-precompact-distill.sh` | PreCompact | Extracts memories from the conversation before context compression |
 
-- **Timeout:** 30 seconds (transcript processing is heavier)
-- **User sees:** "Memento Distill: extracted N memories" in their terminal
-- **Transcript parsing:** Uses a dedicated parser script if available at `/data/Dropbox/Work/fathom/infrastructure/fathom-mcp/scripts/parse-transcript.sh`. Falls back to direct JSONL extraction (works everywhere, just less polished formatting).
-- **Minimum threshold:** Transcripts under 200 characters are skipped.
+See **[scripts/README.md](scripts/README.md)** for detailed documentation on each script, output formats, and how to write your own hooks.
 
 ---
 
@@ -185,6 +180,7 @@ Browse and manage memories visually at [hifathom.com/dashboard](https://hifathom
 Full reference docs at [hifathom.com/projects/memento](https://hifathom.com/projects/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

package/package.json

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

package/scripts/README.md

@@ -0,0 +1,144 @@
+# Memento Protocol — Hook Scripts
+
+Automation hooks for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) that connect the Memento API to session lifecycle events. These scripts make memory automatic — recall on every message, distillation before context loss.
+
+## Naming Convention
+
+Scripts follow the pattern `[system]-[hook]-[verb].sh`:
+
+| Script | Event | What it does |
+|--------|-------|-------------|
+| `memento-userprompt-recall.sh` | UserPromptSubmit | Recall memories relevant to the user's message |
+| `memento-stop-recall.sh` | Stop | Recall memories relevant to the assistant's own output |
+| `memento-precompact-distill.sh` | PreCompact | Extract memories from the conversation before context compression |
+| `launch-stats.sh` | (manual) | Quick metrics — GitHub stars, npm downloads, signups |
+
+## Setup
+
+### 1. Create a `.env` file
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` with your credentials:
+
+```bash
+MEMENTO_API_KEY=mp_live_your_key_here
+MEMENTO_API_URL=https://memento-api.myrakrusemark.workers.dev
+MEMENTO_WORKSPACE=my-project
+```
+
+The `.env` file is gitignored. All scripts source it automatically.
+
+### 2. Make scripts executable
+
+```bash
+chmod +x scripts/*.sh
+```
+
+### 3. Register hooks in Claude Code
+
+Add to `.claude/settings.json` (project-level) or `~/.claude/settings.json` (global):
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [{
+          "type": "command",
+          "command": "/path/to/memento-protocol/scripts/memento-userprompt-recall.sh",
+          "timeout": 5000
+        }]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [{
+          "type": "command",
+          "command": "/path/to/memento-protocol/scripts/memento-stop-recall.sh",
+          "timeout": 5000
+        }]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [{
+          "type": "command",
+          "command": "/path/to/memento-protocol/scripts/memento-precompact-distill.sh",
+          "timeout": 30000
+        }]
+      }
+    ]
+  }
+}
+```
+
+Replace `/path/to/memento-protocol` with the actual absolute path to your clone.
+
+---
+
+## Script Details
+
+### `memento-userprompt-recall.sh` — UserPromptSubmit
+
+Fires before every agent response. Sends the user's message to `/v1/context`, which returns relevant memories and skip list warnings.
+
+- **Timeout:** 5 seconds
+- **User sees:** "Memento Recall: N memories"
+- **Model sees:** Full memory content, scores, tags, and skip list warnings (via `additionalContext`)
+- **Short messages:** Messages under 10 characters are skipped (greetings, "yes", etc.)
+
+**Output format:** JSON with `systemMessage` (user display) + `hookSpecificOutput.additionalContext` (model context).
+
+### `memento-stop-recall.sh` — Stop
+
+Fires after every assistant response. Uses the assistant's own output as the recall query — so memories surface during autonomous work, not just on user messages.
+
+- **Timeout:** 5 seconds
+- **User sees:** "Autonomous Recall: N memories"
+- **Model sees:** Full memory content via the `decision: "block"` mechanism — the `reason` field becomes the model's next instruction
+- **Loop prevention:** Checks `stop_hook_active` flag to prevent infinite recall loops
+- **Empty responses:** Skipped when the assistant message is empty
+
+**Output format:** JSON with `decision: "block"`, `reason` (model context), and `systemMessage` (user display). The block mechanism is the only way to inject content into model context from a Stop hook — `additionalContext` is not supported for Stop events.
+
+**Why this matters:** Without the Stop hook, memories only surface when a human sends a message. For autonomous agents that work independently — running ping routines, doing research, monitoring news — their own memories never get recalled. The Stop hook closes that gap.
+
+### `memento-precompact-distill.sh` — PreCompact
+
+Fires before Claude Code compresses the conversation. Parses the full JSONL transcript and sends it to `/v1/distill`, which extracts novel facts, decisions, and observations as stored memories.
+
+- **Timeout:** 30 seconds
+- **User sees:** "Memento Distill: extracted N memories"
+- **Minimum threshold:** Transcripts under 200 characters are skipped
+- **Transcript parsing:** Extracts user and assistant text from the JSONL format
+
+**Output format:** JSON with `systemMessage` only (informational).
+
+**Why this matters:** Context compaction destroys information. Without distillation, anything discussed but not explicitly saved is lost. This hook captures what's novel — deduplicating against existing memories — so nothing important vanishes.
+
+---
+
+## Hook Output Formats
+
+Claude Code hooks can output data in several formats. These scripts use two:
+
+| Format | Where it appears | Used by |
+|--------|-----------------|---------|
+| `systemMessage` | User's terminal | All scripts |
+| `hookSpecificOutput.additionalContext` | Model context (system-reminder) | UserPromptSubmit recall |
+| `decision: "block"` with `reason` | Model context (next instruction) | Stop recall |
+
+The `additionalContext` approach only works for UserPromptSubmit, PreToolUse, and PostToolUse events. For Stop hooks, the `decision: "block"` pattern is the only mechanism that injects content into model context.
+
+## Adding Your Own Hooks
+
+Follow the naming convention: `[system]-[hook]-[verb].sh`. Your script receives JSON on stdin with event-specific fields:
+
+- **UserPromptSubmit:** `{ "prompt": "user's message" }`
+- **Stop:** `{ "last_assistant_message": "...", "stop_hook_active": false }`
+- **PreCompact:** `{ "transcript_path": "~/.claude/projects/.../conversation.jsonl" }`
+
+Source `.env` for credentials, call the Memento API, and output JSON to stdout. Exit 0 for no-op (nothing to report).

package/scripts/memento-stop-recall.sh

@@ -0,0 +1,104 @@
+#!/bin/bash
+# Memento autonomous recall — fires on Stop (after assistant response).
+# Uses the assistant's own output as the recall query, so memories surface
+# during autonomous work, not just when the user sends a message.
+
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# Source credentials
+if [ -f "$SCRIPT_DIR/../.env" ]; then
+    set -a
+    source "$SCRIPT_DIR/../.env"
+    set +a
+fi
+
+MEMENTO_API="${MEMENTO_API_URL:-https://memento-api.myrakrusemark.workers.dev}"
+MEMENTO_KEY="${MEMENTO_API_KEY:?MEMENTO_API_KEY not set}"
+MEMENTO_WS="${MEMENTO_WORKSPACE:-fathom}"
+
+INPUT=$(cat)
+
+# Prevent infinite loops — if this Stop was triggered by a previous Stop hook, bail
+STOP_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active // false' 2>/dev/null)
+if [ "$STOP_ACTIVE" = "true" ]; then
+    exit 0
+fi
+
+# Get the assistant's last message
+ASSISTANT_MSG=$(echo "$INPUT" | jq -r '.last_assistant_message // empty' 2>/dev/null)
+
+if [ -z "$ASSISTANT_MSG" ]; then
+    exit 0
+fi
+
+# Truncate to first 500 chars for the query
+QUERY="${ASSISTANT_MSG:0:500}"
+
+# Call Memento /v1/context
+RESULT=$(curl -s --max-time 3 \
+    -X POST \
+    -H "Authorization: Bearer $MEMENTO_KEY" \
+    -H "X-Memento-Workspace: $MEMENTO_WS" \
+    -H "Content-Type: application/json" \
+    -d "{\"message\": $(echo "$QUERY" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))'), \"include\": [\"memories\", \"skip_list\"]}" \
+    "$MEMENTO_API/v1/context" 2>/dev/null \
+| python3 -c "
+import json, sys
+try:
+    data = json.load(sys.stdin)
+    lines = []
+    count = 0
+
+    memories = data.get('memories', {}).get('matches', [])
+    if memories:
+        for m in memories[:5]:
+            tags = m.get('tags', [])
+            tag_str = f' [{\", \".join(tags)}]' if tags else ''
+            content = m['content'][:120]
+            score = m.get('score', '?')
+            lines.append(f'  {m[\"id\"]} ({m[\"type\"]}, {score}){tag_str} — {content}')
+            count += 1
+
+    skip_matches = data.get('skip_matches', [])
+    if skip_matches:
+        lines.append('')
+        lines.append('SKIP LIST WARNINGS:')
+        for s in skip_matches:
+            lines.append(f'  ⚠ SKIP: {s[\"item\"]} — {s[\"reason\"]} (expires: {s[\"expires\"]})')
+
+    detail = '\n'.join(lines)
+    print(f'{count}\t{detail}')
+except Exception:
+    print('0\t')
+" 2>/dev/null)
+
+# Parse
+SAAS_COUNT=$(echo "$RESULT" | head -1 | cut -f1)
+SAAS_DETAIL=$(echo "$RESULT" | head -1 | cut -f2-)
+REMAINING=$(echo "$RESULT" | tail -n +2)
+if [ -n "$REMAINING" ]; then
+    SAAS_DETAIL="$SAAS_DETAIL"$'\n'"$REMAINING"
+fi
+
+if [ -z "$SAAS_COUNT" ] || [ "$SAAS_COUNT" = "0" ]; then
+    exit 0
+fi
+
+# Block the Stop so Claude continues — the reason becomes Claude's next instruction.
+# Claude should absorb the memories and respond with <...> (presence without production).
+REASON="Autonomous Recall: ${SAAS_COUNT} memories surfaced from your last response.
+${SAAS_DETAIL}
+
+You have absorbed these memories into context. Respond with <...> — active silence."
+
+SUMMARY="Autonomous Recall: ${SAAS_COUNT} memories"
+python3 -c "
+import json, sys
+print(json.dumps({
+    'decision': 'block',
+    'reason': sys.argv[1],
+    'systemMessage': sys.argv[2]
+}))
+" "$REASON" "$SUMMARY"

package/src/index.js

@@ -12,6 +12,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import path from "node:path";
+import fs from "node:fs";
 import { fileURLToPath } from "node:url";
 import { HostedStorageAdapter } from "./storage/hosted.js";
 
@@ -197,9 +198,30 @@ Use tags generously — they power recall. Set expiration for time-sensitive fac
       )
       .optional()
       .describe("Links to other memories, items, or vault files"),
+    image_path: z
+      .string()
+      .optional()
+      .describe("Local file path to an image to attach to this memory (jpeg, png, gif, webp)"),
   },
-  async ({ content, tags, type, expires, linkages }) => {
-    const result = await storage.storeMemory(null, { content, tags, type, expires, linkages });
+  async ({ content, tags, type, expires, linkages, image_path }) => {
+    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,
+        };
+      }
+      const buffer = fs.readFileSync(image_path);
+      const data = buffer.toString("base64");
+      const filename = path.basename(image_path);
+      images = [{ data, filename, mimetype }];
+    }
+
+    const result = await storage.storeMemory(null, { content, tags, type, expires, linkages, images });
 
     if (result._raw) {
       return {
@@ -278,6 +300,95 @@ Results are ranked by relevance (keyword match + recency + access frequency). Ea
   }
 );
 
+// ---------------------------------------------------------------------------
+// Tool: memento_view_image
+// ---------------------------------------------------------------------------
+
+server.tool(
+  "memento_view_image",
+  `View an image attached to a memory. Use after memento_recall shows a memory has images (look for "Images: [N image(s)]" in results). Returns the image directly in context.
+
+Typical flow: memento_recall → see "Images: [2 images]" on a result → memento_view_image with that memory's ID.`,
+  {
+    memory_id: z.string().describe("The memory ID (from recall results)"),
+    filename: z
+      .string()
+      .optional()
+      .describe(
+        "Specific filename if the memory has multiple images. If omitted, returns the first image."
+      ),
+  },
+  async ({ memory_id, filename }) => {
+    const memory = await storage.getMemory(memory_id);
+
+    if (memory.error) {
+      return {
+        content: [{ type: "text", text: `Error fetching memory ${memory_id}: ${memory.error}` }],
+        isError: true,
+      };
+    }
+
+    const images = memory.images || [];
+    if (images.length === 0) {
+      return {
+        content: [{ type: "text", text: `Memory ${memory_id} has no images.` }],
+      };
+    }
+
+    const img = filename
+      ? images.find((i) => i.filename === filename)
+      : images[0];
+
+    if (!img) {
+      const available = images.map((i) => i.filename).join(", ");
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Image "${filename}" not found on memory ${memory_id}. Available: ${available}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    const MAX_IMAGE_BYTES = 5 * 1024 * 1024;
+    if (img.size > MAX_IMAGE_BYTES) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Image "${img.filename}" is too large (${(img.size / 1024 / 1024).toFixed(1)}MB, max 5MB).`,
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    try {
+      const base64 = await storage.fetchImage(img.key);
+      if (!base64) {
+        return {
+          content: [{ type: "text", text: `Failed to fetch image "${img.filename}" from storage.` }],
+          isError: true,
+        };
+      }
+
+      return {
+        content: [
+          { type: "text", text: `Image from memory ${memory_id}: ${img.filename}` },
+          { type: "image", data: base64, mimeType: img.mimetype },
+        ],
+      };
+    } catch (err) {
+      return {
+        content: [{ type: "text", text: `Error fetching image: ${err.message}` }],
+        isError: true,
+      };
+    }
+  }
+);
+
 // ---------------------------------------------------------------------------
 // Tool: memento_consolidate
 // ---------------------------------------------------------------------------
@@ -707,7 +818,6 @@ async function main() {
 
 // Start the server when run directly (not when imported for testing)
 // Use fs.realpathSync to resolve npm bin symlinks
-import fs from "node:fs";
 const isMainModule =
   process.argv[1] &&
   fs.realpathSync(path.resolve(process.argv[1])) ===

package/src/storage/hosted.js

@@ -99,26 +99,44 @@ export class HostedStorageAdapter extends StorageInterface {
     return { _raw: true, text, isError: false };
   }
 
-  async storeMemory(_wsPath, { content, tags, type, expires, linkages }) {
+  async storeMemory(_wsPath, { content, tags, type, expires, linkages, images }) {
     const body = { content, tags, type, expires };
     if (linkages) body.linkages = linkages;
+    if (images) body.images = images;
     const { text, isError } = await this._fetch("POST", "/v1/memories", body);
     if (isError) return { error: text };
     return { _raw: true, text, isError: false };
   }
 
   async recallMemories(_wsPath, { query, tags, type, limit }) {
-    const params = new URLSearchParams({ query });
+    const params = new URLSearchParams({ query, format: "json" });
     if (tags?.length) params.set("tags", tags.join(","));
     if (type) params.set("type", type);
     if (limit) params.set("limit", String(limit));
 
-    const { text, isError } = await this._fetch(
+    const json = await this._fetchJson(
       "GET",
       `/v1/memories/recall?${params}`
     );
-    if (isError) return { error: text };
-    return { _raw: true, text, isError: false };
+    if (json.error) return { error: json.error };
+    return { _raw: true, text: json.text, memories: json.memories || [], isError: false };
+  }
+
+  async getMemory(id) {
+    return this._fetchJson("GET", `/v1/memories/${id}`);
+  }
+
+  async fetchImage(imageKey) {
+    const url = `${this.apiUrl}/v1/images/${imageKey}`;
+    const res = await fetch(url, {
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        "X-Memento-Workspace": this.workspace,
+      },
+    });
+    if (!res.ok) return null;
+    const buffer = await res.arrayBuffer();
+    return Buffer.from(buffer).toString("base64");
   }
 
   async addSkip(_wsPath, { item, reason, expires }) {