wyrm-mcp 3.4.0 → 3.5.0

package/README.md

@@ -46,6 +46,36 @@ AI:  *checks Wyrm* "We went with JWT + refresh tokens, stored in httpOnly cookie
 
 ---
 
+## Installation
+
+### npm (recommended)
+```bash
+npm install -g wyrm-mcp
+```
+
+### Homebrew (macOS / Linux)
+```bash
+brew tap ghosts-lk/wyrm
+brew install wyrm-mcp
+```
+
+### Docker
+```bash
+docker run -d -p 3000:3000 -v wyrm-data:/data ghcr.io/ghosts-lk/wyrm-mcp:latest
+```
+Or with Docker Compose:
+```bash
+curl -O https://raw.githubusercontent.com/ghosts-lk/Wyrm/main/docker-compose.yml
+docker compose up -d
+```
+
+### npx (no install)
+```bash
+npx wyrm-mcp
+```
+
+---
+
 ## Quick Start
 
 ### 1. Install

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;GAeG;AAwBH,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;GAeG;AA4BH,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -23,7 +23,10 @@ import { WyrmSync } from "./sync.js";
 import { createContextBundle } from "./summarizer.js";
 import { autoConfigureAll, removeFromAll, getStatusSummary, findWyrmServerPath, getDefaultDbPath } from "./autoconfig.js";
 import { cache, estimateTokens } from "./performance.js";
-import { createHash } from "crypto";
+import { createHash, randomBytes, pbkdf2Sync, createCipheriv, createDecipheriv } from "crypto";
+import { readFileSync, writeFileSync, copyFileSync, chmodSync, unlinkSync, existsSync as fsExistsSync } from "fs";
+import { homedir } from "os";
+import { join as pathJoin } from "path";
 import { initializeOrchestrator, getDefaultConfig } from "./auto-orchestrator.js";
 import { sanitizeFtsQuery, sanitizeString, validateBatchSize } from "./security.js";
 import { getCrypto, initializeCrypto } from "./crypto.js";
@@ -31,7 +34,7 @@ import { createVectorStore } from "./vectors.js";
 import { IndexingPipeline } from "./indexer.js";
 import { KnowledgeGraph } from "./knowledge-graph.js";
 import { MemoryArtifacts } from "./memory-artifacts.js";
-import { GroundTruths, ReasoningScaffolds } from "./intelligence.js";
+import { GroundTruths, ReasoningScaffolds, computeStaleness } from "./intelligence.js";
 import { classifyCapture } from "./capture.js";
 import { injectSystemPrompt } from "./autoconfig.js";
 export { classifyCapture } from "./capture.js";
@@ -222,7 +225,6 @@ const READ_ONLY_TOOLS = new Set([
     "wyrm_entity_search",
     "wyrm_entity_graph",
     "wyrm_entity_path",
-    "wyrm_recall",
     "wyrm_context_build",
     "wyrm_truth_get",
     "wyrm_scaffold_get",
@@ -251,6 +253,7 @@ const WRITE_TOOLS = new Set([
     "wyrm_entity_link",
     "wyrm_entity_merge",
     "wyrm_remember",
+    "wyrm_recall",
     "wyrm_feedback",
     "wyrm_truth_set",
     "wyrm_scaffold_save",
@@ -261,10 +264,13 @@ const WRITE_TOOLS = new Set([
     "wyrm_import_pr",
     "wyrm_import_rules",
     "wyrm_inject_prompt",
+    "wyrm_prune",
+    "wyrm_sync_export",
+    "wyrm_sync_import",
 ]);
 const server = new Server({
     name: "wyrm",
-    version: "3.4.0",
+    version: "3.5.0",
 }, {
     capabilities: {
         tools: {},
@@ -905,6 +911,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                     rationale: { type: "string", description: "Why this is true / how it was determined" },
                     source: { type: "string", description: "Origin: 'user', 'derived', 'observed', 'confirmed'" },
                     confidence: { type: "number", description: "Confidence 0-1 (default: 1.0 for user-asserted truths)" },
+                    ttl_days: { type: "number", description: "Time-to-live in days — truth becomes stale after this many days since last_verified_at" },
                 },
                 required: ["projectPath", "category", "key", "value"],
             },
@@ -1020,6 +1027,45 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 },
             },
         },
+        {
+            name: "wyrm_prune",
+            description: "Prune low-confidence, stale memory artifacts. Dry-run by default — use dry_run:false with confirm_ids to actually delete. Never deletes artifacts in the review queue.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_id: { type: "number", description: "Project ID (optional, all projects if omitted)" },
+                    min_confidence: { type: "number", description: "Prune artifacts below this confidence (default: 0.3)" },
+                    older_than_days: { type: "number", description: "Last accessed more than N days ago (default: 90)" },
+                    types: { type: "array", items: { type: "string" }, description: "Filter by artifact_type (optional)" },
+                    dry_run: { type: "boolean", description: "If true (default), return candidates without deleting. Set false to delete." },
+                    confirm_ids: { type: "array", items: { type: "number" }, description: "Required when dry_run:false — only IDs in this list will be deleted" },
+                },
+            },
+        },
+        {
+            name: "wyrm_sync_export",
+            description: "Export an AES-256-GCM encrypted snapshot of the Wyrm database for cross-device sync. Passphrase from WYRM_SYNC_PASSPHRASE env var.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    output_path: { type: "string", description: "File path to write the encrypted snapshot" },
+                    description: { type: "string", description: "Optional description of this export" },
+                },
+                required: ["output_path"],
+            },
+        },
+        {
+            name: "wyrm_sync_import",
+            description: "Import an encrypted Wyrm snapshot. Use restore_mode:'preview' to inspect without touching the DB; 'restore' to replace current DB (backs up first).",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    input_path: { type: "string", description: "Path to the encrypted snapshot file" },
+                    restore_mode: { type: "string", enum: ["preview", "restore"], description: "preview = show stats only; restore = replace DB (backs up first)" },
+                },
+                required: ["input_path", "restore_mode"],
+            },
+        },
         {
             name: "wyrm_import_git",
             description: "Import a list of commits into the Wyrm memory review queue. Useful for onboarding a project's history or capturing recent work.",
@@ -1919,6 +1965,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         limit: rcLimit ?? 10,
                         minConfidence: rcMinConf,
                     });
+                    // Track access for memory decay
+                    if (results.length > 0) {
+                        const rawDbRecall = db.getDatabase();
+                        const ids = results.map(r => r.artifact.id);
+                        const placeholders = ids.map(() => '?').join(',');
+                        rawDbRecall.prepare(`UPDATE memory_artifacts SET last_accessed_at = datetime('now'), access_count = access_count + 1 WHERE id IN (${placeholders})`).run(...ids);
+                    }
                     if (results.length === 0) {
                         return { content: [{ type: "text", text: `🐉 No relevant memory found for: "${rcQuery}"\n\nUse \`wyrm_remember\` to store knowledge as you work.` }] };
                     }
@@ -1942,10 +1995,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         text += `_Confidence: ${(a.confidence * 100).toFixed(0)}% | Used ${a.reuse_count}× | Success rate: ${a.reuse_count > 0 ? ((a.reuse_success_count / a.reuse_count) * 100).toFixed(0) + '%' : 'not yet used'}_\n\n`;
                     }
                     text += `_Use \`wyrm_feedback\` to record whether these were helpful._`;
-                    const response = cachedResponse(text);
-                    if (cacheKey)
-                        cache.set(cacheKey, response, 15000);
-                    return response;
+                    return cachedResponse(text);
                 }
                 case "wyrm_feedback": {
                     const { artifactId, success } = args;
@@ -2004,7 +2054,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     return response;
                 }
                 case "wyrm_truth_set": {
-                    const { projectPath: tPath, category: tCat, key: tKey, value: tVal, rationale: tRat, source: tSrc, confidence: tConf } = args;
+                    const { projectPath: tPath, category: tCat, key: tKey, value: tVal, rationale: tRat, source: tSrc, confidence: tConf, ttl_days: tTtl } = args;
                     const tProject = db.getProject(tPath);
                     if (!tProject)
                         return { content: [{ type: "text", text: `Project not found: ${tPath}` }], isError: true };
@@ -2015,10 +2065,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         rationale: tRat,
                         source: tSrc,
                         confidence: tConf ?? 1.0,
+                        ttl_days: tTtl,
                     });
                     cache.invalidate('wyrm_truth_get');
                     cache.invalidate('wyrm_context_build');
-                    return { content: [{ type: "text", text: `🐉 **Ground Truth Set** ✅\n\n- **Category:** ${tCat}\n- **Key:** ${tKey}\n- **Value:** ${tVal}${tRat ? `\n- **Rationale:** ${tRat}` : ''}\n- **ID:** ${truth.id}\n\nThis truth will be injected at the top of every \`wyrm_context_build\` response for this project.` }] };
+                    return { content: [{ type: "text", text: `🐉 **Ground Truth Set** ✅\n\n- **Category:** ${tCat}\n- **Key:** ${tKey}\n- **Value:** ${tVal}${tRat ? `\n- **Rationale:** ${tRat}` : ''}${tTtl ? `\n- **TTL:** ${tTtl} days` : ''}\n- **ID:** ${truth.id}\n\nThis truth will be injected at the top of every \`wyrm_context_build\` response for this project.` }] };
                 }
                 case "wyrm_truth_get": {
                     const { projectPath: tgPath, category: tgCat } = args;
@@ -2042,11 +2093,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     for (const [cat, items] of byCategory) {
                         text += `### ${cat}\n`;
                         for (const t of items) {
-                            text += `- **${t.key}:** ${t.value}`;
+                            const staleness = computeStaleness(t);
+                            const stale = staleness !== null && staleness > 0.7;
+                            const stalePrefix = stale ? '[⚠️ STALE] ' : '';
+                            text += `- ${stalePrefix}**${t.key}:** ${t.value}`;
                             if (t.confidence < 1)
                                 text += ` _(confidence: ${(t.confidence * 100).toFixed(0)}%)_`;
                             if (t.rationale)
                                 text += `\n  _${t.rationale}_`;
+                            if (staleness !== null)
+                                text += `\n  _staleness: ${(staleness * 100).toFixed(0)}% (TTL: ${t.ttl_days}d)_`;
                             text += '\n';
                         }
                         text += '\n';
@@ -2591,6 +2647,35 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         if (effectiveProjId === null) {
                             return { content: [{ type: "text", text: `🧠 Cannot capture truth without project_id. Please provide project_id.` }], isError: true };
                         }
+                        // Structural contradiction check: same project + same category
+                        if (capConf >= 80) {
+                            const capCategory = capSubtype ?? 'other';
+                            const existingTruths = groundTruths.getCurrent(effectiveProjId);
+                            const sameCategory = existingTruths.filter(t => t.category === capCategory);
+                            if (sameCategory.length > 0) {
+                                // Route to review queue — possible supersession
+                                const conflictArtifact = memory.add(effectiveProjId, {
+                                    kind: 'pattern',
+                                    problem: `Potential conflict with ${sameCategory.length} existing truth(s) in category "${capCategory}"`,
+                                    validatedFix: capContent,
+                                    whyItWorked: 'Pending review — possible supersession',
+                                    tags: capTags ?? [],
+                                    confidence: capConf / 100,
+                                    needsReview: 1,
+                                });
+                                return {
+                                    content: [{
+                                            type: "text",
+                                            text: JSON.stringify({
+                                                status: 'queued_for_review',
+                                                reason: 'conflict_check',
+                                                artifact_id: conflictArtifact.id,
+                                                conflicts_with: sameCategory.map(t => ({ id: t.id, content: t.value.slice(0, 80) })),
+                                            }),
+                                        }],
+                                };
+                            }
+                        }
                         if (capMode !== 'truth' && capConf < 100) {
                             // Store as artifact pending review
                             const artifact = memory.add(effectiveProjId, {
@@ -2638,6 +2723,34 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         if (!shouldAutoCreate) {
                             needsReviewNote = `\n⚠️ Stored for review — run \`wyrm_review\` to activate`;
                         }
+                        // Advisory conflict check for heuristics (non-blocking)
+                        let advisoryConflicts;
+                        if (capSubtype === 'heuristic' && capConf >= 75 && effectiveProjId !== null) {
+                            try {
+                                const rawDbCap = db.getDatabase();
+                                const sanitizedCap = capContent.replace(/['"*]/g, ' ').trim().split(/\s+/).slice(0, 5).join(' ');
+                                const heuristicConflicts = rawDbCap.prepare(`
+                SELECT a.id, a.problem FROM memory_artifacts a
+                JOIN memory_artifacts_fts fts ON a.id = fts.rowid
+                WHERE fts MATCH ? AND a.project_id = ? AND a.kind = 'heuristic' AND a.needs_review = 0
+                LIMIT 3
+              `).all(sanitizedCap, effectiveProjId);
+                                if (heuristicConflicts.length > 0) {
+                                    advisoryConflicts = heuristicConflicts.map(h => ({ id: h.id, content: h.problem.slice(0, 80) }));
+                                }
+                            }
+                            catch {
+                                // FTS may fail on short queries — advisory only, ignore
+                            }
+                        }
+                        if (advisoryConflicts && advisoryConflicts.length > 0) {
+                            return {
+                                content: [{
+                                        type: "text",
+                                        text: `🧠 Captured as ${capType}: ${capSubtype}\nConfidence: ${capConf}%  |  ${capReasoning}\nID: ${typeShort}:${storedId}${needsReviewNote}\n\n⚠️ Advisory: ${advisoryConflicts.length} similar heuristic(s) found:\n${advisoryConflicts.map(c => `  - [${c.id}] ${c.content}`).join('\n')}`,
+                                    }],
+                            };
+                        }
                     }
                     return {
                         content: [{
@@ -2674,10 +2787,32 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         return { content: [{ type: "text", text: `🐉 Project not found. Available projects:\n${candidates}` }] };
                     }
                     const sections = [];
-                    // Section 1 — Ground Truths (up to 1200 chars)
-                    const truthsText = groundTruths.formatForContext(spProject.id, 1200);
-                    if (truthsText)
-                        sections.push(truthsText);
+                    // Section 1 — Ground Truths (up to 1200 chars), prefix stale truths
+                    const spCurrentTruths = groundTruths.getCurrent(spProject.id);
+                    if (spCurrentTruths.length > 0) {
+                        const CATEGORY_LABELS_SP = {
+                            tech_stack: '🛠️ Tech Stack', architecture: '🏗️ Architecture',
+                            constraint: '🚧 Constraints', decision: '📋 Decisions',
+                            contact: '👤 Contacts', other: '📌 Other Facts',
+                        };
+                        let spTruthsText = '### 📚 Project Ground Truths _(treat as authoritative — do not infer or contradict)_\n';
+                        const spByCategory = new Map();
+                        for (const t of spCurrentTruths) {
+                            if (!spByCategory.has(t.category))
+                                spByCategory.set(t.category, []);
+                            spByCategory.get(t.category).push(t);
+                        }
+                        for (const [cat, items] of spByCategory) {
+                            spTruthsText += `**${CATEGORY_LABELS_SP[cat] ?? cat}:**\n`;
+                            for (const t of items) {
+                                const staleness = computeStaleness(t);
+                                const stale = staleness !== null && staleness > 0.7;
+                                const stalePrefix = stale ? '[⚠️ STALE] ' : '';
+                                spTruthsText += `- ${stalePrefix}**${t.key}:** ${t.value}${t.rationale ? ` _(${t.rationale})_` : ''}\n`;
+                            }
+                        }
+                        sections.push(spTruthsText.slice(0, 1200));
+                    }
                     // Section 2 — Reasoning Scaffold (up to 1500 chars)
                     if (spTask) {
                         const scaffoldMatchSP = scaffoldLib.findBest(spTask, spProject.id, 0.3);
@@ -2869,7 +3004,249 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     }
                     return { content: [{ type: "text", text: injText }] };
                 }
-                default:
+                // ==================== v3.5.0 TOOLS ====================
+                case "wyrm_prune": {
+                    const { project_id: pruneProjectId, min_confidence: pruneMinConf = 0.3, older_than_days: pruneOlderDays = 90, types: pruneTypes, dry_run: pruneDryRun = true, confirm_ids: pruneConfirmIds, } = args;
+                    const rawDbPrune = db.getDatabase();
+                    const projectClausePrune = pruneProjectId !== undefined ? `AND project_id = ${pruneProjectId}` : '';
+                    const typeClausePrune = pruneTypes && pruneTypes.length > 0
+                        ? `AND kind IN (${pruneTypes.map(() => '?').join(',')})`
+                        : '';
+                    const typeParamsPrune = pruneTypes ?? [];
+                    const candidateRows = rawDbPrune.prepare(`
+          SELECT id, project_id, kind, problem, confidence, last_accessed_at, access_count
+          FROM memory_artifacts
+          WHERE confidence < ?
+            AND (last_accessed_at IS NULL OR last_accessed_at < datetime('now', ?))
+            AND needs_review = 0
+            AND supersedes_id IS NULL
+            ${projectClausePrune}
+            ${typeClausePrune}
+          ORDER BY confidence ASC, last_accessed_at ASC
+          LIMIT 500
+        `).all(pruneMinConf, `-${pruneOlderDays} days`, ...typeParamsPrune);
+                    if (pruneDryRun) {
+                        return {
+                            content: [{
+                                    type: "text",
+                                    text: JSON.stringify({
+                                        dry_run: true,
+                                        count: candidateRows.length,
+                                        candidates: candidateRows.map(r => ({
+                                            id: r.id,
+                                            kind: r.kind,
+                                            problem: r.problem.slice(0, 100),
+                                            confidence: r.confidence,
+                                            last_accessed_at: r.last_accessed_at,
+                                        })),
+                                    }),
+                                }],
+                        };
+                    }
+                    // dry_run: false — require confirm_ids
+                    if (!pruneConfirmIds || pruneConfirmIds.length === 0) {
+                        return {
+                            content: [{ type: "text", text: `🐉 **Prune**: dry_run:false requires confirm_ids — provide the IDs from a dry-run to confirm deletion.` }],
+                            isError: true,
+                        };
+                    }
+                    const candidateIds = new Set(candidateRows.map(r => r.id));
+                    const toDelete = pruneConfirmIds.filter(id => candidateIds.has(id));
+                    if (toDelete.length === 0) {
+                        return {
+                            content: [{ type: "text", text: `🐉 **Prune**: No matching IDs to delete (confirm_ids not in candidate set).` }],
+                        };
+                    }
+                    const placeholdersPrune = toDelete.map(() => '?').join(',');
+                    const deleteResult = rawDbPrune.prepare(`DELETE FROM memory_artifacts WHERE id IN (${placeholdersPrune}) AND needs_review = 0`).run(...toDelete);
+                    return {
+                        content: [{
+                                type: "text",
+                                text: JSON.stringify({ deleted: deleteResult.changes, ids: toDelete }),
+                            }],
+                    };
+                }
+                case "wyrm_sync_export": {
+                    const { output_path: exportPath, description: exportDesc } = args;
+                    const passphrase = process.env.WYRM_SYNC_PASSPHRASE;
+                    if (!passphrase) {
+                        return {
+                            content: [{ type: "text", text: `🐉 **Sync Export**: Set WYRM_SYNC_PASSPHRASE env var to enable encrypted export.` }],
+                            isError: true,
+                        };
+                    }
+                    const dbPath = db.getDatabasePath();
+                    const wyrmDir = pathJoin(homedir(), '.wyrm');
+                    const tempDbPath = pathJoin(wyrmDir, 'wyrm_sync_export_temp.db');
+                    try {
+                        // WAL-safe snapshot via VACUUM INTO
+                        const rawDbExport = db.getDatabase();
+                        if (fsExistsSync(tempDbPath))
+                            unlinkSync(tempDbPath);
+                        rawDbExport.prepare(`VACUUM INTO ?`).run(tempDbPath);
+                        // Read snapshot
+                        const plaintext = readFileSync(tempDbPath);
+                        // Derive key
+                        const salt = randomBytes(32);
+                        const iv = randomBytes(16);
+                        const key = pbkdf2Sync(passphrase, salt, 600000, 32, 'sha256');
+                        // Encrypt
+                        const cipher = createCipheriv('aes-256-gcm', key, iv);
+                        const encrypted = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+                        const authTag = cipher.getAuthTag();
+                        // Binary format: WYRM(4) + version(1) + salt(32) + iv(16) + authTag(16) + data
+                        const magic = Buffer.from('WYRM');
+                        const version = Buffer.alloc(1);
+                        version.writeUInt8(1, 0);
+                        const output = Buffer.concat([magic, version, salt, iv, authTag, encrypted]);
+                        writeFileSync(exportPath, output);
+                        try {
+                            chmodSync(exportPath, 0o600);
+                        }
+                        catch { /* non-fatal */ }
+                        // Clean up temp
+                        try {
+                            unlinkSync(tempDbPath);
+                        }
+                        catch { /* non-fatal */ }
+                        const sizeMb = (output.length / (1024 * 1024)).toFixed(2);
+                        return {
+                            content: [{
+                                    type: "text",
+                                    text: JSON.stringify({
+                                        success: true,
+                                        path: exportPath,
+                                        size_mb: parseFloat(sizeMb),
+                                        exported_at: new Date().toISOString(),
+                                        description: exportDesc ?? null,
+                                    }),
+                                }],
+                        };
+                    }
+                    catch (err) {
+                        try {
+                            if (fsExistsSync(tempDbPath))
+                                unlinkSync(tempDbPath);
+                        }
+                        catch { /* clean up */ }
+                        return {
+                            content: [{ type: "text", text: `🐉 **Sync Export** failed: ${err}` }],
+                            isError: true,
+                        };
+                    }
+                }
+                case "wyrm_sync_import":
+                    {
+                        const { input_path: importPath, restore_mode: restoreMode } = args;
+                        const passphrase = process.env.WYRM_SYNC_PASSPHRASE;
+                        if (!passphrase) {
+                            return {
+                                content: [{ type: "text", text: `🐉 **Sync Import**: Set WYRM_SYNC_PASSPHRASE env var to enable encrypted import.` }],
+                                isError: true,
+                            };
+                        }
+                        const wyrmDirImport = pathJoin(homedir(), '.wyrm');
+                        const tempImportPath = pathJoin(wyrmDirImport, 'wyrm_sync_import_temp.db');
+                        try {
+                            const fileData = readFileSync(importPath);
+                            // Validate magic bytes
+                            const magic = fileData.subarray(0, 4).toString('ascii');
+                            if (magic !== 'WYRM') {
+                                return { content: [{ type: "text", text: `🐉 Invalid Wyrm snapshot file (bad magic bytes).` }], isError: true };
+                            }
+                            const version = fileData.readUInt8(4);
+                            if (version !== 1) {
+                                return { content: [{ type: "text", text: `🐉 Unsupported snapshot version: ${version}` }], isError: true };
+                            }
+                            const salt = fileData.subarray(5, 37);
+                            const iv = fileData.subarray(37, 53);
+                            const authTag = fileData.subarray(53, 69);
+                            const encrypted = fileData.subarray(69);
+                            // Derive key & decrypt
+                            const key = pbkdf2Sync(passphrase, salt, 600000, 32, 'sha256');
+                            const decipher = createDecipheriv('aes-256-gcm', key, iv);
+                            decipher.setAuthTag(authTag);
+                            let decrypted;
+                            try {
+                                decrypted = Buffer.concat([decipher.update(encrypted), decipher.final()]);
+                            }
+                            catch {
+                                return { content: [{ type: "text", text: `🐉 Decryption failed — wrong passphrase or corrupted snapshot.` }], isError: true };
+                            }
+                            if (restoreMode === 'preview') {
+                                // Open temp DB and return stats
+                                if (fsExistsSync(tempImportPath))
+                                    unlinkSync(tempImportPath);
+                                writeFileSync(tempImportPath, decrypted);
+                                let previewStats = {};
+                                try {
+                                    const BetterSQLite = (await import('better-sqlite3')).default;
+                                    const previewDb = new BetterSQLite(tempImportPath, { readonly: true });
+                                    const tables = ['projects', 'sessions', 'ground_truths', 'memory_artifacts', 'quests'];
+                                    for (const t of tables) {
+                                        try {
+                                            const row = previewDb.prepare(`SELECT COUNT(*) as n FROM ${t}`).get();
+                                            previewStats[t] = row.n;
+                                        }
+                                        catch {
+                                            previewStats[t] = 0;
+                                        }
+                                    }
+                                    previewDb.close();
+                                }
+                                catch { /* stats optional */ }
+                                try {
+                                    unlinkSync(tempImportPath);
+                                }
+                                catch { /* clean up */ }
+                                return {
+                                    content: [{
+                                            type: "text",
+                                            text: JSON.stringify({ preview: true, stats: previewStats }),
+                                        }],
+                                };
+                            }
+                            // restore mode
+                            const dbPathImport = db.getDatabasePath();
+                            const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+                            const backupPath = `${dbPathImport}.backup.${timestamp}`;
+                            // Backup current DB
+                            copyFileSync(dbPathImport, backupPath);
+                            // Write decrypted to temp
+                            if (fsExistsSync(tempImportPath))
+                                unlinkSync(tempImportPath);
+                            writeFileSync(tempImportPath, decrypted);
+                            // Close current DB connection, replace file, reopen
+                            const rawDbImport = db.getDatabase();
+                            rawDbImport.close();
+                            copyFileSync(tempImportPath, dbPathImport);
+                            try {
+                                unlinkSync(tempImportPath);
+                            }
+                            catch { /* clean up */ }
+                            return {
+                                content: [{
+                                        type: "text",
+                                        text: JSON.stringify({
+                                            success: true,
+                                            restored_from: importPath,
+                                            backup_at: backupPath,
+                                        }),
+                                    }],
+                            };
+                        }
+                        catch (err) {
+                            try {
+                                if (fsExistsSync(tempImportPath))
+                                    unlinkSync(tempImportPath);
+                            }
+                            catch { /* clean up */ }
+                            return {
+                                content: [{ type: "text", text: `🐉 **Sync Import** failed: ${err}` }],
+                                isError: true,
+                            };
+                        }
+                    }
                     return {
                         content: [{ type: "text", text: `Unknown tool: ${name}` }],
                         isError: true,