shieldcortex 4.12.14 → 4.13.0

package/dist/cli/migrate-legacy.js

@@ -0,0 +1,291 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { randomUUID } from 'crypto';
+import Database from 'better-sqlite3';
+const DEFAULT_LEGACY_SOURCES = [
+    path.join(os.homedir(), '.claude-cortex', 'memories.db'),
+    path.join(os.homedir(), '.claude-memory', 'memories.db'),
+];
+const DEFAULT_TARGET = path.join(os.homedir(), '.shieldcortex', 'memories.db');
+function migrateOne(sourcePath, target, dryRun) {
+    const report = {
+        path: sourcePath,
+        exists: false,
+        memoriesFound: 0,
+        memoriesImported: 0,
+        linksFound: 0,
+        linksImported: 0,
+        linksSkipped: 0,
+    };
+    if (!fs.existsSync(sourcePath))
+        return report;
+    report.exists = true;
+    let source;
+    try {
+        source = new Database(sourcePath, { readonly: true, fileMustExist: true });
+        const memories = source
+            .prepare(`
+        SELECT id, type, category, title, content, project, tags, salience,
+               decayed_score, access_count, last_accessed, created_at,
+               metadata, embedding, scope, transferable
+        FROM memories
+      `)
+            .all();
+        const links = source
+            .prepare(`
+        SELECT source_id, target_id, relationship, strength, created_at
+        FROM memory_links
+      `)
+            .all();
+        report.memoriesFound = memories.length;
+        report.linksFound = links.length;
+        if (dryRun)
+            return report;
+        const insertMemory = target.prepare(`
+      INSERT INTO memories (
+        uuid, type, category, title, content, project, tags, salience,
+        decayed_score, access_count, last_accessed, created_at, updated_at,
+        metadata, embedding, scope, transferable, source, source_kind, capture_method
+      ) VALUES (
+        @uuid, @type, @category, @title, @content, @project, @tags, @salience,
+        @decayed_score, @access_count, @last_accessed, @created_at, @updated_at,
+        @metadata, @embedding, @scope, @transferable, @source, @source_kind, @capture_method
+      )
+    `);
+        const insertLink = target.prepare(`
+      INSERT OR IGNORE INTO memory_links (source_id, target_id, relationship, strength, created_at)
+      VALUES (?, ?, ?, ?, ?)
+    `);
+        const sourceLabel = path.basename(path.dirname(sourcePath));
+        const idMap = new Map();
+        const txn = target.transaction(() => {
+            for (const row of memories) {
+                const result = insertMemory.run({
+                    uuid: randomUUID(),
+                    type: row.type,
+                    category: row.category,
+                    title: row.title,
+                    content: row.content,
+                    project: row.project,
+                    tags: row.tags ?? '[]',
+                    salience: row.salience ?? 0.5,
+                    decayed_score: row.decayed_score,
+                    access_count: row.access_count ?? 0,
+                    last_accessed: row.last_accessed,
+                    created_at: row.created_at,
+                    updated_at: row.created_at,
+                    metadata: row.metadata ?? '{}',
+                    embedding: row.embedding,
+                    scope: row.scope ?? 'project',
+                    transferable: row.transferable ?? 0,
+                    source: `legacy:${sourceLabel}`,
+                    source_kind: 'legacy-import',
+                    capture_method: 'legacy-migrate',
+                });
+                idMap.set(row.id, Number(result.lastInsertRowid));
+                report.memoriesImported++;
+            }
+            for (const link of links) {
+                const newSource = idMap.get(link.source_id);
+                const newTarget = idMap.get(link.target_id);
+                if (newSource === undefined || newTarget === undefined) {
+                    report.linksSkipped++;
+                    continue;
+                }
+                const linkResult = insertLink.run(newSource, newTarget, link.relationship, link.strength ?? 0.5, link.created_at);
+                if (linkResult.changes > 0)
+                    report.linksImported++;
+                else
+                    report.linksSkipped++;
+            }
+        });
+        txn();
+    }
+    catch (err) {
+        report.error = err instanceof Error ? err.message : String(err);
+    }
+    finally {
+        source?.close();
+    }
+    return report;
+}
+export function migrateLegacy(options = {}) {
+    const sources = options.sources ?? DEFAULT_LEGACY_SOURCES;
+    const targetPath = options.target ?? DEFAULT_TARGET;
+    const dryRun = options.dryRun === true;
+    if (!fs.existsSync(targetPath)) {
+        throw new Error(`target DB does not exist: ${targetPath} (run \`shieldcortex setup\` first)`);
+    }
+    const target = new Database(targetPath);
+    // Foreign keys on so legacy links to deleted memories fail loudly.
+    target.pragma('foreign_keys = ON');
+    // The dashboard API server holds an open connection in WAL mode; give the
+    // SQLite locking layer plenty of room to coordinate so the migration
+    // doesn't bail with SQLITE_BUSY mid-transaction.
+    target.pragma('busy_timeout = 10000');
+    const report = {
+        target: targetPath,
+        dryRun,
+        sources: [],
+        totalMemories: 0,
+        totalLinks: 0,
+    };
+    try {
+        for (const sourcePath of sources) {
+            const sourceReport = migrateOne(sourcePath, target, dryRun);
+            report.sources.push(sourceReport);
+            report.totalMemories += sourceReport.memoriesImported;
+            report.totalLinks += sourceReport.linksImported;
+        }
+    }
+    finally {
+        target.close();
+    }
+    return report;
+}
+function printReport(report) {
+    const banner = report.dryRun ? '[DRY RUN] ' : '';
+    console.log(`${banner}Legacy memory migration → ${report.target}`);
+    console.log('');
+    for (const src of report.sources) {
+        if (!src.exists) {
+            console.log(`  ${src.path}: not found, skipped`);
+            continue;
+        }
+        if (src.error) {
+            console.log(`  ${src.path}: ERROR — ${src.error}`);
+            continue;
+        }
+        const verb = report.dryRun ? 'would import' : 'imported';
+        console.log(`  ${src.path}:`);
+        console.log(`    memories: ${src.memoriesFound} found, ${verb} ${src.memoriesImported}`);
+        console.log(`    links:    ${src.linksFound} found, ${verb} ${src.linksImported}, skipped ${src.linksSkipped}`);
+    }
+    console.log('');
+    console.log(report.dryRun
+        ? `Total: would import ${report.totalMemories} memories + ${report.totalLinks} links.`
+        : `Total: imported ${report.totalMemories} memories + ${report.totalLinks} links.`);
+    if (!report.dryRun) {
+        console.log('');
+        console.log('Tip: back up of the target DB was your responsibility — restore from');
+        console.log('     ~/.shieldcortex/memories.db.bak.* if needed.');
+    }
+}
+function flagValue(args, name) {
+    const idx = args.indexOf(name);
+    if (idx === -1)
+        return undefined;
+    const v = args[idx + 1];
+    if (!v || v.startsWith('--'))
+        return undefined;
+    return v;
+}
+async function runPrune(args) {
+    const { initDatabase } = await import('../database/init.js');
+    const { pruneMemories } = await import('../memory/prune.js');
+    initDatabase();
+    const dryRun = !args.includes('--execute');
+    const salienceLte = Number(flagValue(args, '--salience-lte') ?? 0.2);
+    const ageDaysGte = Number(flagValue(args, '--older-than') ?? 30);
+    const project = flagValue(args, '--project');
+    const includePinned = args.includes('--include-pinned');
+    const result = await pruneMemories({
+        salienceLte,
+        ageDaysGte,
+        project,
+        excludePinned: !includePinned,
+        dryRun,
+    });
+    const banner = dryRun ? '[DRY RUN] ' : '';
+    console.log(`${banner}Prune memories where salience <= ${salienceLte} AND age >= ${ageDaysGte}d`);
+    console.log(`  Project: ${project ?? '(all)'} · ExcludePinned: ${!includePinned}`);
+    console.log(`  Matched: ${result.matched}`);
+    if (result.sample.length > 0) {
+        console.log('  Sample:');
+        for (const s of result.sample) {
+            console.log(`    #${s.id} [${s.project ?? '-'}] sal ${s.salience.toFixed(2)} · ${s.ageDays}d · ${s.title.slice(0, 60)}`);
+        }
+    }
+    if (!dryRun) {
+        console.log(`  Deleted: ${result.deleted ?? 0}`);
+        if (result.backupPath)
+            console.log(`  Backup:  ${result.backupPath}`);
+    }
+    else if (result.matched > 0) {
+        console.log('  Re-run with --execute to delete.');
+    }
+}
+async function runDedupe(args) {
+    const { initDatabase } = await import('../database/init.js');
+    const { dedupeMemories } = await import('../memory/dedupe-runner.js');
+    initDatabase();
+    const dryRun = !args.includes('--execute');
+    const project = flagValue(args, '--project');
+    const limit = Number(flagValue(args, '--limit') ?? 200);
+    const result = await dedupeMemories({ project, dryRun, limit });
+    const banner = dryRun ? '[DRY RUN] ' : '';
+    console.log(`${banner}Dedupe long-term memories${project ? ` in project ${project}` : ' (all projects)'}`);
+    console.log(`  Pairs scanned: ${result.pairsFound}`);
+    console.log(`  Clusters: ${result.groups.length}`);
+    const totalRemovable = result.groups.reduce((sum, g) => sum + g.removeIds.length, 0);
+    console.log(`  Removable: ${totalRemovable}`);
+    if (result.groups.length > 0) {
+        console.log('  Groups:');
+        for (const g of result.groups.slice(0, 10)) {
+            console.log(`    keep #${g.keepId} [${g.removeIds.length} dup] ${g.similarity} — "${g.keepTitle.slice(0, 50)}"`);
+        }
+        if (result.groups.length > 10)
+            console.log(`    … and ${result.groups.length - 10} more`);
+    }
+    if (!dryRun) {
+        console.log(`  Merged: ${result.merged ?? 0}`);
+        if (result.backupPath)
+            console.log(`  Backup: ${result.backupPath}`);
+    }
+    else if (totalRemovable > 0) {
+        console.log('  Re-run with --execute to merge.');
+    }
+}
+function printUsage() {
+    console.log('Usage: shieldcortex memories <subcommand> [options]');
+    console.log('');
+    console.log('Subcommands:');
+    console.log('  migrate-legacy [--dry-run] [--source <path>]');
+    console.log('      Import memories from ~/.claude-memory/ and ~/.claude-cortex/');
+    console.log('      into the current ~/.shieldcortex/memories.db.');
+    console.log('');
+    console.log('  prune [--salience-lte 0.2] [--older-than 30] [--project X]');
+    console.log('        [--include-pinned] [--execute]');
+    console.log('      Delete memories below salience X older than N days.');
+    console.log('      DRY-RUN BY DEFAULT — pass --execute to actually delete.');
+    console.log('      Backup auto-saved before any delete.');
+    console.log('');
+    console.log('  dedupe [--project X] [--limit 200] [--execute]');
+    console.log('      Cluster near-duplicate long-term memories and keep the highest-');
+    console.log('      salience representative. DRY-RUN BY DEFAULT — pass --execute.');
+    console.log('      Backup auto-saved before any merge.');
+}
+export async function handleMemoriesCommand(args) {
+    const sub = args[0];
+    if (sub === 'migrate-legacy') {
+        const dryRun = args.includes('--dry-run');
+        const sourceIdx = args.indexOf('--source');
+        const sources = sourceIdx !== -1 && args[sourceIdx + 1]
+            ? [args[sourceIdx + 1]]
+            : undefined;
+        const report = migrateLegacy({ sources, dryRun });
+        printReport(report);
+        return;
+    }
+    if (sub === 'prune') {
+        await runPrune(args.slice(1));
+        return;
+    }
+    if (sub === 'dedupe') {
+        await runDedupe(args.slice(1));
+        return;
+    }
+    printUsage();
+    process.exit(1);
+}

package/dist/cloud/cli.js

@@ -157,8 +157,8 @@ export function handleCloudConfig(args) {
         console.log('  --cloud-enable         Enable cloud sync');
         console.log('  --cloud-disable        Disable cloud sync');
         console.log('  --cloud-status         Show current configuration');
-        console.log('  --openclaw-auto-memory <true|false>  Enable or disable OpenClaw auto-memory extraction');
-        console.log('  --proactive-recall <true|false>  Enable or disable proactive memory recall on prompts');
+        console.log('  --openclaw-auto-memory <true|false>  Extract memories from OpenClaw LLM output (default: off)');
+        console.log('  --proactive-recall <true|false>  Inject SC memory into prompts (default: off — adds latency)');
         console.log('  --restore-4.10-defaults  Restore pre-v4.11.0 defaults (recall on, strict interceptor, minimal preamble)');
         console.log('');
         console.log('LLM Verification:');

package/dist/database/init.js

@@ -31,7 +31,14 @@ function expandPath(path) {
  * Get the database path with legacy fallback
  * - New installs use ~/.shieldcortex/
  * - Existing users with ~/.claude-memory/ continue to work
+ *
+ * DEPRECATION: the .claude-memory fallback will be removed in v5.0.0 (target
+ * Q3 2026). Existing users on the legacy path get a one-time-per-process
+ * warning pointing them at `shieldcortex migrate-legacy` so they can move to
+ * ~/.shieldcortex/ before the cut. Same applies to .claude-cortex (separate
+ * legacy DB read by the CLI migrate command).
  */
+let _legacyFallbackWarned = false;
 function getDefaultDbPath() {
     const newPath = join(homedir(), '.shieldcortex', 'memories.db');
     const legacyPath = join(homedir(), '.claude-memory', 'memories.db');
@@ -39,7 +46,13 @@ function getDefaultDbPath() {
     if (existsSync(newPath) || !existsSync(legacyPath)) {
         return newPath;
     }
-    // Fall back to legacy path for existing users
+    // Fall back to legacy path for existing users — warn once.
+    if (!_legacyFallbackWarned) {
+        _legacyFallbackWarned = true;
+        console.warn('[shieldcortex] DEPRECATED: reading from ~/.claude-memory/memories.db.');
+        console.warn('[shieldcortex] This fallback will be removed in v5.0.0 (target Q3 2026).');
+        console.warn('[shieldcortex] To migrate now: shieldcortex migrate-legacy');
+    }
     return legacyPath;
 }
 function resolveRuntimeInfo() {
@@ -729,6 +742,18 @@ function runMigrations(database) {
       CREATE INDEX IF NOT EXISTS idx_frag_entities_memory ON fragmentation_entities(memory_id);
       CREATE INDEX IF NOT EXISTS idx_frag_entities_text ON fragmentation_entities(entity_value);
       CREATE INDEX IF NOT EXISTS idx_frag_entities_type ON fragmentation_entities(entity_type);
+
+      CREATE TABLE IF NOT EXISTS hook_invocations (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        hook_name TEXT NOT NULL,
+        invoked_at TEXT NOT NULL DEFAULT (datetime('now')),
+        exit_code INTEGER,
+        duration_ms INTEGER,
+        memories_extracted INTEGER DEFAULT 0,
+        transcript_bytes INTEGER,
+        notes TEXT
+      );
+      CREATE INDEX IF NOT EXISTS idx_hook_invocations_name_time ON hook_invocations(hook_name, invoked_at DESC);
     `);
     }
     catch {

package/dist/index.js

@@ -522,7 +522,8 @@ ${bold}DOCS${reset}
             return;
         }
         const stopHook = process.argv.includes('--with-stop-hook');
-        await setupClaudeMd({ stopHook });
+        const sessionEnd = process.argv.includes('--with-session-end');
+        await setupClaudeMd({ stopHook, sessionEnd });
         return;
     }
     // Handle "migrate" subcommand
@@ -584,6 +585,12 @@ ${bold}DOCS${reset}
         await handleReviewCopilotCommand(process.argv.slice(3), parsedArgs.dbPath);
         return;
     }
+    // Handle "memories" subcommand (memory database operations: migrate-legacy, ...)
+    if (process.argv[2] === 'memories') {
+        const { handleMemoriesCommand } = await import('./cli/migrate-legacy.js');
+        await handleMemoriesCommand(process.argv.slice(3));
+        return;
+    }
     // Handle "status" subcommand
     if (process.argv[2] === 'status') {
         const { handleStatusCommand } = await import('./setup/status.js');

package/dist/memory/backup.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Copy the live memories DB to ~/.shieldcortex/backups/ using SQLite's
+ * backup() API (consistent snapshot even with the API server holding an
+ * open WAL connection). Returns the absolute path of the written file.
+ *
+ * Used as a safety net before any destructive maintenance op (prune /
+ * dedupe). The caller surfaces the path back to the user so they can
+ * restore manually if a maintenance run was wrong.
+ */
+export declare function backupMemoriesDb(label: string): Promise<string>;
+/**
+ * List existing backups newest-first. Caller can show this in the UI so
+ * the user knows what restore points exist.
+ */
+export declare function listMemoriesBackups(): Array<{
+    path: string;
+    sizeBytes: number;
+    createdAt: string;
+}>;

package/dist/memory/backup.js

@@ -0,0 +1,47 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { getDatabase } from '../database/init.js';
+/**
+ * Copy the live memories DB to ~/.shieldcortex/backups/ using SQLite's
+ * backup() API (consistent snapshot even with the API server holding an
+ * open WAL connection). Returns the absolute path of the written file.
+ *
+ * Used as a safety net before any destructive maintenance op (prune /
+ * dedupe). The caller surfaces the path back to the user so they can
+ * restore manually if a maintenance run was wrong.
+ */
+export async function backupMemoriesDb(label) {
+    const home = os.homedir();
+    const backupDir = path.join(home, '.shieldcortex', 'backups');
+    if (!fs.existsSync(backupDir)) {
+        fs.mkdirSync(backupDir, { recursive: true });
+    }
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const safeLabel = label.replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 32) || 'backup';
+    const outPath = path.join(backupDir, `memories.${stamp}.${safeLabel}.db`);
+    const db = getDatabase();
+    // better-sqlite3's backup() returns a Promise that resolves once the
+    // page-by-page copy completes. It honours WAL mode so the snapshot is
+    // consistent without locking the API server out.
+    await db.backup(outPath);
+    return outPath;
+}
+/**
+ * List existing backups newest-first. Caller can show this in the UI so
+ * the user knows what restore points exist.
+ */
+export function listMemoriesBackups() {
+    const home = os.homedir();
+    const backupDir = path.join(home, '.shieldcortex', 'backups');
+    if (!fs.existsSync(backupDir))
+        return [];
+    return fs.readdirSync(backupDir)
+        .filter((name) => name.startsWith('memories.') && name.endsWith('.db'))
+        .map((name) => {
+        const full = path.join(backupDir, name);
+        const stat = fs.statSync(full);
+        return { path: full, sizeBytes: stat.size, createdAt: stat.mtime.toISOString() };
+    })
+        .sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+}

package/dist/memory/dedupe-runner.d.ts

@@ -0,0 +1,33 @@
+export interface DedupeOptions {
+    /** Optional project scope. */
+    project?: string;
+    /** When true (default) only count + sample pairs, no merges. */
+    dryRun?: boolean;
+    /** Cap on pairs returned/processed. Default 200. */
+    limit?: number;
+}
+export interface DedupeGroupSummary {
+    keepId: number;
+    keepTitle: string;
+    removeIds: number[];
+    /** Average pairwise similarity score (text-based, 0..1). */
+    similarity: string;
+}
+export interface DedupeResult {
+    options: {
+        project: string | null;
+        dryRun: boolean;
+        limit: number;
+    };
+    pairsFound: number;
+    groups: DedupeGroupSummary[];
+    merged?: number;
+    backupPath?: string;
+}
+/**
+ * Find near-duplicate long-term memories (text-based: title similarity +
+ * content overlap, via the existing findDuplicateMemoryPairs heuristic) and
+ * optionally merge them by keeping the highest-salience representative and
+ * deleting the rest. Backs up the live DB before any merge.
+ */
+export declare function dedupeMemories(rawOptions?: DedupeOptions): Promise<DedupeResult>;

package/dist/memory/dedupe-runner.js

@@ -0,0 +1,103 @@
+import { findDuplicateMemoryPairs } from './consolidate.js';
+import { deleteMemory } from './store.js';
+import { backupMemoriesDb } from './backup.js';
+/**
+ * Group pairs into clusters by treating "duplicate" as a transitive
+ * relation: if A↔B and B↔C are both flagged, A,B,C cluster together. The
+ * representative of each cluster is `recommendedKeepId` (highest salience
+ * tie-broken by most recent).
+ */
+function clusterPairs(pairs) {
+    // Union-find over memory ids.
+    const parent = new Map();
+    const find = (id) => {
+        if (!parent.has(id))
+            parent.set(id, id);
+        let cur = id;
+        while (parent.get(cur) !== cur)
+            cur = parent.get(cur);
+        return cur;
+    };
+    const union = (a, b) => {
+        const ra = find(a);
+        const rb = find(b);
+        if (ra !== rb)
+            parent.set(ra, rb);
+    };
+    const memoryById = new Map();
+    const similarityById = new Map();
+    for (const pair of pairs) {
+        union(pair.memoryA.id, pair.memoryB.id);
+        memoryById.set(pair.memoryA.id, pair.memoryA);
+        memoryById.set(pair.memoryB.id, pair.memoryB);
+        similarityById.set(pair.memoryA.id, pair.similarity);
+        similarityById.set(pair.memoryB.id, pair.similarity);
+    }
+    const clusters = new Map();
+    for (const id of memoryById.keys()) {
+        const root = find(id);
+        if (!clusters.has(root))
+            clusters.set(root, []);
+        clusters.get(root).push(id);
+    }
+    const groups = [];
+    for (const [, ids] of clusters) {
+        if (ids.length < 2)
+            continue;
+        // Highest salience wins; tie → most recent.
+        let keepId = ids[0];
+        for (const id of ids) {
+            const a = memoryById.get(id);
+            const b = memoryById.get(keepId);
+            const aS = a.salience ?? 0;
+            const bS = b.salience ?? 0;
+            const aT = new Date(a.createdAt ?? 0).getTime();
+            const bT = new Date(b.createdAt ?? 0).getTime();
+            if (aS > bS || (aS === bS && aT > bT))
+                keepId = id;
+        }
+        const removeIds = ids.filter((id) => id !== keepId);
+        groups.push({
+            keepId,
+            keepTitle: memoryById.get(keepId).title,
+            removeIds,
+            similarity: similarityById.get(keepId) ?? '',
+        });
+    }
+    return groups.sort((a, b) => b.removeIds.length - a.removeIds.length);
+}
+/**
+ * Find near-duplicate long-term memories (text-based: title similarity +
+ * content overlap, via the existing findDuplicateMemoryPairs heuristic) and
+ * optionally merge them by keeping the highest-salience representative and
+ * deleting the rest. Backs up the live DB before any merge.
+ */
+export async function dedupeMemories(rawOptions = {}) {
+    const options = {
+        project: rawOptions.project ?? null,
+        dryRun: rawOptions.dryRun ?? true,
+        limit: rawOptions.limit ?? 200,
+    };
+    const pairs = findDuplicateMemoryPairs({
+        project: options.project ?? undefined,
+        limit: options.limit,
+    });
+    const groups = clusterPairs(pairs);
+    const result = {
+        options,
+        pairsFound: pairs.length,
+        groups,
+    };
+    if (options.dryRun || groups.length === 0)
+        return result;
+    result.backupPath = await backupMemoriesDb('pre-dedupe');
+    let merged = 0;
+    for (const group of groups) {
+        for (const id of group.removeIds) {
+            if (deleteMemory(id, { type: 'cli', identifier: 'maintenance:dedupe' }))
+                merged++;
+        }
+    }
+    result.merged = merged;
+    return result;
+}

package/dist/memory/fts.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared FTS5 + JSON helpers used across memory store modules.
+ *
+ * Lifted out of store.ts so the memory module split can avoid
+ * circular imports and silent helper duplication.
+ */
+/**
+ * Escape FTS5 query to prevent syntax errors.
+ *
+ * FTS5 interprets:
+ * - "word-word" as "column:value" syntax
+ * - AND, OR, NOT as boolean operators
+ * - &, | as boolean operators
+ *
+ * We quote individual terms to search them literally. Apostrophes are
+ * split on because the porter unicode61 tokenizer treats them as word
+ * separators during indexing ("don't" → "don" + "t"); queries must
+ * split the same way to match indexed tokens.
+ */
+export declare function escapeFts5Query(query: string): string;
+/**
+ * Safely parse JSON with fallback — prevents corrupted DB values from
+ * crashing queries. Returns the fallback for null, undefined, empty
+ * string, or any parse error.
+ */
+export declare function safeJsonParse<T>(value: string | null | undefined, fallback: T): T;

package/dist/memory/fts.js

@@ -0,0 +1,59 @@
+/**
+ * Shared FTS5 + JSON helpers used across memory store modules.
+ *
+ * Lifted out of store.ts so the memory module split can avoid
+ * circular imports and silent helper duplication.
+ */
+/**
+ * Escape FTS5 query to prevent syntax errors.
+ *
+ * FTS5 interprets:
+ * - "word-word" as "column:value" syntax
+ * - AND, OR, NOT as boolean operators
+ * - &, | as boolean operators
+ *
+ * We quote individual terms to search them literally. Apostrophes are
+ * split on because the porter unicode61 tokenizer treats them as word
+ * separators during indexing ("don't" → "don" + "t"); queries must
+ * split the same way to match indexed tokens.
+ */
+export function escapeFts5Query(query) {
+    return query
+        .split(/\s+/)
+        .filter((term) => term.length > 0)
+        .map((term) => {
+        if (term.includes("'")) {
+            const parts = term.split("'").filter((p) => p.length > 0);
+            return parts.map((p) => {
+                if (/[^a-zA-Z0-9_]/.test(p))
+                    return `"${p.replace(/"/g, '""')}"`;
+                return p;
+            }).join(' ');
+        }
+        const upperTerm = term.toUpperCase();
+        if (upperTerm === 'AND' || upperTerm === 'OR' || upperTerm === 'NOT') {
+            return `"${term}"`;
+        }
+        if (/[^a-zA-Z0-9_]/.test(term)) {
+            return `"${term.replace(/"/g, '""')}"`;
+        }
+        return term;
+    })
+        .filter(Boolean)
+        .join(' ');
+}
+/**
+ * Safely parse JSON with fallback — prevents corrupted DB values from
+ * crashing queries. Returns the fallback for null, undefined, empty
+ * string, or any parse error.
+ */
+export function safeJsonParse(value, fallback) {
+    if (!value)
+        return fallback;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return fallback;
+    }
+}