memento-mcp 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -8,6 +8,13 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Version
 
 ## [Unreleased]
 
+### Added
+- `precompact-distill` hook supports `model` config option in `.memento.json`: `"llama"` (default, free via Cloudflare Workers AI) or `"claude-code"` (runs `claude -p` locally, better extraction quality, uses API credits).
+- `/v1/context` memory matches now include `created_at` timestamp — enables contradiction resolution and temporal reasoning when comparing recalled memories.
+
+### Changed
+- `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`.
+
 ---
 
 ## [0.2.0] - 2026-02-20

package/package.json

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

package/scripts/README.md

@@ -107,12 +107,29 @@ Fires after every assistant response. Uses the assistant's own output as the rec
 
 ### `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.
+Fires before Claude Code compresses the conversation. Parses the full JSONL transcript and extracts novel facts, decisions, and observations as stored memories. Supports two extraction backends:
 
-- **Timeout:** 30 seconds
+- **`"llama"` (default)** — sends transcript to `/v1/distill`, which runs Llama 3.1 8B via Cloudflare Workers AI. Free.
+- **`"claude-code"`** — runs `claude -p` locally for better extraction quality, then pushes to `/v1/memories/ingest`. Uses API credits.
+
+Configure the model in `.memento.json`:
+
+```json
+{
+  "hooks": {
+    "precompact-distill": {
+      "enabled": true,
+      "model": "claude-code"
+    }
+  }
+}
+```
+
+- **Timeout:** 30s (llama) / 60s (claude-code)
 - **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
+- **Source tag:** `source:distill:llama-3.1-8b` or `source:distill:claude-code` — identifies which model extracted each memory
 
 **Output format:** JSON with `systemMessage` only (informational).
 

package/scripts/memento-precompact-distill.sh

@@ -54,6 +54,7 @@ print('true' if hook.get('enabled', True) else 'false')
     MEMENTO_API_KEY="${MEMENTO_API_KEY:-$(echo "$CONFIG_JSON" | python3 -c "import json,sys; print(json.load(sys.stdin).get('apiKey',''))" 2>/dev/null)}"
     MEMENTO_API_URL="${MEMENTO_API_URL:-$(echo "$CONFIG_JSON" | python3 -c "import json,sys; print(json.load(sys.stdin).get('apiUrl',''))" 2>/dev/null)}"
     MEMENTO_WORKSPACE="${MEMENTO_WORKSPACE:-$(echo "$CONFIG_JSON" | python3 -c "import json,sys; print(json.load(sys.stdin).get('workspace',''))" 2>/dev/null)}"
+    DISTILL_MODEL="${DISTILL_MODEL:-$(echo "$CONFIG_JSON" | python3 -c "import json,sys; print(json.load(sys.stdin).get('hooks',{}).get('precompact-distill',{}).get('model','llama'))" 2>/dev/null)}"
 fi
 # --- End config block ---
 
@@ -81,6 +82,99 @@ if [ ${#TRANSCRIPT_TEXT} -lt 200 ]; then
     exit 0  # Too short to distill anything useful
 fi
 
+DISTILL_MODEL="${DISTILL_MODEL:-llama}"
+
+# claude-code path: run extraction locally via claude -p, push to /v1/memories/ingest
+if [ "$DISTILL_MODEL" = "claude-code" ]; then
+    PROMPT_FILE=$(mktemp)
+    cat > "$PROMPT_FILE" << 'DISTILL_PROMPT'
+You are a memory extraction system. Read the conversation transcript below and extract discrete memories worth remembering long-term.
+
+Rules:
+- Extract ONLY genuinely new information — facts, decisions, preferences, instructions, observations, or insights.
+- Each memory should be a single, self-contained statement.
+- Each memory needs a type: "fact", "decision", "instruction", "observation", or "preference".
+- Each memory needs tags (max 6, lowercase, hyphenated). Do NOT include a source tag.
+- If the conversation is trivial, return an empty array.
+- Return ONLY valid JSON — no markdown, no commentary, no code fences.
+
+Memory writing style:
+- Lead with the most searchable term: entity names, project names, specific identifiers.
+- Preserve exact values verbatim: IDs, amounts, measurements, dates.
+- Use direct active phrasing.
+
+Output format:
+[{"content": "...", "type": "fact", "tags": ["tag1", "tag2"]}]
+
+If nothing novel to extract, return: []
+
+---
+TRANSCRIPT:
+DISTILL_PROMPT
+    echo "$TRANSCRIPT_TEXT" >> "$PROMPT_FILE"
+
+    RAW_OUTPUT=$(claude -p "$(cat "$PROMPT_FILE")" 2>/dev/null)
+    rm -f "$PROMPT_FILE"
+
+    CC_SUMMARY=$(echo "$RAW_OUTPUT" | python3 -c "
+import json, sys, re
+from collections import Counter
+raw = sys.stdin.read()
+cleaned = re.sub(r'^\x60{3}(?:json)?\s*', '', raw.strip(), flags=re.IGNORECASE)
+cleaned = re.sub(r'\s*\x60{3}$', '', cleaned.strip())
+try:
+    parsed = json.loads(cleaned.strip())
+except Exception:
+    match = re.search(r'\[[\s\S]*\]', raw)
+    try:
+        parsed = json.loads(match.group(0)) if match else []
+    except Exception:
+        parsed = []
+if not isinstance(parsed, list):
+    parsed = []
+count = len(parsed)
+if count == 0:
+    print('0|')
+else:
+    type_counts = Counter(m.get('type', 'unknown') for m in parsed)
+    breakdown = ', '.join(f\"{v} {k}{'s' if v != 1 else ''}\" for k, v in sorted(type_counts.items()))
+    print(f'{count}|{breakdown}')
+" 2>/dev/null)
+
+    MEMORY_COUNT=$(echo "$CC_SUMMARY" | cut -d'|' -f1)
+    TYPE_BREAKDOWN=$(echo "$CC_SUMMARY" | cut -d'|' -f2)
+
+    if [ "${MEMORY_COUNT:-0}" -gt 0 ] 2>/dev/null; then
+        INGEST_PAYLOAD=$(echo "$RAW_OUTPUT" | python3 -c "
+import json, sys, re
+raw = sys.stdin.read()
+cleaned = re.sub(r'^\x60{3}(?:json)?\s*', '', raw.strip(), flags=re.IGNORECASE)
+cleaned = re.sub(r'\s*\x60{3}$', '', cleaned.strip())
+try:
+    parsed = json.loads(cleaned.strip())
+except Exception:
+    match = re.search(r'\[[\s\S]*\]', raw)
+    parsed = json.loads(match.group(0)) if match else []
+print(json.dumps({'memories': parsed, 'source': 'distill:claude-code'}))
+" 2>/dev/null)
+
+        curl -s --max-time 60 \
+            -X POST \
+            -H "Authorization: Bearer $MEMENTO_KEY" \
+            -H "X-Memento-Workspace: $MEMENTO_WS" \
+            -H "Content-Type: application/json" \
+            -d "$INGEST_PAYLOAD" \
+            "$MEMENTO_API/v1/memories/ingest" > /dev/null 2>&1
+
+        python3 -c "import json,sys; print(json.dumps({'systemMessage': sys.argv[1]}))" \
+            "Memento Distill (claude-code): ${MEMORY_COUNT} memories — ${TYPE_BREAKDOWN}"
+    else
+        python3 -c "import json,sys; print(json.dumps({'systemMessage': sys.argv[1]}))" \
+            "Memento Distill (claude-code): no memories extracted"
+    fi
+    exit 0
+fi
+
 # Send to Memento SaaS /v1/distill
 RESPONSE=$(curl -s --max-time 30 \
     -X POST \
@@ -91,27 +185,32 @@ RESPONSE=$(curl -s --max-time 30 \
     "$MEMENTO_API/v1/distill" 2>/dev/null)
 
 # Report results
-MEMORY_COUNT=$(echo "$RESPONSE" | python3 -c "
+DISTILL_SUMMARY=$(echo "$RESPONSE" | python3 -c "
 import json, sys
+from collections import Counter
 try:
     data = json.load(sys.stdin)
-    print(len(data.get('memories', [])))
+    memories = data.get('memories', [])
+    count = len(memories)
+    if count == 0:
+        print('0|')
+    else:
+        type_counts = Counter(m.get('type', 'unknown') for m in memories)
+        breakdown = ', '.join(f\"{v} {k}{'s' if v != 1 else ''}\" for k, v in sorted(type_counts.items()))
+        print(f'{count}|{breakdown}')
 except Exception:
-    print('0')
+    print('0|')
 " 2>/dev/null)
 
-if [ "$MEMORY_COUNT" -gt 0 ] 2>/dev/null; then
-    python3 -c "
-import json, sys
-msg = sys.argv[1]
-print(json.dumps({'systemMessage': msg}))
-" "Memento Distill: extracted ${MEMORY_COUNT} memories"
+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
+    python3 -c "import json,sys; print(json.dumps({'systemMessage': sys.argv[1]}))" \
+        "Memento Distill: ${MEMORY_COUNT} memories — ${TYPE_BREAKDOWN}"
 else
-    python3 -c "
-import json, sys
-msg = sys.argv[1]
-print(json.dumps({'systemMessage': msg}))
-" "Memento Distill: no memories extracted"
+    python3 -c "import json,sys; print(json.dumps({'systemMessage': sys.argv[1]}))" \
+        "Memento Distill: no memories extracted"
 fi
 
 exit 0

package/scripts/memento-stop-recall.sh

@@ -96,7 +96,8 @@ try:
             tag_str = f' [{\", \".join(tags)}]' if tags else ''
             content = m['content'][:${RECALL_MAX_LENGTH:-200}]
             score = m.get('score', '?')
-            lines.append(f'  {m[\"id\"]} ({m[\"type\"]}, {score}){tag_str} — {content}')
+            date_str = f' {m["created_at"][:10]}' if m.get('created_at') else ''
+            lines.append(f'  {m[\"id\"]} ({m[\"type\"]}, {score}{date_str}){tag_str} — {content}')
             count += 1
 
     skip_matches = data.get('skip_matches', [])

package/scripts/memento-userprompt-recall.sh

@@ -89,7 +89,8 @@ try:
             tag_str = f' [{\", \".join(tags)}]' if tags else ''
             content = m['content'][:${RECALL_MAX_LENGTH:-200}]
             score = m.get('score', '?')
-            lines.append(f'  {m[\"id\"]} ({m[\"type\"]}, {score}){tag_str} — {content}')
+            date_str = f' {m["created_at"][:10]}' if m.get('created_at') else ''
+            lines.append(f'  {m[\"id\"]} ({m[\"type\"]}, {score}{date_str}){tag_str} — {content}')
             count += 1
 
     # Skip matches (WARNING format)

package/src/config.js

@@ -68,5 +68,8 @@ export function resolveConfig(startDir = process.cwd()) {
     hooks[key] = { ...defaults, ...(fileConfig.hooks?.[key] || {}) };
   }
 
-  return { apiKey, apiUrl, workspace, features, hooks };
+  // peek_workspaces: array of workspace names to include in recall/list queries
+  const peek_workspaces = fileConfig.peek_workspaces || [];
+
+  return { apiKey, apiUrl, workspace, features, hooks, peek_workspaces };
 }

package/src/index.js

@@ -39,6 +39,7 @@ const storage = new HostedStorageAdapter({
   apiKey: config.apiKey,
   apiUrl: config.apiUrl,
   workspace: config.workspace,
+  peekWorkspaces: config.peek_workspaces,
 });
 
 // ---------------------------------------------------------------------------
@@ -268,9 +269,10 @@ Results are ranked by relevance (keyword match + recency + access frequency). Ea
       .optional()
       .describe("Filter by type: fact, decision, observation, instruction"),
     limit: z.number().optional().describe("Max results (default: 10)"),
+    peek_workspaces: z.array(z.string()).optional().describe("Peek into other workspaces (read-only). Returns their memories tagged with workspace name. Max 5."),
   },
-  async ({ query, tags, type, limit }) => {
-    const result = await storage.recallMemories(null, { query, tags, type, limit });
+  async ({ query, tags, type, limit, peek_workspaces }) => {
+    const result = await storage.recallMemories(null, { query, tags, type, limit, peek_workspaces });
 
     if (result._raw) {
       return {
@@ -522,6 +524,108 @@ Use this before routine checks (news, weather, HN stories) to avoid re-reading t
   }
 );
 
+// ---------------------------------------------------------------------------
+// Tool: memento_skip_list
+// ---------------------------------------------------------------------------
+
+server.tool(
+  "memento_skip_list",
+  `List all skip list entries with their IDs. Use this to find entry IDs for removal with memento_skip_remove.
+
+Auto-purges expired entries before returning results.`,
+  {},
+  async () => {
+    const result = await storage.listSkips(null);
+
+    if (result.error) {
+      return { content: [{ type: "text", text: result.error }], isError: true };
+    }
+
+    if (!result.entries || result.entries.length === 0) {
+      return {
+        content: [{ type: "text", text: "Skip list is empty." }],
+      };
+    }
+
+    const formatted = result.entries
+      .map((e) => `**${e.id}** "${e.item}"\n  Reason: ${e.reason}\n  Expires: ${e.expires_at}`)
+      .join("\n\n");
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: `${result.total} skip list entr${result.total === 1 ? "y" : "ies"}:\n\n${formatted}`,
+        },
+      ],
+    };
+  }
+);
+
+// ---------------------------------------------------------------------------
+// Tool: memento_skip_remove
+// ---------------------------------------------------------------------------
+
+server.tool(
+  "memento_skip_remove",
+  `Remove a skip list entry by ID. Use memento_skip_list first to find the entry ID.
+
+Use this when a skip condition has been resolved early or was added in error.`,
+  {
+    id: z.string().describe("Skip entry ID to remove"),
+  },
+  async ({ id }) => {
+    const result = await storage.deleteSkip(null, id);
+
+    if (result._raw) {
+      return {
+        content: [{ type: "text", text: result.text }],
+        ...(result.isError ? { isError: true } : {}),
+      };
+    }
+
+    if (result.error) {
+      return { content: [{ type: "text", text: result.error }], isError: true };
+    }
+
+    return {
+      content: [{ type: "text", text: `Skip entry ${id} removed.` }],
+    };
+  }
+);
+
+// ---------------------------------------------------------------------------
+// Tool: memento_memory_delete
+// ---------------------------------------------------------------------------
+
+server.tool(
+  "memento_memory_delete",
+  `Permanently delete a memory by ID. Prefer memento_consolidate over deletion for most cases — consolidation preserves history while sharpening recall.
+
+Use deletion only for memories that are incorrect, contain errors, or should never have been stored.`,
+  {
+    id: z.string().describe("Memory ID to delete"),
+  },
+  async ({ id }) => {
+    const result = await storage.deleteMemory(null, id);
+
+    if (result._raw) {
+      return {
+        content: [{ type: "text", text: result.text }],
+        ...(result.isError ? { isError: true } : {}),
+      };
+    }
+
+    if (result.error) {
+      return { content: [{ type: "text", text: result.error }], isError: true };
+    }
+
+    return {
+      content: [{ type: "text", text: `Memory ${id} deleted.` }],
+    };
+  }
+);
+
 // ---------------------------------------------------------------------------
 // Tool: memento_health
 // ---------------------------------------------------------------------------
@@ -710,9 +814,10 @@ server.tool(
       .optional()
       .describe("Filter by status"),
     query: z.string().optional().describe("Search title and content"),
+    peek_workspaces: z.array(z.string()).optional().describe("Peek into other workspaces (read-only). Returns their items tagged with workspace name. Max 5."),
   },
-  async ({ category, status, query }) => {
-    const result = await storage.listItems(null, { category, status, query });
+  async ({ category, status, query, peek_workspaces }) => {
+    const result = await storage.listItems(null, { category, status, query, peek_workspaces });
 
     if (result.error) {
       return { content: [{ type: "text", text: result.error }], isError: true };

package/src/storage/hosted.js

@@ -17,11 +17,12 @@
 import { StorageInterface } from "./interface.js";
 
 export class HostedStorageAdapter extends StorageInterface {
-  constructor({ apiKey, apiUrl, workspace }) {
+  constructor({ apiKey, apiUrl, workspace, peekWorkspaces }) {
     super();
     this.apiKey = apiKey;
     this.apiUrl = apiUrl.replace(/\/$/, ""); // strip trailing slash
     this.workspace = workspace || "default";
+    this.peekWorkspaces = peekWorkspaces || [];
   }
 
   /**
@@ -108,11 +109,13 @@ export class HostedStorageAdapter extends StorageInterface {
     return { _raw: true, text, isError: false };
   }
 
-  async recallMemories(_wsPath, { query, tags, type, limit }) {
+  async recallMemories(_wsPath, { query, tags, type, limit, peek_workspaces }) {
     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 peek = peek_workspaces?.length ? peek_workspaces : this.peekWorkspaces;
+    if (peek?.length) params.set("peek_workspaces", peek.join(","));
 
     const json = await this._fetchJson(
       "GET",
@@ -149,6 +152,24 @@ export class HostedStorageAdapter extends StorageInterface {
     return { _raw: true, text, isError: false };
   }
 
+  async listSkips(_wsPath) {
+    const json = await this._fetchJson("GET", "/v1/skip-list");
+    if (json.error) return { error: json.error };
+    return json;
+  }
+
+  async deleteSkip(_wsPath, id) {
+    const { text, isError } = await this._fetch("DELETE", `/v1/skip-list/${id}`);
+    if (isError) return { error: text };
+    return { _raw: true, text, isError: false };
+  }
+
+  async deleteMemory(_wsPath, id) {
+    const { text, isError } = await this._fetch("DELETE", `/v1/memories/${id}`);
+    if (isError) return { error: text };
+    return { _raw: true, text, isError: false };
+  }
+
   async checkSkip(_wsPath, query) {
     const params = new URLSearchParams({ query });
     const { text, isError } = await this._fetch(
@@ -188,6 +209,8 @@ export class HostedStorageAdapter extends StorageInterface {
     if (filters.category) params.set("category", filters.category);
     if (filters.status) params.set("status", filters.status);
     if (filters.query) params.set("q", filters.query);
+    const peek = filters.peek_workspaces?.length ? filters.peek_workspaces : this.peekWorkspaces;
+    if (peek?.length) params.set("peek_workspaces", peek.join(","));
     const qs = params.toString();
     const path = `/v1/working-memory/items${qs ? `?${qs}` : ""}`;
     const res = await this._fetchJson("GET", path);

package/src/storage/interface.js

@@ -79,6 +79,35 @@ export class StorageInterface {
     throw new Error("Not implemented");
   }
 
+  /**
+   * List all skip list entries with IDs. Auto-purges expired entries.
+   * @param {string} wsPath - Resolved workspace path
+   * @returns {Promise<{ entries?: Array, total?: number, error?: string }>}
+   */
+  async listSkips(wsPath) {
+    throw new Error("Not implemented");
+  }
+
+  /**
+   * Remove a skip list entry by ID.
+   * @param {string} wsPath - Resolved workspace path
+   * @param {string} id - Skip entry ID
+   * @returns {Promise<{ _raw?: boolean, text?: string, error?: string }>}
+   */
+  async deleteSkip(wsPath, id) {
+    throw new Error("Not implemented");
+  }
+
+  /**
+   * Permanently delete a memory by ID.
+   * @param {string} wsPath - Resolved workspace path
+   * @param {string} id - Memory ID
+   * @returns {Promise<{ _raw?: boolean, text?: string, error?: string }>}
+   */
+  async deleteMemory(wsPath, id) {
+    throw new Error("Not implemented");
+  }
+
   /**
    * Report memory system health and stats.
    * @param {string} wsPath - Resolved workspace path