prism-mcp-server 3.0.1 → 3.1.0

package/dist/server.js

@@ -68,6 +68,7 @@ import { startDashboardServer } from "./dashboard/server.js";
 // error wrapper. Now uses getStorage() which routes through the
 // correct backend (Supabase or SQLite) with proper error handling.
 import { getStorage } from "./storage/index.js";
+import { getSettingSync, initConfigStorage } from "./storage/configStorage.js";
 // ─── Import Tool Definitions (schemas) and Handlers (implementations) ─────
 import { WEB_SEARCH_TOOL, BRAVE_WEB_SEARCH_CODE_MODE_TOOL, LOCAL_SEARCH_TOOL, BRAVE_LOCAL_SEARCH_CODE_MODE_TOOL, CODE_MODE_TRANSFORM_TOOL, BRAVE_ANSWERS_TOOL, RESEARCH_PAPER_ANALYSIS_TOOL, webSearchHandler, braveWebSearchCodeModeHandler, localSearchHandler, braveLocalSearchCodeModeHandler, codeModeTransformHandler, braveAnswersHandler, researchPaperAnalysisHandler, } from "./tools/index.js";
 // Session memory tools — only used if Supabase is configured
@@ -81,7 +82,9 @@ SESSION_SAVE_IMAGE_TOOL, SESSION_VIEW_IMAGE_TOOL,
 // ─── v2.2.0: Health Check tool definition ───
 SESSION_HEALTH_CHECK_TOOL, 
 // ─── Phase 2: GDPR Memory Deletion tool definition ───
-SESSION_FORGET_MEMORY_TOOL, sessionSaveLedgerHandler, sessionSaveHandoffHandler, sessionLoadContextHandler, knowledgeSearchHandler, knowledgeForgetHandler, 
+SESSION_FORGET_MEMORY_TOOL, 
+// ─── v3.1: TTL Retention tool ───
+KNOWLEDGE_SET_RETENTION_TOOL, sessionSaveLedgerHandler, sessionSaveHandoffHandler, sessionLoadContextHandler, knowledgeSearchHandler, knowledgeForgetHandler, 
 // ─── v0.4.0: New tool handlers ───
 compactLedgerHandler, sessionSearchMemoryHandler, 
 // ─── v2.0: Time Travel handlers ───
@@ -92,6 +95,8 @@ sessionSaveImageHandler, sessionViewImageHandler,
 sessionHealthCheckHandler, 
 // ─── Phase 2: GDPR Memory Deletion handler ───
 sessionForgetMemoryHandler, 
+// ─── v3.1: TTL Retention handler ───
+knowledgeSetRetentionHandler, 
 // ─── v3.0: Agent Hivemind tools ───
 AGENT_REGISTRY_TOOLS, agentRegisterHandler, agentHeartbeatHandler, agentListTeamHandler, } from "./tools/index.js";
 // ─── Dynamic Tool Registration ───────────────────────────────────
@@ -126,6 +131,8 @@ const SESSION_MEMORY_TOOLS = [
     SESSION_HEALTH_CHECK_TOOL, // session_health_check — brain integrity checker (v2.2.0)
     // ─── Phase 2: GDPR Memory Deletion tool ───
     SESSION_FORGET_MEMORY_TOOL, // session_forget_memory — GDPR-compliant memory deletion (Phase 2)
+    // ─── v3.1: TTL Retention tool ───
+    KNOWLEDGE_SET_RETENTION_TOOL, // knowledge_set_retention — set auto-expiry TTL for a project
 ];
 // Combine: always list ALL tools so scanners (Glama, Smithery, MCP Registry)
 // can enumerate the full capability set. Runtime guards in the CallTool handler
@@ -146,6 +153,11 @@ const ALL_TOOLS = [
 // This is a simple in-memory set. If the server restarts, clients
 // will re-subscribe on reconnect (per MCP spec behavior).
 const activeSubscriptions = new Set();
+// Module-level promise for the async storage pre-warm fired in startServer().
+// Resource handlers check storageIsReady (synchronous) instead of awaiting
+// the promise, so they never block the MCP stdio pipe during startup.
+let storageReady = null;
+let storageIsReady = false;
 /**
  * Notifies subscribed clients that a resource has changed.
  *
@@ -260,6 +272,20 @@ export function createServer() {
             if (name !== "resume_session") {
                 throw new Error(`Unknown prompt: ${name}`);
             }
+            // Non-blocking: if storage isn't warm yet, return a fallback message
+            // instead of blocking the MCP stdio pipe during Supabase init.
+            if (!storageIsReady) {
+                const project = promptArgs?.project || "default";
+                return {
+                    messages: [{
+                            role: "user",
+                            content: {
+                                type: "text",
+                                text: `⏳ Storage is still initializing. Session context for "${project}" will be available shortly.\nUse the session_load_context tool to load context once ready.`,
+                            },
+                        }],
+                };
+            }
             const project = promptArgs?.project || "default";
             const level = promptArgs?.level || "standard";
             // v2.3.6 FIX: Use storage abstraction instead of direct supabaseRpc
@@ -330,9 +356,14 @@ export function createServer() {
         }));
         // List concrete resources — one per known project
         server.setRequestHandler(ListResourcesRequestSchema, async () => {
-            // v2.3.6 FIX: Use storage abstraction instead of direct supabaseGet
+            // Non-blocking: if storage isn't warm yet, return empty list instantly
+            // so the client UI isn't blocked during Supabase init (can take 1m+).
+            // Resources will appear on the next ListResources call once warm.
+            if (!storageIsReady) {
+                return { resources: [] };
+            }
             try {
-                const storage = await getStorage();
+                const storage = await getStorage(); // instant — singleton is warm
                 const projects = await storage.listProjects();
                 return {
                     resources: projects.map((p) => ({
@@ -357,8 +388,19 @@ export function createServer() {
                 throw new Error(`Unknown resource URI: ${uri}. Expected format: memory://{project}/handoff`);
             }
             const project = decodeURIComponent(match[1]);
+            // Non-blocking: if storage isn't warm yet, return a friendly fallback
+            // instead of blocking the client UI for 1m+ during Supabase init.
+            if (!storageIsReady) {
+                return {
+                    contents: [{
+                            uri,
+                            mimeType: "text/plain",
+                            text: `⏳ Storage is still initializing. Session context for "${project}" will be available shortly.\nUse the session_load_context tool to load context once ready.`,
+                        }],
+                };
+            }
             try {
-                const storage = await getStorage();
+                const storage = await getStorage(); // instant — singleton is warm
                 const data = await storage.loadContext(project, "standard", PRISM_USER_ID);
                 if (!data) {
                     return {
@@ -396,11 +438,25 @@ export function createServer() {
                     ? `\n\n🔑 Session version: ${version}. Pass expected_version: ${version} when saving handoff.\n` +
                         `_occ_instruction: When saving handoff state, you MUST pass expected_version: ${version} to prevent state collisions with other sessions.`
                     : "";
+                // ─── Agent Identity Block (mirrors session_load_context output) ───
+                const ROLE_ICONS = {
+                    dev: "🛠️", qa: "🔍", pm: "📋", lead: "🏗️",
+                    security: "🔒", ux: "🎨", global: "🌐", cmo: "📢",
+                };
+                const agentName = getSettingSync("agent_name", "");
+                const defaultRole = getSettingSync("default_role", "");
+                let identityBlock = "";
+                if (agentName || (defaultRole && defaultRole !== "global")) {
+                    const icon = ROLE_ICONS[defaultRole] || "🤖";
+                    const namePart = agentName ? `👋 **${agentName}**` : `👋 **Agent**`;
+                    const rolePart = defaultRole ? ` · Role: \`${defaultRole}\`` : "";
+                    identityBlock = `\n\n[👤 AGENT IDENTITY]\n${icon} ${namePart}${rolePart}`;
+                }
                 return {
                     contents: [{
                             uri,
                             mimeType: "text/plain",
-                            text: `📋 Session context for "${project}" (standard):\n\n${formattedContext.trim()}${versionNote}`,
+                            text: `📋 Session context for "${project}" (standard):\n\n${formattedContext.trim()}${identityBlock}${versionNote}`,
                         }],
                 };
             }
@@ -525,6 +581,11 @@ export function createServer() {
                     if (!SESSION_MEMORY_ENABLED)
                         throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
                     return await sessionForgetMemoryHandler(args);
+                // ─── v3.1: TTL Retention Tool ───
+                case "knowledge_set_retention":
+                    if (!SESSION_MEMORY_ENABLED)
+                        throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
+                    return await knowledgeSetRetentionHandler(args);
                 // ─── v3.0: Agent Hivemind Tools ───
                 case "agent_register":
                     if (!SESSION_MEMORY_ENABLED)
@@ -633,37 +694,70 @@ export function createSandboxServer() {
  * responses to stdout. Log messages go to stderr.
  */
 export async function startServer() {
+    // Pre-warm the config settings cache BEFORE connecting the MCP transport.
+    // This ensures getSettingSync() returns real values (agent_name, default_role)
+    // during the Initialize handshake — zero extra latency for resource reads.
+    // initConfigStorage() is local SQLite only (~5ms), safe to await.
+    await initConfigStorage();
     const server = createServer();
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    // ─── v2.0 Step 6: Initialize SyncBus (Telepathy) ───
+    // Pre-warm storage AFTER connecting — fired async so we never block the
+    // stdio handshake. Supabase REST initialization can take 500ms–5s; blocking
+    // on it before server.connect() was the root cause of the 1m 56s CLI delay.
+    // By the time the first real tool/resource call arrives, the singleton is warm.
     if (SESSION_MEMORY_ENABLED) {
-        try {
-            const syncBus = await getSyncBus();
-            await syncBus.startListening();
-            syncBus.on("update", (event) => {
-                // Send an MCP logging notification to the IDE
-                try {
-                    server.sendLoggingMessage({
-                        level: "info",
-                        data: `[Prism Telepathy] \u{1F9E0} Another agent just updated the memory for ` +
-                            `'${event.project}' to version ${event.version}. ` +
-                            `You may want to run session_load_context to sync up.`,
-                    });
-                }
-                catch (err) {
-                    console.error(`[Telepathy] Failed to send notification: ${err}`);
+        const STORAGE_TIMEOUT_MS = 10_000;
+        storageReady = Promise.race([
+            getStorage().then(() => { storageIsReady = true; }),
+            new Promise(resolve => setTimeout(() => {
+                if (!storageIsReady) {
+                    console.error(`[Prism] Storage pre-warm timed out after ${STORAGE_TIMEOUT_MS}ms (non-fatal)`);
                 }
-            });
-        }
-        catch (err) {
-            console.error(`[Telepathy] SyncBus init failed (non-fatal): ${err}`);
-        }
+                resolve();
+            }, STORAGE_TIMEOUT_MS)),
+        ]).catch(err => {
+            console.error(`[Prism] Storage pre-warm failed (non-fatal): ${err}`);
+        });
+    }
+    // ─── v2.0 Step 6: Initialize SyncBus (Telepathy) ───
+    // Fire-and-forget — SyncBus is non-critical for startup.
+    // Awaiting getSyncBus() + startListening() could block the event loop
+    // if Supabase Realtime is slow, delaying MCP request processing.
+    if (SESSION_MEMORY_ENABLED) {
+        (async () => {
+            try {
+                const syncBus = await getSyncBus();
+                await syncBus.startListening();
+                syncBus.on("update", (event) => {
+                    // Send an MCP logging notification to the IDE
+                    try {
+                        server.sendLoggingMessage({
+                            level: "info",
+                            data: `[Prism Telepathy] \u{1F9E0} Another agent just updated the memory for ` +
+                                `'${event.project}' to version ${event.version}. ` +
+                                `You may want to run session_load_context to sync up.`,
+                        });
+                    }
+                    catch (err) {
+                        console.error(`[Telepathy] Failed to send notification: ${err}`);
+                    }
+                });
+            }
+            catch (err) {
+                console.error(`[Telepathy] SyncBus init failed (non-fatal): ${err}`);
+            }
+        })();
     }
     // ─── v2.0 Step 8: Mind Palace Dashboard ───
-    startDashboardServer().catch(err => {
-        console.error(`[Dashboard] Mind Palace startup failed (non-fatal): ${err}`);
-    });
+    // Deferred to next tick — yields the event loop so the MCP stdio
+    // transport processes the initialize handshake before dashboard
+    // init spawns child processes (lsof) and awaits storage.
+    setTimeout(() => {
+        startDashboardServer().catch(err => {
+            console.error(`[Dashboard] Mind Palace startup failed (non-fatal): ${err}`);
+        });
+    }, 0);
     // Keep the process alive — without this, Node.js would exit
     // because there are no active event loop handles after the
     // synchronous setup completes.

package/dist/storage/configStorage.js

@@ -16,6 +16,12 @@ import { homedir } from "os";
 const CONFIG_PATH = resolve(homedir(), ".prism-mcp", "prism-config.db");
 let configClient = null;
 let initialized = false;
+// ─── In-memory settings cache ──────────────────────────────────────
+// Preloaded during initConfigStorage() so that hot-path MCP handlers
+// (e.g. ReadResourceRequestSchema) can read settings synchronously
+// without opening an additional SQLite round-trip and stalling the
+// MCP stdio handshake (which causes a black-screen on startup).
+let settingsCache = null;
 function getClient() {
     if (!configClient) {
         configClient = createClient({
@@ -35,17 +41,43 @@ export async function initConfigStorage() {
       updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
     )
   `);
+    // Preload all rows into the cache so subsequent reads are zero-cost.
+    const rs = await client.execute("SELECT key, value FROM system_settings");
+    settingsCache = {};
+    for (const row of rs.rows) {
+        settingsCache[row.key] = row.value;
+    }
     initialized = true;
 }
+/**
+ * Synchronous setting read — served from the in-memory cache.
+ * Returns defaultValue if the cache hasn't been populated yet (e.g. very
+ * early startup before initConfigStorage() has been called) or if the key
+ * doesn't exist. Safe to call from any MCP request handler without triggering
+ * a SQLite round-trip.
+ */
+export function getSettingSync(key, defaultValue = "") {
+    if (!settingsCache)
+        return defaultValue;
+    return settingsCache[key] ?? defaultValue;
+}
 export async function getSetting(key, defaultValue = "") {
     await initConfigStorage();
+    // Serve from cache when warm (the common case after startup).
+    if (settingsCache && key in settingsCache) {
+        return settingsCache[key];
+    }
     const client = getClient();
     const rs = await client.execute({
         sql: "SELECT value FROM system_settings WHERE key = ?",
         args: [key],
     });
     if (rs.rows.length > 0) {
-        return rs.rows[0].value;
+        const value = rs.rows[0].value;
+        // Populate cache entry for future reads.
+        if (settingsCache)
+            settingsCache[key] = value;
+        return value;
     }
     return defaultValue;
 }
@@ -60,9 +92,17 @@ export async function setSetting(key, value) {
     `,
         args: [key, value],
     });
+    // Keep the cache in sync so getSettingSync() reflects the new value immediately.
+    if (settingsCache) {
+        settingsCache[key] = value;
+    }
 }
 export async function getAllSettings() {
     await initConfigStorage();
+    // Return a snapshot of the cache (avoids a redundant DB round-trip).
+    if (settingsCache) {
+        return { ...settingsCache };
+    }
     const client = getClient();
     const rs = await client.execute("SELECT key, value FROM system_settings");
     const settings = {};

package/dist/storage/sqlite.js

@@ -26,13 +26,35 @@ export class SqliteStorage {
     db;
     dbPath;
     // ─── Lifecycle ─────────────────────────────────────────────
-    async initialize() {
-        // Resolve ~/.prism-mcp/ directory
-        const prismDir = path.join(os.homedir(), ".prism-mcp");
-        if (!fs.existsSync(prismDir)) {
-            fs.mkdirSync(prismDir, { recursive: true });
+    async initialize(dbPath) {
+        // ─── DB Path Resolution ────────────────────────────────────────────
+        // Priority:
+        //   1. Explicit dbPath argument — used by tests to inject a per-instance
+        //      path with ZERO global side-effects. No env mutation, no race risk,
+        //      safe under full parallel test execution.
+        //   2. Default: ~/.prism-mcp/data.db — used by production server startup.
+        //
+        // Why explict arg over env var?
+        //   Env vars are process-global. Mutating them around an async boundary
+        //   (set → await initialize() → restore) is racey when multiple test
+        //   suites run in parallel: suite B can clobber PRISM_DB_PATH between
+        //   suite A's write and suite A's read. A direct argument has no
+        //   observable global state and cannot race.
+        let resolvedPath;
+        if (dbPath) {
+            resolvedPath = dbPath;
+            const dir = path.dirname(resolvedPath);
+            if (!fs.existsSync(dir))
+                fs.mkdirSync(dir, { recursive: true });
+        }
+        else {
+            const prismDir = path.join(os.homedir(), ".prism-mcp");
+            if (!fs.existsSync(prismDir)) {
+                fs.mkdirSync(prismDir, { recursive: true });
+            }
+            resolvedPath = path.join(prismDir, "data.db");
         }
-        this.dbPath = path.join(prismDir, "data.db");
+        this.dbPath = resolvedPath;
         this.db = createClient({
             url: `file:${this.dbPath}`,
         });
@@ -261,7 +283,19 @@ export class SqliteStorage {
       )
     `);
         await this.db.execute(`CREATE INDEX IF NOT EXISTS idx_registry_project ON agent_registry(project, user_id)`);
-        // system_settings: key-value store for dashboard runtime settings (v3.0)
+        // ── Note: system_settings is intentionally orphaned ─────────────────
+        // This table is created for forward-compatibility but is NOT the active
+        // settings store. Both SqliteStorage and SupabaseStorage proxy settings
+        // calls to configStorage.js (JSON file on disk) via:
+        //   import { getSetting, setSetting, getAllSettings } from "./configStorage.js"
+        //
+        // The table is NOT safe to drop from the migration because existing user
+        // deployments may already have it and SQLite has no IF EXISTS for DROP
+        // in a safe cross-version migration. Instead, a future release can
+        // repoint getSettings/setSetting to use this.db.execute() here and
+        // retire configStorage.js at that point.
+        //
+        // See: src/storage/interface.ts "v3.0: Dashboard Settings (configStorage proxy)"
         await this.db.execute(`
       CREATE TABLE IF NOT EXISTS system_settings (
         key TEXT PRIMARY KEY,
@@ -292,6 +326,15 @@ export class SqliteStorage {
                 // e.g., "created_at.desc" → "created_at DESC"
                 const parts = value.split(".");
                 const col = parts[0];
+                // ── SQL Injection Guard ──────────────────────────────────────────
+                // col is interpolated directly into the ORDER BY clause. We must
+                // reject anything that isn't a plain identifier (letters, digits,
+                // underscores) before it touches the query string.
+                // Note: @libsql/client already blocks stacked queries (;DROP TABLE),
+                // but CASE WHEN / expression injection is still possible without this.
+                if (!/^[a-zA-Z0-9_]+$/.test(col)) {
+                    throw new Error(`Invalid order column: "${col}". Only alphanumeric identifiers are allowed.`);
+                }
                 const dir = parts[1]?.toUpperCase() === "DESC" ? "DESC" : "ASC";
                 order = `ORDER BY ${col} ${dir}`;
                 continue;
@@ -357,7 +400,13 @@ export class SqliteStorage {
             return [];
         if (typeof value === "string") {
             try {
-                return JSON.parse(value);
+                const parsed = JSON.parse(value);
+                // ── Type Safety Guard ────────────────────────────────────────────
+                // JSON.parse() can return any type (object, number, boolean, null).
+                // If a malformed non-array JSON string (e.g. "{}") somehow made it
+                // into the DB, callers would crash on .map()/.filter().
+                // Force it to an array so all downstream code stays safe.
+                return Array.isArray(parsed) ? parsed : [];
             }
             catch {
                 return [];
@@ -1142,4 +1191,112 @@ export class SqliteStorage {
     async getAllSettings() {
         return cfgGetAll();
     }
+    // ─── v3.1: Memory Analytics ──────────────────────────────────────────────
+    //
+    // Returns usage statistics for the Mind Palace dashboard.
+    // Two SQL queries are used:
+    //   Query 1 — aggregate counts (fast, single pass)
+    //   Query 2 — sessions-per-day for the 14-day sparkline
+    //
+    // Both queries exclude:
+    //   • archived_at IS NOT NULL  — TTL-expired entries (soft-deleted by expireByTTL)
+    //   • deleted_at IS NOT NULL   — GDPR tombstones (from session_forget_memory)
+    // This ensures the dashboard only shows "live" memory, matching what the
+    // LLM actually sees during session_load_context.
+    async getAnalytics(project, userId) {
+        // Query 1: Aggregate stats — total entries, rollup count, tokens saved,
+        // and average summary length (used as a proxy for knowledge richness).
+        const countResult = await this.db.execute({
+            sql: `SELECT
+              COUNT(*) AS total_entries,
+              SUM(CASE WHEN is_rollup = 1 THEN 1 ELSE 0 END) AS total_rollups,
+              -- rollup_count tracks how many raw entries each rollup replaced,
+              -- so we can show "X entries saved by compaction" in the dashboard.
+              SUM(CASE WHEN is_rollup = 1 THEN COALESCE(rollup_count, 0) ELSE 0 END) AS rollup_savings,
+              COALESCE(AVG(LENGTH(summary)), 0) AS avg_summary_length
+            FROM session_ledger
+            WHERE project = ? AND user_id = ?
+              AND archived_at IS NULL AND deleted_at IS NULL`,
+            args: [project, userId],
+        });
+        const row = countResult.rows[0];
+        // Query 2: Sessions per day for the sparkline (last 14 days).
+        // We only count non-rollup entries so the chart reflects actual work sessions,
+        // not compaction operations.
+        const sparkResult = await this.db.execute({
+            sql: `SELECT
+              DATE(created_at) AS date,
+              COUNT(*) AS count
+            FROM session_ledger
+            WHERE project = ? AND user_id = ?
+              AND archived_at IS NULL AND deleted_at IS NULL
+              AND is_rollup = 0
+              AND created_at >= DATE('now', '-14 days')
+            GROUP BY DATE(created_at)
+            ORDER BY date ASC`,
+            args: [project, userId],
+        });
+        // Fill in zeros for days with no sessions so the sparkline always
+        // has exactly 14 bars regardless of how sparse the data is.
+        // A gap-fill approach (day loop + Map lookup) is much simpler than
+        // a SQL recursive CTE for this use case.
+        const sparkMap = new Map();
+        for (const r of sparkResult.rows) {
+            sparkMap.set(r.date, r.count);
+        }
+        const sessionsByDay = [];
+        for (let i = 13; i >= 0; i--) {
+            const date = new Date();
+            date.setDate(date.getDate() - i);
+            const dateStr = date.toISOString().slice(0, 10);
+            sessionsByDay.push({ date: dateStr, count: sparkMap.get(dateStr) || 0 });
+        }
+        return {
+            totalEntries: row?.total_entries || 0,
+            totalRollups: row?.total_rollups || 0,
+            rollupSavings: row?.rollup_savings || 0,
+            avgSummaryLength: Math.round(row?.avg_summary_length || 0),
+            sessionsByDay,
+        };
+    }
+    // ─── v3.1: TTL / Automated Data Retention ────────────────────────────────
+    //
+    // Design: SOFT-DELETE (not hard-delete)
+    //
+    // We set archived_at rather than deleting rows. This means:
+    //   • The entry disappears from session_load_context and knowledge_search
+    //     immediately (both queries filter on archived_at IS NULL)
+    //   • The row is preserved for audit trails and GDPR right-of-access requests
+    //   • A hard-delete can still be performed later via session_forget_memory
+    //     with hard_delete: true
+    //
+    // Rollup entries (is_rollup = 1) are intentionally excluded from expiry:
+    //   • Rollups are dense summaries of many sessions — losing them would wipe
+    //     the entire compacted history, not just old raw entries.
+    //   • If users want to clean up rollups, they should use knowledge_forget
+    //     or session_forget_memory explicitly.
+    //
+    // The minimum TTL enforced in the handler is 7 days, so the cutoff is
+    // always at least one week in the past. This prevents accidental mass-delete.
+    async expireByTTL(project, ttlDays, userId) {
+        const cutoff = new Date();
+        cutoff.setDate(cutoff.getDate() - ttlDays);
+        const cutoffStr = cutoff.toISOString();
+        // Use archived_at (soft-delete) rather than hard-deleting rows.
+        // This preserves the audit trail while hiding old entries from all
+        // standard queries that filter on `archived_at IS NULL`.
+        const result = await this.db.execute({
+            sql: `UPDATE session_ledger
+            SET archived_at = datetime('now')
+            WHERE project = ? AND user_id = ?
+              AND is_rollup = 0          -- never expire compacted rollups
+              AND archived_at IS NULL    -- idempotent: skip already-expired rows
+              AND deleted_at IS NULL     -- skip GDPR tombstones
+              AND created_at < ?`,
+            args: [project, userId, cutoffStr],
+        });
+        const expired = result.rowsAffected || 0;
+        debugLog(`[SqliteStorage] TTL sweep: expired ${expired} entries for "${project}" (cutoff: ${cutoffStr})`);
+        return { expired };
+    }
 }

package/dist/storage/supabase.js

@@ -296,4 +296,56 @@ export class SupabaseStorage {
     async getAllSettings() {
         return cfgGetAll();
     }
+    // ─── v3.1: Memory Analytics ──────────────────────────────────
+    async getAnalytics(project, userId) {
+        // Attempt to call a Supabase RPC. Falls back to zeroed struct if the RPC
+        // doesn't exist yet (avoids breaking users who haven't run the migration).
+        try {
+            const result = await supabaseRpc("get_project_analytics", {
+                p_project: project,
+                p_user_id: userId,
+            });
+            const data = Array.isArray(result) ? result[0] : result;
+            if (data) {
+                return {
+                    totalEntries: data.total_entries || 0,
+                    totalRollups: data.total_rollups || 0,
+                    rollupSavings: data.rollup_savings || 0,
+                    avgSummaryLength: data.avg_summary_length || 0,
+                    sessionsByDay: data.sessions_by_day || [],
+                };
+            }
+        }
+        catch {
+            debugLog("[SupabaseStorage] getAnalytics RPC unavailable — returning zeroed struct");
+        }
+        // Graceful degradation: return zeroed struct so dashboard doesn't crash
+        return {
+            totalEntries: 0, totalRollups: 0, rollupSavings: 0,
+            avgSummaryLength: 0, sessionsByDay: [],
+        };
+    }
+    // ─── v3.1: TTL / Automated Data Retention ────────────────────
+    async expireByTTL(project, ttlDays, userId) {
+        const cutoff = new Date();
+        cutoff.setDate(cutoff.getDate() - ttlDays);
+        const cutoffStr = cutoff.toISOString();
+        // Use existing supabasePatch with PostgREST filter syntax
+        // No new RPC needed — PATCH with filter works for bulk soft-delete
+        try {
+            await supabasePatch("session_ledger", { archived_at: cutoffStr }, {
+                project: `eq.${project}`,
+                user_id: `eq.${userId}`,
+                "created_at": `lt.${cutoffStr}`,
+                "is_rollup": "eq.false",
+                "archived_at": "is.null",
+            });
+        }
+        catch (e) {
+            debugLog("[SupabaseStorage] expireByTTL failed: " + (e instanceof Error ? e.message : String(e)));
+        }
+        // Supabase PATCH doesn't return rowsAffected — return 0 (UI doesn't need exact count)
+        debugLog(`[SupabaseStorage] TTL sweep completed for "${project}" (cutoff: ${cutoffStr})`);
+        return { expired: 0 };
+    }
 }