prism-mcp-server 2.3.12 → 2.5.1

package/dist/tools/sessionMemoryHandlers.js

@@ -20,9 +20,17 @@ import { getStorage } from "../storage/index.js";
 import { toKeywordArray } from "../utils/keywordExtractor.js";
 import { generateEmbedding } from "../utils/embeddingApi.js";
 import { getCurrentGitState, getGitDrift } from "../utils/git.js";
+// ─── Phase 1: Explainability & Memory Lineage ────────────────
+// These utilities provide structured tracing metadata for search operations.
+// When `enable_trace: true` is passed to session_search_memory or knowledge_search,
+// a separate MCP content block (content[1]) is returned with a MemoryTrace object
+// containing: strategy, scores, latency breakdown (embedding/storage/total), and metadata.
+// See src/utils/tracing.ts for full type definitions and design decisions.
+import { createMemoryTrace, traceToContentBlock } from "../utils/tracing.js";
 import { GOOGLE_API_KEY, PRISM_USER_ID, PRISM_AUTO_CAPTURE, PRISM_CAPTURE_PORTS } from "../config.js";
 import { captureLocalEnvironment } from "../utils/autoCapture.js";
 import { isSessionSaveLedgerArgs, isSessionSaveHandoffArgs, isSessionLoadContextArgs, isKnowledgeSearchArgs, isKnowledgeForgetArgs, isSessionSearchMemoryArgs, isBackfillEmbeddingsArgs, isMemoryHistoryArgs, isMemoryCheckoutArgs, isSessionHealthCheckArgs, // v2.2.0: health check type guard
+isSessionForgetMemoryArgs, // Phase 2: GDPR-compliant memory deletion type guard
  } from "./sessionMemoryDefinitions.js";
 import { notifyResourceUpdate } from "../server.js";
 // ─── Save Ledger Handler ──────────────────────────────────────
@@ -471,15 +479,43 @@ export async function sessionLoadContextHandler(args) {
 // ─── Knowledge Search Handler ─────────────────────────────────
 /**
  * Searches accumulated knowledge across all past sessions.
+ *
+ * ═══════════════════════════════════════════════════════════════════
+ * PHASE 1 CHANGES (Explainability & Memory Lineage):
+ *
+ * Added `enable_trace` optional parameter (default: false).
+ * When enabled, appends a MemoryTrace content block to the response
+ * with strategy="keyword", timing data, and result metadata.
+ *
+ * TIMING INSTRUMENTATION:
+ *   - totalStart: captured before any work begins
+ *   - storageStart/storageMs: isolates database query time
+ *   - embeddingMs: always 0 for keyword search (no embedding needed)
+ *   - totalMs: end-to-end including keyword extraction overhead
+ *
+ * BACKWARD COMPATIBILITY:
+ *   When enable_trace is false (default), the response is identical
+ *   to the pre-Phase 1 implementation. Zero breaking changes.
+ *
+ * MCP OUTPUT ARRAY:
+ *   content[0] = human-readable search results (unchanged)
+ *   content[1] = machine-readable MemoryTrace JSON (only when enable_trace=true)
+ * ═══════════════════════════════════════════════════════════════════
  */
 export async function knowledgeSearchHandler(args) {
     if (!isKnowledgeSearchArgs(args)) {
         throw new Error("Invalid arguments for knowledge_search");
     }
-    const { project, query, category, limit = 10 } = args;
+    // Phase 1: destructure enable_trace (defaults to false for backward compat)
+    const { project, query, category, limit = 10, enable_trace = false } = args;
     debugLog(`[knowledge_search] Searching: project=${project || "all"}, query="${query || ""}", category=${category || "any"}, limit=${limit}`);
+    // Phase 1: Capture total start time for latency measurement
+    const totalStart = performance.now();
     const searchKeywords = query ? toKeywordArray(query) : [];
     const storage = await getStorage();
+    // Phase 1: Capture storage-specific start time to isolate DB latency
+    // from keyword extraction and other overhead
+    const storageStart = performance.now();
     const data = await storage.searchKnowledge({
         project: project || null,
         keywords: searchKeywords,
@@ -488,27 +524,60 @@ export async function knowledgeSearchHandler(args) {
         limit: Math.min(limit, 50),
         userId: PRISM_USER_ID,
     });
+    const storageMs = performance.now() - storageStart;
+    const totalMs = performance.now() - totalStart;
     if (!data) {
-        return {
-            content: [{
-                    type: "text",
-                    text: `🔍 No knowledge found matching your search.\n` +
-                        (query ? `Query: "${query}"\n` : "") +
-                        (category ? `Category: ${category}\n` : "") +
-                        (project ? `Project: ${project}\n` : "") +
-                        `\nTip: Try session_search_memory for semantic (meaning-based) search ` +
-                        `if keyword search doesn't find what you need.`,
-                }],
-            isError: false,
-        };
-    }
-    return {
-        content: [{
+        // Phase 1: Use contentBlocks array instead of inline object
+        // so we can conditionally push the trace block at content[1]
+        const contentBlocks = [{
                 type: "text",
-                text: `🧠 Found ${data.count} knowledge entries:\n\n${JSON.stringify(data, null, 2)}`,
-            }],
-        isError: false,
-    };
+                text: `🔍 No knowledge found matching your search.\n` +
+                    (query ? `Query: "${query}"\n` : "") +
+                    (category ? `Category: ${category}\n` : "") +
+                    (project ? `Project: ${project}\n` : "") +
+                    `\nTip: Try session_search_memory for semantic (meaning-based) search ` +
+                    `if keyword search doesn't find what you need.`,
+            }];
+        // Phase 1: Append trace block even on empty results — this tells
+        // the developer the search DID execute, it just found nothing.
+        // topScore and threshold are null for keyword search (no scoring system).
+        if (enable_trace) {
+            const trace = createMemoryTrace({
+                strategy: "keyword",
+                query: query || "",
+                resultCount: 0,
+                topScore: null, // keyword search doesn't produce similarity scores
+                threshold: null, // keyword search has no threshold concept
+                embeddingMs: 0, // no embedding needed for keyword search
+                storageMs,
+                totalMs,
+                project: project || null,
+            });
+            contentBlocks.push(traceToContentBlock(trace));
+        }
+        return { content: contentBlocks, isError: false };
+    }
+    // Phase 1: Wrap in contentBlocks array for optional trace attachment
+    const contentBlocks = [{
+            type: "text",
+            text: `🧠 Found ${data.count} knowledge entries:\n\n${JSON.stringify(data, null, 2)}`,
+        }];
+    // Phase 1: Attach MemoryTrace with strategy="keyword" and timing data
+    if (enable_trace) {
+        const trace = createMemoryTrace({
+            strategy: "keyword",
+            query: query || "",
+            resultCount: data.count,
+            topScore: null, // keyword search doesn't produce similarity scores
+            threshold: null, // keyword search has no threshold concept
+            embeddingMs: 0, // no embedding needed for keyword search
+            storageMs,
+            totalMs,
+            project: project || null,
+        });
+        contentBlocks.push(traceToContentBlock(trace));
+    }
+    return { content: contentBlocks, isError: false };
 }
 // ─── Knowledge Forget Handler ─────────────────────────────────
 /**
@@ -581,15 +650,55 @@ export async function knowledgeForgetHandler(args) {
 }
 // ─── Semantic Search Handler ──────────────────────────────────
 /**
- * Searches session history semantically using embeddings.
+ * Searches session history semantically using vector embeddings.
+ *
+ * ═══════════════════════════════════════════════════════════════════
+ * PHASE 1 CHANGES (Explainability & Memory Lineage):
+ *
+ * Added `enable_trace` optional parameter (default: false).
+ * When enabled, appends a MemoryTrace content block to the response.
+ *
+ * TIMING INSTRUMENTATION (3 checkpoints):
+ *   1. totalStart: before any work begins
+ *   2. embeddingStart/embeddingMs: isolates Gemini API call latency
+ *      (this is the most variable — 50ms to 2000ms depending on load)
+ *   3. storageStart/storageMs: isolates pgvector/SQLite query time
+ *
+ * WHY SEPARATE EMBEDDING FROM STORAGE:
+ *   A single latency_ms number is misleading. Example:
+ *   - 500ms total could be 480ms Gemini API + 20ms pgvector
+ *     → Fix: cache embeddings or switch to a faster model
+ *   - 500ms total could be 20ms Gemini API + 480ms pgvector
+ *     → Fix: add an index or reduce vector dimensions
+ *
+ * SCORE BUBBLING:
+ *   The `topScore` in the trace comes from results[0].similarity,
+ *   which is the cosine distance returned by SemanticSearchResult
+ *   (see src/storage/interface.ts L104-112). No storage layer
+ *   modifications were needed — the score was already there.
+ *
+ * MCP OUTPUT ARRAY:
+ *   content[0] = human-readable search results (unchanged)
+ *   content[1] = machine-readable MemoryTrace JSON (only when enable_trace=true)
+ *
+ * BACKWARD COMPATIBILITY:
+ *   When enable_trace is false (default), the response is byte-for-byte
+ *   identical to the pre-Phase 1 implementation. Zero breaking changes.
+ *   Existing tests pass without modification.
+ * ═══════════════════════════════════════════════════════════════════
  */
 export async function sessionSearchMemoryHandler(args) {
     if (!isSessionSearchMemoryArgs(args)) {
         throw new Error("Invalid arguments for session_search_memory");
     }
-    const { query, project, limit = 5, similarity_threshold = 0.7, } = args;
+    const { query, project, limit = 5, similarity_threshold = 0.7, 
+    // Phase 1: enable_trace defaults to false for full backward compatibility.
+    // When true, a MemoryTrace JSON block is appended as content[1].
+    enable_trace = false, } = args;
     debugLog(`[session_search_memory] Semantic search: query="${query}", ` +
         `project=${project || "all"}, limit=${limit}, threshold=${similarity_threshold}`);
+    // Phase 1: Start total latency timer BEFORE any work (embedding + storage)
+    const totalStart = performance.now();
     // Step 1: Generate embedding for the search query
     if (!GOOGLE_API_KEY) {
         return {
@@ -603,6 +712,9 @@ export async function sessionSearchMemoryHandler(args) {
         };
     }
     let queryEmbedding;
+    // Phase 1: Start embedding latency timer — isolates Gemini API call time.
+    // This is the most variable component: 50ms on a good day, 2000ms under load.
+    const embeddingStart = performance.now();
     try {
         queryEmbedding = await generateEmbedding(query);
     }
@@ -616,9 +728,15 @@ export async function sessionSearchMemoryHandler(args) {
             isError: true,
         };
     }
+    // Phase 1: Capture embedding API latency
+    const embeddingMs = performance.now() - embeddingStart;
     // Step 2: Search via storage backend
     try {
         const storage = await getStorage();
+        // Phase 1: Start storage latency timer — isolates DB query time.
+        // For Supabase: this measures the pgvector cosine distance RPC call.
+        // For SQLite: this measures the local sqlite-vec similarity search.
+        const storageStart = performance.now();
         const results = await storage.searchMemory({
             queryEmbedding: JSON.stringify(queryEmbedding),
             project: project || null,
@@ -626,20 +744,38 @@ export async function sessionSearchMemoryHandler(args) {
             similarityThreshold: similarity_threshold,
             userId: PRISM_USER_ID,
         });
+        // Phase 1: Capture storage query latency and compute total
+        const storageMs = performance.now() - storageStart;
+        const totalMs = performance.now() - totalStart;
         if (results.length === 0) {
-            return {
-                content: [{
-                        type: "text",
-                        text: `🔍 No semantically similar sessions found for: "${query}"\n` +
-                            (project ? `Project: ${project}\n` : "") +
-                            `Similarity threshold: ${similarity_threshold}\n\n` +
-                            `Tips:\n` +
-                            `• Lower the similarity_threshold (e.g., 0.5) for broader results\n` +
-                            `• Try knowledge_search for keyword-based matching\n` +
-                            `• Ensure sessions have been saved with embeddings (requires GOOGLE_API_KEY)`,
-                    }],
-                isError: false,
-            };
+            // Phase 1: Use contentBlocks array so we can optionally push trace at [1]
+            const contentBlocks = [{
+                    type: "text",
+                    text: `🔍 No semantically similar sessions found for: "${query}"\n` +
+                        (project ? `Project: ${project}\n` : "") +
+                        `Similarity threshold: ${similarity_threshold}\n\n` +
+                        `Tips:\n` +
+                        `• Lower the similarity_threshold (e.g., 0.5) for broader results\n` +
+                        `• Try knowledge_search for keyword-based matching\n` +
+                        `• Ensure sessions have been saved with embeddings (requires GOOGLE_API_KEY)`,
+                }];
+            // Phase 1: Trace is still valuable on empty results — it proves the search
+            // executed and reveals whether the bottleneck was embedding or storage.
+            if (enable_trace) {
+                const trace = createMemoryTrace({
+                    strategy: "semantic",
+                    query,
+                    resultCount: 0,
+                    topScore: null, // no results = no top score
+                    threshold: similarity_threshold,
+                    embeddingMs,
+                    storageMs,
+                    totalMs,
+                    project: project || null,
+                });
+                contentBlocks.push(traceToContentBlock(trace));
+            }
+            return { content: contentBlocks, isError: false };
         }
         // Format results with similarity scores
         const formatted = results.map((r, i) => {
@@ -652,13 +788,33 @@ export async function sessionSearchMemoryHandler(args) {
                 (r.decisions?.length ? `  Decisions: ${r.decisions.join("; ")}\n` : "") +
                 (r.files_changed?.length ? `  Files: ${r.files_changed.join(", ")}\n` : "");
         }).join("\n");
-        return {
-            content: [{
-                    type: "text",
-                    text: `🧠 Found ${results.length} semantically similar sessions:\n\n${formatted}`,
-                }],
-            isError: false,
-        };
+        // Phase 1: content[0] = human-readable results (unchanged from pre-Phase 1)
+        const contentBlocks = [{
+                type: "text",
+                text: `🧠 Found ${results.length} semantically similar sessions:\n\n${formatted}`,
+            }];
+        // Phase 1: content[1] = machine-readable MemoryTrace (only when enable_trace=true)
+        // topScore is read from results[0].similarity — this is the cosine distance
+        // already returned by SemanticSearchResult in the storage interface.
+        // No storage layer modifications were needed ("Score Bubbling" reviewer level-up).
+        if (enable_trace) {
+            const topScore = results.length > 0 && typeof results[0].similarity === "number"
+                ? results[0].similarity
+                : null;
+            const trace = createMemoryTrace({
+                strategy: "semantic",
+                query,
+                resultCount: results.length,
+                topScore,
+                threshold: similarity_threshold,
+                embeddingMs,
+                storageMs,
+                totalMs,
+                project: project || null,
+            });
+            contentBlocks.push(traceToContentBlock(trace));
+        }
+        return { content: contentBlocks, isError: false };
     }
     catch (err) {
         const errorMsg = err instanceof Error ? err.message : String(err);
@@ -1194,3 +1350,90 @@ export async function sessionHealthCheckHandler(args) {
         };
     }
 }
+// ═══════════════════════════════════════════════════════════════
+// Phase 2: GDPR-Compliant Memory Deletion Handler
+// ═══════════════════════════════════════════════════════════════
+//
+// This handler implements the session_forget_memory MCP tool.
+// It provides SURGICAL deletion of individual memory entries by ID,
+// supporting both soft-delete (tombstoning) and hard-delete (physical removal).
+//
+// WHY THIS IS SEPARATE FROM knowledgeForgetHandler:
+//   knowledgeForgetHandler operates on BULK criteria (project, category, age).
+//   sessionForgetMemoryHandler operates on a SINGLE entry by ID.
+//   This surgical approach is required for GDPR Article 17 compliance,
+//   where a data subject requests deletion of specific personal data.
+//
+// THE TOP-K HOLE PROBLEM (Solved):
+//   Without deleted_at filtering inside the database queries (both SQL and RPCs),
+//   a LIMIT 5 query might return 5 rows where 4 are soft-deleted. Post-filtering
+//   in TypeScript would strip them, leaving only 1 result. This destroys the
+//   agent's recall capability. By adding "AND deleted_at IS NULL" to ALL
+//   search queries (done in sqlite.ts and Supabase RPCs), the filtering
+//   happens BEFORE the LIMIT is applied, guaranteeing full Top-K results.
+// ═══════════════════════════════════════════════════════════════
+export async function sessionForgetMemoryHandler(args) {
+    try {
+        // ─── Input Validation ───
+        if (!isSessionForgetMemoryArgs(args)) {
+            return {
+                content: [{
+                        type: "text",
+                        text: "Invalid arguments. Required: memory_id (string). Optional: hard_delete (boolean), reason (string).",
+                    }],
+                isError: true,
+            };
+        }
+        const { memory_id, hard_delete = false, reason } = args;
+        // ─── Get Storage Backend ───
+        const storage = await getStorage();
+        // ─── Execute Deletion ───
+        // The storage methods verify user_id ownership internally,
+        // preventing cross-user deletion attacks.
+        if (hard_delete) {
+            // IRREVERSIBLE: Physical removal from the database.
+            // FTS5 triggers (SQLite) or Supabase cascades clean up indexes.
+            await storage.hardDeleteLedger(memory_id, PRISM_USER_ID);
+            debugLog(`[session_forget_memory] Hard-deleted entry ${memory_id}`);
+            return {
+                content: [{
+                        type: "text",
+                        text: `🗑️ **Hard Deleted** memory entry \`${memory_id}\`.\n\n` +
+                            `This entry has been permanently removed from the database. ` +
+                            `It cannot be recovered. All associated embeddings and FTS indexes ` +
+                            `have been cleaned up.`,
+                    }],
+                isError: false,
+            };
+        }
+        else {
+            // REVERSIBLE: Soft-delete (tombstone) — sets deleted_at + deleted_reason.
+            // The entry remains in the database but is excluded from ALL search
+            // queries (vector, FTS5, and context loading).
+            await storage.softDeleteLedger(memory_id, PRISM_USER_ID, reason);
+            debugLog(`[session_forget_memory] Soft-deleted entry ${memory_id} (reason: ${reason || "none"})`);
+            return {
+                content: [{
+                        type: "text",
+                        text: `🔇 **Soft Deleted** memory entry \`${memory_id}\`.\n\n` +
+                            `The entry has been tombstoned (deleted_at = NOW()). ` +
+                            `It will no longer appear in any search results, but remains ` +
+                            `in the database for audit trail purposes.\n\n` +
+                            (reason ? `📋 **Reason**: ${reason}\n\n` : "") +
+                            `To permanently remove this entry, call again with \`hard_delete: true\`.`,
+                    }],
+                isError: false,
+            };
+        }
+    }
+    catch (error) {
+        console.error(`[session_forget_memory] Error: ${error}`);
+        return {
+            content: [{
+                    type: "text",
+                    text: `Error forgetting memory: ${error instanceof Error ? error.message : String(error)}`,
+                }],
+            isError: true,
+        };
+    }
+}

package/dist/utils/embeddingApi.js

@@ -85,13 +85,20 @@ export async function generateEmbedding(text) {
     const model = genAI.getGenerativeModel({ model: "gemini-embedding-001" }, { apiVersion: "v1beta" } // gemini-embedding-001 requires v1beta
     );
     debugLog(`[embedding] Generating 768-dim embedding for ${inputText.length} chars`);
-    const result = await model.embedContent({
+    const request = {
         content: {
             role: "user",
             parts: [{ text: inputText }],
         },
         taskType: TaskType.SEMANTIC_SIMILARITY,
-        outputDimensionality: 768,
-    });
-    return result.embedding.values;
+        // SDK runtime supports this for gemini-embedding-001 even when older
+        // type defs may lag; keep cast localized at request boundary.
+        ...{ outputDimensionality: 768 },
+    };
+    const result = await model.embedContent(request);
+    const values = result.embedding.values;
+    if (!Array.isArray(values) || values.length !== 768) {
+        throw new Error(`Embedding dimension mismatch: expected 768, got ${values?.length ?? 'unknown'}`);
+    }
+    return values;
 }

package/dist/utils/tracing.js

@@ -0,0 +1,139 @@
+/**
+ * Memory Trace — Phase 1 Explainability & Lineage
+ *
+ * ═══════════════════════════════════════════════════════════════════
+ * PURPOSE:
+ *   Provides structured tracing metadata for every search/recall
+ *   operation in Prism MCP. When `enable_trace: true` is passed to
+ *   `session_search_memory` or `knowledge_search`, the response
+ *   includes a separate MCP content block with a MemoryTrace object.
+ *
+ * WHY THIS EXISTS:
+ *   Without tracing, developers have no visibility into *why* a
+ *   memory was returned — was it a semantic match? A keyword hit?
+ *   How confident was the score? Was the 500ms latency caused by
+ *   the embedding API or the database query?
+ *
+ *   This module answers all of those questions by providing:
+ *   - strategy: "semantic" | "keyword" → which search path was used
+ *   - top_score: the cosine similarity / relevance score of the best result
+ *   - latency: { embedding_ms, storage_ms, total_ms } → pinpoints bottlenecks
+ *   - result_count, threshold, project, query, timestamp → full context
+ *
+ * DESIGN DECISIONS:
+ *
+ *   1. NO OPENTELEMETRY SDK IN PHASE 1
+ *      We get the data structures right in-memory first. OTel
+ *      integration (W3C traceparent headers, span export to
+ *      Datadog/LangSmith) layers on top in a follow-up without
+ *      any code changes to the MemoryTrace types.
+ *
+ *   2. SEPARATE MCP CONTENT BLOCK (The "Output Array Trick")
+ *      Instead of concatenating trace JSON into the human-readable
+ *      text response (content[0]), we return it as content[1].
+ *
+ *      Why?
+ *      - Prevents LLMs from accidentally blending trace JSON into
+ *        their reasoning (they sometimes try to "interpret" inline JSON)
+ *      - Programmatic MCP clients can grab content[1] directly
+ *        without parsing/splitting string output
+ *      - Clean separation of concerns: content[0] = human-readable,
+ *        content[1] = machine-readable trace metadata
+ *
+ *   3. LATENCY BREAKDOWN (Not just total)
+ *      A single `latency_ms` number is misleading. A 500ms total could
+ *      be 480ms embedding API + 20ms DB, or 20ms embedding + 480ms DB.
+ *      These are very different problems requiring different fixes.
+ *
+ *      We capture three timestamps:
+ *        - Before embedding API call → after = embedding_ms
+ *        - Before storage.searchMemory() → after = storage_ms
+ *        - Start to finish = total_ms (includes overhead, serialization, etc.)
+ *
+ *   4. SCORE BUBBLING (No storage layer changes needed)
+ *      The existing SemanticSearchResult interface (interface.ts L104-112)
+ *      already includes `similarity: number`. We read this directly from
+ *      results[0].similarity — no modifications to the storage layer.
+ *      For keyword search, top_score is null since keyword search doesn't
+ *      return relevance scores in the current implementation.
+ *
+ *   5. BACKWARD COMPATIBILITY
+ *      When `enable_trace` is not set (default: false), the response
+ *      is identical to pre-Phase 1 output. Zero breaking changes.
+ *      Existing tests pass without modification.
+ *
+ * USAGE:
+ *   This module is imported by sessionMemoryHandlers.ts. It is NOT
+ *   imported by the storage layer, server.ts, or any other module.
+ *
+ * FILES THAT IMPORT THIS:
+ *   - src/tools/sessionMemoryHandlers.ts (search handlers)
+ *
+ * RELATED FILES:
+ *   - src/tools/sessionMemoryDefinitions.ts (enable_trace param definition)
+ *   - src/storage/interface.ts (SemanticSearchResult with similarity score)
+ *
+ * FUTURE EXTENSIONS (Phase 1.5+):
+ *   - Add OpenTelemetry span creation using these same trace objects
+ *   - Add `reranked_score` field when re-ranking is implemented
+ *   - Add `graph_hops` field when graph-based recall is added
+ *   - Add PII sanitization flags for GDPR-strict deployments
+ * ═══════════════════════════════════════════════════════════════════
+ */
+// ─── Factory ──────────────────────────────────────────────────
+/**
+ * Create a MemoryTrace object from search operation metrics.
+ *
+ * This is a pure factory function — no side effects, no I/O.
+ * Called by the search handlers after both the embedding API call
+ * and storage query have completed.
+ *
+ * Latency values are rounded to nearest integer for cleaner output
+ * (sub-millisecond precision is noise, not signal).
+ *
+ * @param params.strategy      - "semantic" or "keyword"
+ * @param params.query         - Original search query string
+ * @param params.resultCount   - Number of results returned
+ * @param params.topScore      - Best similarity score, or null for keyword
+ * @param params.threshold     - Threshold used, or null for keyword
+ * @param params.embeddingMs   - Time for embedding API call (0 for keyword)
+ * @param params.storageMs     - Time for database query
+ * @param params.totalMs       - Total end-to-end time
+ * @param params.project       - Project filter, or null for all
+ * @returns A complete MemoryTrace object ready for serialization
+ */
+export function createMemoryTrace(params) {
+    return {
+        strategy: params.strategy,
+        query: params.query,
+        result_count: params.resultCount,
+        top_score: params.topScore,
+        threshold: params.threshold,
+        latency: {
+            embedding_ms: Math.round(params.embeddingMs),
+            storage_ms: Math.round(params.storageMs),
+            total_ms: Math.round(params.totalMs),
+        },
+        timestamp: new Date().toISOString(),
+        project: params.project,
+    };
+}
+/**
+ * Format a MemoryTrace into an MCP content block.
+ *
+ * Returns a single content block to push into the content[] array
+ * at index [1]. The "=== MEMORY TRACE ===" header makes it visually
+ * distinct from the human-readable search results at content[0].
+ *
+ * The trace is pretty-printed (2-space indent) for readability in
+ * console output and MCP inspector tools.
+ *
+ * @param trace - A MemoryTrace object from createMemoryTrace()
+ * @returns An MCP content block: { type: "text", text: "..." }
+ */
+export function traceToContentBlock(trace) {
+    return {
+        type: "text",
+        text: `=== MEMORY TRACE ===\n${JSON.stringify(trace, null, 2)}`,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prism-mcp-server",
-  "version": "2.3.12",
+  "version": "2.5.1",
   "mcpName": "io.github.dcostenco/prism-mcp",
   "description": "The Mind Palace for AI Agents — local-first MCP server with persistent memory (SQLite/Supabase), visual dashboard, time travel, multi-agent sync, Morning Briefings, reality drift detection, code mode templates, semantic vector search, and Brave Search + Gemini analysis. Zero-config local mode.",
   "module": "index.ts",