prism-mcp-server 2.3.12 → 2.5.1

package/dist/storage/sqlite.js

@@ -152,6 +152,36 @@ export class SqliteStorage {
       CREATE INDEX IF NOT EXISTS idx_history_version
         ON session_handoffs_history(project, version);
     `);
+        // ─── Phase 2 Migration: GDPR Soft Delete Columns ──────────
+        //
+        // SQLITE GOTCHA: Unlike CREATE TABLE IF NOT EXISTS, ALTER TABLE
+        // throws a fatal error if the column already exists. We MUST
+        // wrap each ALTER TABLE in a try/catch and only ignore
+        // "duplicate column name" errors.
+        //
+        // This migration runs on every boot but is idempotent — the
+        // try/catch ensures it's safe to run repeatedly.
+        try {
+            await this.db.execute(`ALTER TABLE session_ledger ADD COLUMN deleted_at TEXT DEFAULT NULL`);
+            debugLog("[SqliteStorage] Phase 2 migration: added deleted_at column");
+        }
+        catch (e) {
+            // "duplicate column name" = column already exists from prior boot.
+            // Any other error is a real problem — rethrow it.
+            if (!e.message?.includes("duplicate column name"))
+                throw e;
+        }
+        try {
+            await this.db.execute(`ALTER TABLE session_ledger ADD COLUMN deleted_reason TEXT DEFAULT NULL`);
+            debugLog("[SqliteStorage] Phase 2 migration: added deleted_reason column");
+        }
+        catch (e) {
+            if (!e.message?.includes("duplicate column name"))
+                throw e;
+        }
+        // Index for fast WHERE deleted_at IS NULL queries.
+        // CREATE INDEX IF NOT EXISTS is safe to run repeatedly (no try/catch needed).
+        await this.db.execute(`CREATE INDEX IF NOT EXISTS idx_ledger_deleted ON session_ledger(deleted_at)`);
     }
     // ─── PostgREST Filter Parser ───────────────────────────────
     //
@@ -341,6 +371,37 @@ export class SqliteStorage {
         });
         return entries;
     }
+    // ─── Phase 2: GDPR-Compliant Memory Deletion ──────────────
+    //
+    // These methods are SURGICAL — they operate on a single entry by ID.
+    // They MUST verify user_id ownership to prevent cross-user deletion.
+    //
+    // softDeleteLedger: Sets deleted_at + deleted_reason. Entry stays in
+    //   DB for audit trail. All search queries filter it out via
+    //   "AND deleted_at IS NULL". Reversible.
+    //
+    // hardDeleteLedger: Physical DELETE. Irreversible. FTS5 triggers
+    //   automatically clean up the full-text index.
+    async softDeleteLedger(id, userId, reason) {
+        // UPDATE (not DELETE): sets tombstone fields while preserving the row.
+        // The JS-side datetime('now') matches SQLite's native format.
+        await this.db.execute({
+            sql: `UPDATE session_ledger
+            SET deleted_at = datetime('now'), deleted_reason = ?
+            WHERE id = ? AND user_id = ?`,
+            args: [reason || null, id, userId],
+        });
+        debugLog(`[SqliteStorage] Soft-deleted ledger entry ${id} (reason: ${reason || "none"})`);
+    }
+    async hardDeleteLedger(id, userId) {
+        // Physical DELETE — row is permanently removed.
+        // FTS5 trigger (ledger_fts_delete) automatically cleans up the index.
+        await this.db.execute({
+            sql: `DELETE FROM session_ledger WHERE id = ? AND user_id = ?`,
+            args: [id, userId],
+        });
+        debugLog(`[SqliteStorage] Hard-deleted ledger entry ${id}`);
+    }
     // ─── Handoff Operations (OCC) ──────────────────────────────
     async saveHandoff(handoff, expectedVersion) {
         // CASE 1: No expectedVersion → UPSERT (create or force-update)
@@ -471,10 +532,11 @@ export class SqliteStorage {
         context.key_context = handoff.key_context;
         if (level === "standard") {
             // Add recent ledger entries as summaries
+            // Phase 2: AND deleted_at IS NULL — exclude soft-deleted entries
             const recentLedger = await this.db.execute({
                 sql: `SELECT summary, decisions, session_date, created_at
               FROM session_ledger
-              WHERE project = ? AND user_id = ? AND archived_at IS NULL
+              WHERE project = ? AND user_id = ? AND archived_at IS NULL AND deleted_at IS NULL
               ORDER BY created_at DESC
               LIMIT 5`,
                 args: [project, userId],
@@ -487,10 +549,11 @@ export class SqliteStorage {
             return context;
         }
         // Deep: add full session history
+        // Phase 2: AND deleted_at IS NULL — exclude soft-deleted entries
         const fullLedger = await this.db.execute({
             sql: `SELECT summary, decisions, files_changed, todos, session_date, created_at
             FROM session_ledger
-            WHERE project = ? AND user_id = ? AND archived_at IS NULL
+            WHERE project = ? AND user_id = ? AND archived_at IS NULL AND deleted_at IS NULL
             ORDER BY created_at DESC
             LIMIT 50`,
             args: [project, userId],
@@ -529,6 +592,7 @@ export class SqliteStorage {
           AND l.project = ?
           AND l.user_id = ?
           AND l.archived_at IS NULL
+          AND l.deleted_at IS NULL
         ORDER BY rank
         LIMIT ?
       `;
@@ -544,6 +608,7 @@ export class SqliteStorage {
         WHERE ledger_fts MATCH ?
           AND l.user_id = ?
           AND l.archived_at IS NULL
+          AND l.deleted_at IS NULL
         ORDER BY rank
         LIMIT ?
       `;
@@ -573,7 +638,7 @@ export class SqliteStorage {
     }
     /** Fallback search using LIKE when FTS5 query syntax fails */
     async searchKnowledgeFallback(params) {
-        const conditions = ["user_id = ?", "archived_at IS NULL"];
+        const conditions = ["user_id = ?", "archived_at IS NULL", "deleted_at IS NULL"];
         const args = [params.userId];
         if (params.project) {
             conditions.push("project = ?");
@@ -626,6 +691,7 @@ export class SqliteStorage {
             AND l.user_id = ?
             AND l.project = ?
             AND l.archived_at IS NULL
+            AND l.deleted_at IS NULL
           ORDER BY similarity DESC
           LIMIT ?
         `;
@@ -640,6 +706,7 @@ export class SqliteStorage {
           WHERE l.embedding IS NOT NULL
             AND l.user_id = ?
             AND l.archived_at IS NULL
+            AND l.deleted_at IS NULL
           ORDER BY similarity DESC
           LIMIT ?
         `;

package/dist/storage/supabase.js

@@ -67,6 +67,41 @@ export class SupabaseStorage {
         const result = await supabaseDelete("session_ledger", params);
         return Array.isArray(result) ? result : [];
     }
+    // ─── Phase 2: GDPR-Compliant Memory Deletion ──────────────
+    //
+    // These methods are SURGICAL — they operate on a single entry by ID.
+    // They MUST verify user_id ownership to prevent cross-user deletion.
+    //
+    // softDeleteLedger: Sets deleted_at + deleted_reason. Entry stays in
+    //   DB for audit trail. Supabase RPCs and TypeScript queries filter
+    //   it out via "WHERE deleted_at IS NULL". Reversible.
+    //
+    // hardDeleteLedger: Physical DELETE. Irreversible. For GDPR Article 17
+    //   "right to erasure" when the audit trail must also be removed.
+    async softDeleteLedger(id, userId, reason) {
+        // PATCH (not DELETE): sets tombstone fields while preserving the row.
+        // The deleted_at timestamp is set server-side for consistency.
+        // deleted_reason captures the GDPR justification (e.g., "User requested",
+        // "Data retention policy", "GDPR Article 17 request").
+        await supabasePatch("session_ledger", {
+            deleted_at: new Date().toISOString(),
+            deleted_reason: reason || null,
+        }, {
+            id: `eq.${id}`,
+            user_id: `eq.${userId}`, // Ownership guard — prevents cross-user deletion
+        });
+        debugLog(`[SupabaseStorage] Soft-deleted ledger entry ${id} (reason: ${reason || "none"})`);
+    }
+    async hardDeleteLedger(id, userId) {
+        // Physical DELETE — row is permanently removed from the database.
+        // This is irreversible. The FTS5 index (if any) is cleaned up by
+        // Supabase's built-in trigger handling.
+        await supabaseDelete("session_ledger", {
+            id: `eq.${id}`,
+            user_id: `eq.${userId}`, // Ownership guard
+        });
+        debugLog(`[SupabaseStorage] Hard-deleted ledger entry ${id}`);
+    }
     // ─── Handoff Operations ────────────────────────────────────
     async saveHandoff(handoff, expectedVersion) {
         // Direct mapping from sessionSaveHandoffHandler line 214

package/dist/tools/index.js

@@ -26,8 +26,8 @@ export { webSearchHandler, braveWebSearchCodeModeHandler, localSearchHandler, br
 // This file always exports them — server.ts decides whether to include them in the tool list.
 //
 // v0.4.0: Added SESSION_COMPACT_LEDGER_TOOL and SESSION_SEARCH_MEMORY_TOOL
-export { SESSION_SAVE_LEDGER_TOOL, SESSION_SAVE_HANDOFF_TOOL, SESSION_LOAD_CONTEXT_TOOL, KNOWLEDGE_SEARCH_TOOL, KNOWLEDGE_FORGET_TOOL, SESSION_COMPACT_LEDGER_TOOL, SESSION_SEARCH_MEMORY_TOOL, MEMORY_HISTORY_TOOL, MEMORY_CHECKOUT_TOOL, SESSION_SAVE_IMAGE_TOOL, SESSION_VIEW_IMAGE_TOOL, SESSION_HEALTH_CHECK_TOOL } from "./sessionMemoryDefinitions.js";
-export { sessionSaveLedgerHandler, sessionSaveHandoffHandler, sessionLoadContextHandler, knowledgeSearchHandler, knowledgeForgetHandler, sessionSearchMemoryHandler, backfillEmbeddingsHandler, memoryHistoryHandler, memoryCheckoutHandler, sessionSaveImageHandler, sessionViewImageHandler, sessionHealthCheckHandler } from "./sessionMemoryHandlers.js";
+export { SESSION_SAVE_LEDGER_TOOL, SESSION_SAVE_HANDOFF_TOOL, SESSION_LOAD_CONTEXT_TOOL, KNOWLEDGE_SEARCH_TOOL, KNOWLEDGE_FORGET_TOOL, SESSION_COMPACT_LEDGER_TOOL, SESSION_SEARCH_MEMORY_TOOL, MEMORY_HISTORY_TOOL, MEMORY_CHECKOUT_TOOL, SESSION_SAVE_IMAGE_TOOL, SESSION_VIEW_IMAGE_TOOL, SESSION_HEALTH_CHECK_TOOL, SESSION_FORGET_MEMORY_TOOL } from "./sessionMemoryDefinitions.js";
+export { sessionSaveLedgerHandler, sessionSaveHandoffHandler, sessionLoadContextHandler, knowledgeSearchHandler, knowledgeForgetHandler, sessionSearchMemoryHandler, backfillEmbeddingsHandler, memoryHistoryHandler, memoryCheckoutHandler, sessionSaveImageHandler, sessionViewImageHandler, sessionHealthCheckHandler, sessionForgetMemoryHandler } from "./sessionMemoryHandlers.js";
 // ── Compaction Handler (v0.4.0 — Enhancement #2) ──
 // The compaction handler is in a separate file because it's significantly
 // more complex than the other session memory handlers (chunked Gemini

package/dist/tools/sessionMemoryDefinitions.js

@@ -114,6 +114,10 @@ export const SESSION_LOAD_CONTEXT_TOOL = {
     },
 };
 // ─── Knowledge Search ─────────────────────────────────────────
+// Phase 1 Change: Added `enable_trace` optional boolean.
+// When true, the handler returns a separate content[1] block with a
+// MemoryTrace object (strategy="keyword", latency, result metadata).
+// Default: false — output is identical to pre-Phase 1 behavior.
 export const KNOWLEDGE_SEARCH_TOOL = {
     name: "knowledge_search",
     description: "Search accumulated knowledge across all sessions by keywords, category, or free text. " +
@@ -144,6 +148,14 @@ export const KNOWLEDGE_SEARCH_TOOL = {
                 description: "Maximum results to return (default: 10, max: 50).",
                 default: 10,
             },
+            // Phase 1: Explainability — when true, appends a MemoryTrace JSON
+            // object as content[1] in the response array.
+            // MCP clients can parse content[1] programmatically for debugging.
+            enable_trace: {
+                type: "boolean",
+                description: "If true, returns a separate MEMORY TRACE content block with search strategy, " +
+                    "latency breakdown, and scoring metadata for explainability. Default: false.",
+            },
         },
     },
 };
@@ -265,6 +277,15 @@ export const SESSION_SEARCH_MEMORY_TOOL = {
                 description: "Minimum similarity score 0-1 (default: 0.7). Higher = more relevant, fewer results.",
                 default: 0.7,
             },
+            // Phase 1: Explainability — when true, appends a MemoryTrace JSON
+            // object as content[1] in the response array. For semantic search,
+            // the trace includes embedding_ms (Gemini API time) vs storage_ms
+            // (pgvector query time) to pinpoint performance bottlenecks.
+            enable_trace: {
+                type: "boolean",
+                description: "If true, returns a separate MEMORY TRACE content block with search strategy, " +
+                    "latency breakdown (embedding vs storage), and scoring metadata. Default: false.",
+            },
         },
         required: ["query"],
     },
@@ -306,6 +327,9 @@ export const SESSION_BACKFILL_EMBEDDINGS_TOOL = {
 export function isKnowledgeForgetArgs(args) {
     return typeof args === "object" && args !== null;
 }
+// Phase 1: Added enable_trace to the type guard.
+// Optional boolean — when true, the handler returns a MemoryTrace content block.
+// Default: false, so existing callers see no change in behavior.
 export function isKnowledgeSearchArgs(args) {
     return typeof args === "object" && args !== null;
 }
@@ -328,6 +352,9 @@ export function isSessionSaveHandoffArgs(args) {
         typeof args.project === "string");
 }
 // ─── v0.4.0: Type guard for semantic search ──────────────────
+// Phase 1: Added enable_trace to the type guard.
+// Optional boolean — when true, a MemoryTrace block (with embedding_ms,
+// storage_ms, top_score, etc.) is appended as content[1] in the response.
 export function isSessionSearchMemoryArgs(args) {
     return (typeof args === "object" &&
         args !== null &&
@@ -500,3 +527,64 @@ export const SESSION_HEALTH_CHECK_TOOL = {
 export function isSessionHealthCheckArgs(args) {
     return typeof args === "object" && args !== null; // any object is valid
 }
+// ─── Phase 2: GDPR-Compliant Memory Deletion Tool ────────────
+//
+// This tool enables SURGICAL deletion of individual memory entries by ID.
+// It supports two modes:
+//   1. Soft Delete (default): Sets deleted_at = NOW(). The entry remains
+//      in the database for audit trails but is excluded from ALL search
+//      queries (both FTS5 and vector). This prevents the Top-K Hole
+//      problem where LIMIT N queries return fewer results than expected.
+//   2. Hard Delete: Physical removal from the database. Irreversible.
+//      Use only when GDPR Article 17 requires complete erasure.
+//
+// DESIGN DECISION: This is intentionally separate from knowledge_forget,
+// which operates on bulk filter criteria (project, category, age).
+// session_forget_memory is surgical — one entry at a time — for
+// precise GDPR compliance.
+export const SESSION_FORGET_MEMORY_TOOL = {
+    name: "session_forget_memory",
+    description: "Forget (delete) a specific memory entry by its ID. " +
+        "Supports two modes:\n\n" +
+        "- **Soft delete** (default): Tombstones the entry — it stays in the database " +
+        "for audit trails but is excluded from all search results. Reversible.\n" +
+        "- **Hard delete**: Permanently removes the entry from the database. Irreversible. " +
+        "Use only when GDPR Article 17 requires complete erasure.\n\n" +
+        "⚠️ Soft delete is recommended for most use cases. The entry can be " +
+        "restored in the future if needed.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            memory_id: {
+                type: "string",
+                description: "The UUID of the memory (ledger) entry to forget. " +
+                    "You can find this ID in search results returned by " +
+                    "session_search_memory or knowledge_search.",
+            },
+            hard_delete: {
+                type: "boolean",
+                description: "If true, permanently removes the entry (irreversible). " +
+                    "If false (default), soft-deletes by setting deleted_at timestamp. " +
+                    "Soft-deleted entries are excluded from searches but remain in the database.",
+            },
+            reason: {
+                type: "string",
+                description: "Optional GDPR Article 17 justification for the deletion. " +
+                    "Examples: 'User requested', 'Data retention policy', 'Outdated information'. " +
+                    "Stored alongside the tombstone for audit trail purposes.",
+            },
+        },
+        required: ["memory_id"],
+    },
+};
+/**
+ * Type guard for session_forget_memory arguments.
+ * Validates that memory_id (required) is present and is a string.
+ * hard_delete and reason are optional.
+ */
+export function isSessionForgetMemoryArgs(args) {
+    return (typeof args === "object" &&
+        args !== null &&
+        "memory_id" in args &&
+        typeof args.memory_id === "string");
+}