@soleri/core 2.1.0 → 2.5.0

package/src/vault/vault.ts

@@ -1,6 +1,5 @@
-import Database from 'better-sqlite3';
-import { mkdirSync } from 'node:fs';
-import { dirname } from 'node:path';
+import type { PersistenceProvider } from '../persistence/types.js';
+import { SQLitePersistenceProvider } from '../persistence/sqlite-provider.js';
 import type { IntelligenceEntry } from '../intelligence/types.js';
 
 export interface SearchResult {
@@ -39,21 +38,43 @@ export interface MemoryStats {
 }
 
 export class Vault {
-  private db: Database.Database;
+  private provider: PersistenceProvider;
+  private sqliteProvider: SQLitePersistenceProvider | null;
+  private syncManager: import('../cognee/sync-manager.js').CogneeSyncManager | null = null;
 
-  constructor(dbPath: string = ':memory:') {
-    if (dbPath !== ':memory:') mkdirSync(dirname(dbPath), { recursive: true });
-    this.db = new Database(dbPath);
-    this.db.pragma('journal_mode = WAL');
-    this.db.pragma('foreign_keys = ON');
+  /**
+   * Create a Vault with a PersistenceProvider or a SQLite path (backward compat).
+   */
+  constructor(providerOrPath: PersistenceProvider | string = ':memory:') {
+    if (typeof providerOrPath === 'string') {
+      const sqlite = new SQLitePersistenceProvider(providerOrPath);
+      this.provider = sqlite;
+      this.sqliteProvider = sqlite;
+      // SQLite-specific pragmas
+      this.provider.run('PRAGMA journal_mode = WAL');
+      this.provider.run('PRAGMA foreign_keys = ON');
+    } else {
+      this.provider = providerOrPath;
+      this.sqliteProvider =
+        providerOrPath instanceof SQLitePersistenceProvider ? providerOrPath : null;
+    }
     this.initialize();
   }
 
+  setSyncManager(mgr: import('../cognee/sync-manager.js').CogneeSyncManager): void {
+    this.syncManager = mgr;
+  }
+
+  /** Backward-compatible factory. */
+  static createWithSQLite(dbPath: string = ':memory:'): Vault {
+    return new Vault(dbPath);
+  }
+
   private initialize(): void {
-    this.db.exec(`
+    this.provider.execSql(`
       CREATE TABLE IF NOT EXISTS entries (
         id TEXT PRIMARY KEY,
-        type TEXT NOT NULL CHECK(type IN ('pattern', 'anti-pattern', 'rule')),
+        type TEXT NOT NULL CHECK(type IN ('pattern', 'anti-pattern', 'rule', 'playbook')),
         domain TEXT NOT NULL,
         title TEXT NOT NULL,
         severity TEXT NOT NULL CHECK(severity IN ('critical', 'warning', 'suggestion')),
@@ -121,25 +142,87 @@ export class Vault {
         id INTEGER PRIMARY KEY AUTOINCREMENT,
         query TEXT NOT NULL,
         entry_id TEXT NOT NULL,
-        action TEXT NOT NULL CHECK(action IN ('accepted', 'dismissed')),
+        action TEXT NOT NULL CHECK(action IN ('accepted', 'dismissed', 'modified', 'failed')),
+        source TEXT NOT NULL DEFAULT 'search',
+        confidence REAL NOT NULL DEFAULT 0.6,
+        duration INTEGER,
+        context TEXT NOT NULL DEFAULT '{}',
+        reason TEXT,
         created_at INTEGER NOT NULL DEFAULT (unixepoch())
       );
       CREATE INDEX IF NOT EXISTS idx_brain_feedback_query ON brain_feedback(query);
     `);
+    this.migrateBrainSchema();
+    this.migrateTemporalSchema();
+  }
+
+  private migrateTemporalSchema(): void {
+    try {
+      this.provider.run('ALTER TABLE entries ADD COLUMN valid_from INTEGER');
+    } catch {
+      // Column already exists
+    }
+    try {
+      this.provider.run('ALTER TABLE entries ADD COLUMN valid_until INTEGER');
+    } catch {
+      // Column already exists
+    }
+  }
+
+  private migrateBrainSchema(): void {
+    const columns = this.provider.all<{ name: string }>('PRAGMA table_info(brain_feedback)');
+    const hasSource = columns.some((c) => c.name === 'source');
+
+    if (!hasSource && columns.length > 0) {
+      this.provider.transaction(() => {
+        this.provider.run(`
+          CREATE TABLE brain_feedback_new (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            query TEXT NOT NULL,
+            entry_id TEXT NOT NULL,
+            action TEXT NOT NULL CHECK(action IN ('accepted', 'dismissed', 'modified', 'failed')),
+            source TEXT NOT NULL DEFAULT 'search',
+            confidence REAL NOT NULL DEFAULT 0.6,
+            duration INTEGER,
+            context TEXT NOT NULL DEFAULT '{}',
+            reason TEXT,
+            created_at INTEGER NOT NULL DEFAULT (unixepoch())
+          )
+        `);
+        this.provider.run(`
+          INSERT INTO brain_feedback_new (id, query, entry_id, action, created_at)
+            SELECT id, query, entry_id, action, created_at FROM brain_feedback
+        `);
+        this.provider.run('DROP TABLE brain_feedback');
+        this.provider.run('ALTER TABLE brain_feedback_new RENAME TO brain_feedback');
+        this.provider.run(
+          'CREATE INDEX IF NOT EXISTS idx_brain_feedback_query ON brain_feedback(query)',
+        );
+      });
+    }
+
+    try {
+      const sessionCols = this.provider.all<{ name: string }>('PRAGMA table_info(brain_sessions)');
+      if (sessionCols.length > 0 && !sessionCols.some((c) => c.name === 'extracted_at')) {
+        this.provider.run('ALTER TABLE brain_sessions ADD COLUMN extracted_at TEXT');
+      }
+    } catch {
+      // brain_sessions table doesn't exist yet — BrainIntelligence will create it
+    }
   }
 
   seed(entries: IntelligenceEntry[]): number {
-    const upsert = this.db.prepare(`
-      INSERT INTO entries (id,type,domain,title,severity,description,context,example,counter_example,why,tags,applies_to)
-      VALUES (@id,@type,@domain,@title,@severity,@description,@context,@example,@counterExample,@why,@tags,@appliesTo)
+    const sql = `
+      INSERT INTO entries (id,type,domain,title,severity,description,context,example,counter_example,why,tags,applies_to,valid_from,valid_until)
+      VALUES (@id,@type,@domain,@title,@severity,@description,@context,@example,@counterExample,@why,@tags,@appliesTo,@validFrom,@validUntil)
       ON CONFLICT(id) DO UPDATE SET type=excluded.type,domain=excluded.domain,title=excluded.title,severity=excluded.severity,
         description=excluded.description,context=excluded.context,example=excluded.example,counter_example=excluded.counter_example,
-        why=excluded.why,tags=excluded.tags,applies_to=excluded.applies_to,updated_at=unixepoch()
-    `);
-    const tx = this.db.transaction((items: IntelligenceEntry[]) => {
+        why=excluded.why,tags=excluded.tags,applies_to=excluded.applies_to,valid_from=excluded.valid_from,valid_until=excluded.valid_until,updated_at=unixepoch()
+    `;
+    return this.provider.transaction(() => {
       let count = 0;
-      for (const entry of items) {
-        upsert.run({
+      for (const entry of entries) {
+        this.provider.run(sql, {
           id: entry.id,
           type: entry.type,
           domain: entry.domain,
@@ -152,21 +235,31 @@ export class Vault {
           why: entry.why ?? null,
           tags: JSON.stringify(entry.tags),
           appliesTo: JSON.stringify(entry.appliesTo ?? []),
+          validFrom: entry.validFrom ?? null,
+          validUntil: entry.validUntil ?? null,
         });
         count++;
+        if (this.syncManager) {
+          this.syncManager.enqueue('ingest', entry.id, entry);
+        }
       }
       return count;
     });
-    return tx(entries);
   }
 
   search(
     query: string,
-    options?: { domain?: string; type?: string; severity?: string; limit?: number },
+    options?: {
+      domain?: string;
+      type?: string;
+      severity?: string;
+      limit?: number;
+      includeExpired?: boolean;
+    },
   ): SearchResult[] {
     const limit = options?.limit ?? 10;
     const filters: string[] = [];
-    const fp: Record<string, string> = {};
+    const fp: Record<string, unknown> = {};
     if (options?.domain) {
       filters.push('e.domain = @domain');
       fp.domain = options.domain;
@@ -179,13 +272,18 @@ export class Vault {
       filters.push('e.severity = @severity');
       fp.severity = options.severity;
     }
+    if (!options?.includeExpired) {
+      const now = Math.floor(Date.now() / 1000);
+      filters.push('(e.valid_until IS NULL OR e.valid_until > @now)');
+      filters.push('(e.valid_from IS NULL OR e.valid_from <= @now)');
+      fp.now = now;
+    }
     const wc = filters.length > 0 ? `AND ${filters.join(' AND ')}` : '';
     try {
-      const rows = this.db
-        .prepare(
-          `SELECT e.*, -rank as score FROM entries_fts fts JOIN entries e ON e.rowid = fts.rowid WHERE entries_fts MATCH @query ${wc} ORDER BY score DESC LIMIT @limit`,
-        )
-        .all({ query, limit, ...fp }) as Array<Record<string, unknown>>;
+      const rows = this.provider.all<Record<string, unknown>>(
+        `SELECT e.*, -rank as score FROM entries_fts fts JOIN entries e ON e.rowid = fts.rowid WHERE entries_fts MATCH @query ${wc} ORDER BY score DESC LIMIT @limit`,
+        { query, limit, ...fp },
+      );
       return rows.map(rowToSearchResult);
     } catch {
       return [];
@@ -193,9 +291,9 @@ export class Vault {
   }
 
   get(id: string): IntelligenceEntry | null {
-    const row = this.db.prepare('SELECT * FROM entries WHERE id = ?').get(id) as
-      | Record<string, unknown>
-      | undefined;
+    const row = this.provider.get<Record<string, unknown>>('SELECT * FROM entries WHERE id = ?', [
+      id,
+    ]);
     return row ? rowToEntry(row) : null;
   }
 
@@ -206,6 +304,7 @@ export class Vault {
     tags?: string[];
     limit?: number;
     offset?: number;
+    includeExpired?: boolean;
   }): IntelligenceEntry[] {
     const filters: string[] = [];
     const params: Record<string, unknown> = {};
@@ -228,26 +327,29 @@ export class Vault {
       });
       filters.push(`(${c.join(' OR ')})`);
     }
+    if (!options?.includeExpired) {
+      const now = Math.floor(Date.now() / 1000);
+      filters.push('(valid_until IS NULL OR valid_until > @now)');
+      filters.push('(valid_from IS NULL OR valid_from <= @now)');
+      params.now = now;
+    }
     const wc = filters.length > 0 ? `WHERE ${filters.join(' AND ')}` : '';
-    const rows = this.db
-      .prepare(
-        `SELECT * FROM entries ${wc} ORDER BY severity, domain, title LIMIT @limit OFFSET @offset`,
-      )
-      .all({ ...params, limit: options?.limit ?? 50, offset: options?.offset ?? 0 }) as Array<
-      Record<string, unknown>
-    >;
+    const rows = this.provider.all<Record<string, unknown>>(
+      `SELECT * FROM entries ${wc} ORDER BY severity, domain, title LIMIT @limit OFFSET @offset`,
+      { ...params, limit: options?.limit ?? 50, offset: options?.offset ?? 0 },
+    );
     return rows.map(rowToEntry);
   }
 
   stats(): VaultStats {
-    const total = (
-      this.db.prepare('SELECT COUNT(*) as count FROM entries').get() as { count: number }
-    ).count;
+    const total = this.provider.get<{ count: number }>(
+      'SELECT COUNT(*) as count FROM entries',
+    )!.count;
     return {
       totalEntries: total,
-      byType: gc(this.db, 'type'),
-      byDomain: gc(this.db, 'domain'),
-      bySeverity: gc(this.db, 'severity'),
+      byType: gc(this.provider, 'type'),
+      byDomain: gc(this.provider, 'domain'),
+      bySeverity: gc(this.provider, 'severity'),
     };
   }
 
@@ -255,28 +357,186 @@ export class Vault {
     this.seed([entry]);
   }
   remove(id: string): boolean {
-    return this.db.prepare('DELETE FROM entries WHERE id = ?').run(id).changes > 0;
+    const deleted = this.provider.run('DELETE FROM entries WHERE id = ?', [id]).changes > 0;
+    if (deleted && this.syncManager) {
+      this.syncManager.enqueue('delete', id);
+    }
+    return deleted;
+  }
+
+  update(
+    id: string,
+    fields: Partial<
+      Pick<
+        IntelligenceEntry,
+        | 'title'
+        | 'description'
+        | 'context'
+        | 'example'
+        | 'counterExample'
+        | 'why'
+        | 'tags'
+        | 'appliesTo'
+        | 'severity'
+        | 'type'
+        | 'domain'
+        | 'validFrom'
+        | 'validUntil'
+      >
+    >,
+  ): IntelligenceEntry | null {
+    const existing = this.get(id);
+    if (!existing) return null;
+    const merged: IntelligenceEntry = { ...existing, ...fields };
+    this.seed([merged]);
+    return this.get(id);
+  }
+
+  setTemporal(id: string, validFrom?: number, validUntil?: number): boolean {
+    const sets: string[] = [];
+    const params: Record<string, unknown> = { id };
+    if (validFrom !== undefined) {
+      sets.push('valid_from = @validFrom');
+      params.validFrom = validFrom;
+    }
+    if (validUntil !== undefined) {
+      sets.push('valid_until = @validUntil');
+      params.validUntil = validUntil;
+    }
+    if (sets.length === 0) return false;
+    sets.push('updated_at = unixepoch()');
+    return (
+      this.provider.run(`UPDATE entries SET ${sets.join(', ')} WHERE id = @id`, params).changes > 0
+    );
+  }
+
+  findExpiring(withinDays: number): IntelligenceEntry[] {
+    const now = Math.floor(Date.now() / 1000);
+    const cutoff = now + withinDays * 86400;
+    const rows = this.provider.all<Record<string, unknown>>(
+      'SELECT * FROM entries WHERE valid_until IS NOT NULL AND valid_until > @now AND valid_until <= @cutoff ORDER BY valid_until ASC',
+      { now, cutoff },
+    );
+    return rows.map(rowToEntry);
+  }
+
+  findExpired(limit: number = 50): IntelligenceEntry[] {
+    const now = Math.floor(Date.now() / 1000);
+    const rows = this.provider.all<Record<string, unknown>>(
+      'SELECT * FROM entries WHERE valid_until IS NOT NULL AND valid_until <= @now ORDER BY valid_until DESC LIMIT @limit',
+      { now, limit },
+    );
+    return rows.map(rowToEntry);
+  }
+
+  bulkRemove(ids: string[]): number {
+    return this.provider.transaction(() => {
+      let count = 0;
+      for (const id of ids) {
+        count += this.provider.run('DELETE FROM entries WHERE id = ?', [id]).changes;
+        if (this.syncManager) {
+          this.syncManager.enqueue('delete', id);
+        }
+      }
+      return count;
+    });
+  }
+
+  getTags(): Array<{ tag: string; count: number }> {
+    const rows = this.provider.all<{ tags: string }>('SELECT tags FROM entries');
+    const counts = new Map<string, number>();
+    for (const row of rows) {
+      const tags: string[] = JSON.parse(row.tags || '[]');
+      for (const tag of tags) {
+        counts.set(tag, (counts.get(tag) ?? 0) + 1);
+      }
+    }
+    return Array.from(counts.entries())
+      .map(([tag, count]) => ({ tag, count }))
+      .sort((a, b) => b.count - a.count);
+  }
+
+  getDomains(): Array<{ domain: string; count: number }> {
+    return this.provider.all<{ domain: string; count: number }>(
+      'SELECT domain, COUNT(*) as count FROM entries GROUP BY domain ORDER BY count DESC',
+    );
+  }
+
+  getRecent(limit: number = 20): IntelligenceEntry[] {
+    const rows = this.provider.all<Record<string, unknown>>(
+      'SELECT * FROM entries ORDER BY updated_at DESC LIMIT ?',
+      [limit],
+    );
+    return rows.map(rowToEntry);
+  }
+
+  exportAll(): { entries: IntelligenceEntry[]; exportedAt: number; count: number } {
+    const rows = this.provider.all<Record<string, unknown>>(
+      'SELECT * FROM entries ORDER BY domain, title',
+    );
+    const entries = rows.map(rowToEntry);
+    return { entries, exportedAt: Math.floor(Date.now() / 1000), count: entries.length };
+  }
+
+  getAgeReport(): {
+    total: number;
+    buckets: Array<{ label: string; count: number; minDays: number; maxDays: number }>;
+    oldestTimestamp: number | null;
+    newestTimestamp: number | null;
+  } {
+    const rows = this.provider.all<{ created_at: number; updated_at: number }>(
+      'SELECT created_at, updated_at FROM entries',
+    );
+    const now = Math.floor(Date.now() / 1000);
+    const bucketDefs = [
+      { label: 'today', minDays: 0, maxDays: 1 },
+      { label: 'this_week', minDays: 1, maxDays: 7 },
+      { label: 'this_month', minDays: 7, maxDays: 30 },
+      { label: 'this_quarter', minDays: 30, maxDays: 90 },
+      { label: 'older', minDays: 90, maxDays: Infinity },
+    ];
+    const counts = new Array(bucketDefs.length).fill(0) as number[];
+    let oldest: number | null = null;
+    let newest: number | null = null;
+    for (const row of rows) {
+      const ts = row.created_at;
+      if (oldest === null || ts < oldest) oldest = ts;
+      if (newest === null || ts > newest) newest = ts;
+      const ageDays = (now - ts) / 86400;
+      for (let i = 0; i < bucketDefs.length; i++) {
+        if (ageDays >= bucketDefs[i].minDays && ageDays < bucketDefs[i].maxDays) {
+          counts[i]++;
+          break;
+        }
+      }
+    }
+    return {
+      total: rows.length,
+      buckets: bucketDefs.map((b, i) => ({ ...b, count: counts[i] })),
+      oldestTimestamp: oldest,
+      newestTimestamp: newest,
+    };
   }
 
   registerProject(path: string, name?: string): ProjectInfo {
     const projectName = name ?? path.replace(/\/$/, '').split('/').pop() ?? path;
     const existing = this.getProject(path);
     if (existing) {
-      this.db
-        .prepare(
-          'UPDATE projects SET last_seen_at = unixepoch(), session_count = session_count + 1 WHERE path = ?',
-        )
-        .run(path);
+      this.provider.run(
+        'UPDATE projects SET last_seen_at = unixepoch(), session_count = session_count + 1 WHERE path = ?',
+        [path],
+      );
       return this.getProject(path)!;
     }
-    this.db.prepare('INSERT INTO projects (path, name) VALUES (?, ?)').run(path, projectName);
+    this.provider.run('INSERT INTO projects (path, name) VALUES (?, ?)', [path, projectName]);
     return this.getProject(path)!;
   }
 
   getProject(path: string): ProjectInfo | null {
-    const row = this.db.prepare('SELECT * FROM projects WHERE path = ?').get(path) as
-      | Record<string, unknown>
-      | undefined;
+    const row = this.provider.get<Record<string, unknown>>(
+      'SELECT * FROM projects WHERE path = ?',
+      [path],
+    );
     if (!row) return null;
     return {
       path: row.path as string,
@@ -288,9 +548,9 @@ export class Vault {
   }
 
   listProjects(): ProjectInfo[] {
-    const rows = this.db
-      .prepare('SELECT * FROM projects ORDER BY last_seen_at DESC')
-      .all() as Array<Record<string, unknown>>;
+    const rows = this.provider.all<Record<string, unknown>>(
+      'SELECT * FROM projects ORDER BY last_seen_at DESC',
+    );
     return rows.map((row) => ({
       path: row.path as string,
       name: row.name as string,
@@ -302,11 +562,9 @@ export class Vault {
 
   captureMemory(memory: Omit<Memory, 'id' | 'createdAt' | 'archivedAt'>): Memory {
     const id = `mem-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-    this.db
-      .prepare(
-        `INSERT INTO memories (id, project_path, type, context, summary, topics, files_modified, tools_used) VALUES (@id, @projectPath, @type, @context, @summary, @topics, @filesModified, @toolsUsed)`,
-      )
-      .run({
+    this.provider.run(
+      `INSERT INTO memories (id, project_path, type, context, summary, topics, files_modified, tools_used) VALUES (@id, @projectPath, @type, @context, @summary, @topics, @filesModified, @toolsUsed)`,
+      {
         id,
         projectPath: memory.projectPath,
         type: memory.type,
@@ -315,7 +573,8 @@ export class Vault {
         topics: JSON.stringify(memory.topics),
         filesModified: JSON.stringify(memory.filesModified),
         toolsUsed: JSON.stringify(memory.toolsUsed),
-      });
+      },
+    );
     return this.getMemory(id)!;
   }
 
@@ -336,11 +595,10 @@ export class Vault {
     }
     const wc = filters.length > 0 ? `AND ${filters.join(' AND ')}` : '';
     try {
-      const rows = this.db
-        .prepare(
-          `SELECT m.* FROM memories_fts fts JOIN memories m ON m.rowid = fts.rowid WHERE memories_fts MATCH @query ${wc} ORDER BY rank LIMIT @limit`,
-        )
-        .all({ query, limit, ...fp }) as Array<Record<string, unknown>>;
+      const rows = this.provider.all<Record<string, unknown>>(
+        `SELECT m.* FROM memories_fts fts JOIN memories m ON m.rowid = fts.rowid WHERE memories_fts MATCH @query ${wc} ORDER BY rank LIMIT @limit`,
+        { query, limit, ...fp },
+      );
       return rows.map(rowToMemory);
     } catch {
       return [];
@@ -364,30 +622,23 @@ export class Vault {
       params.projectPath = options.projectPath;
     }
     const wc = `WHERE ${filters.join(' AND ')}`;
-    const rows = this.db
-      .prepare(`SELECT * FROM memories ${wc} ORDER BY created_at DESC LIMIT @limit OFFSET @offset`)
-      .all({ ...params, limit: options?.limit ?? 50, offset: options?.offset ?? 0 }) as Array<
-      Record<string, unknown>
-    >;
+    const rows = this.provider.all<Record<string, unknown>>(
+      `SELECT * FROM memories ${wc} ORDER BY created_at DESC LIMIT @limit OFFSET @offset`,
+      { ...params, limit: options?.limit ?? 50, offset: options?.offset ?? 0 },
+    );
     return rows.map(rowToMemory);
   }
 
   memoryStats(): MemoryStats {
-    const total = (
-      this.db.prepare('SELECT COUNT(*) as count FROM memories WHERE archived_at IS NULL').get() as {
-        count: number;
-      }
-    ).count;
-    const byTypeRows = this.db
-      .prepare(
-        'SELECT type as key, COUNT(*) as count FROM memories WHERE archived_at IS NULL GROUP BY type',
-      )
-      .all() as Array<{ key: string; count: number }>;
-    const byProjectRows = this.db
-      .prepare(
-        'SELECT project_path as key, COUNT(*) as count FROM memories WHERE archived_at IS NULL GROUP BY project_path',
-      )
-      .all() as Array<{ key: string; count: number }>;
+    const total = this.provider.get<{ count: number }>(
+      'SELECT COUNT(*) as count FROM memories WHERE archived_at IS NULL',
+    )!.count;
+    const byTypeRows = this.provider.all<{ key: string; count: number }>(
+      'SELECT type as key, COUNT(*) as count FROM memories WHERE archived_at IS NULL GROUP BY type',
+    );
+    const byProjectRows = this.provider.all<{ key: string; count: number }>(
+      'SELECT project_path as key, COUNT(*) as count FROM memories WHERE archived_at IS NULL GROUP BY project_path',
+    );
     return {
       total,
       byType: Object.fromEntries(byTypeRows.map((r) => [r.key, r.count])),
@@ -396,25 +647,249 @@ export class Vault {
   }
 
   getMemory(id: string): Memory | null {
-    const row = this.db.prepare('SELECT * FROM memories WHERE id = ?').get(id) as
-      | Record<string, unknown>
-      | undefined;
+    const row = this.provider.get<Record<string, unknown>>('SELECT * FROM memories WHERE id = ?', [
+      id,
+    ]);
     return row ? rowToMemory(row) : null;
   }
 
-  getDb(): Database.Database {
-    return this.db;
+  deleteMemory(id: string): boolean {
+    return this.provider.run('DELETE FROM memories WHERE id = ?', [id]).changes > 0;
+  }
+
+  memoryStatsDetailed(options?: {
+    projectPath?: string;
+    fromDate?: number;
+    toDate?: number;
+  }): MemoryStats & { oldest: number | null; newest: number | null; archivedCount: number } {
+    const filters: string[] = [];
+    const params: Record<string, unknown> = {};
+    if (options?.projectPath) {
+      filters.push('project_path = @projectPath');
+      params.projectPath = options.projectPath;
+    }
+    if (options?.fromDate) {
+      filters.push('created_at >= @fromDate');
+      params.fromDate = options.fromDate;
+    }
+    if (options?.toDate) {
+      filters.push('created_at <= @toDate');
+      params.toDate = options.toDate;
+    }
+    const wc = filters.length > 0 ? `WHERE ${filters.join(' AND ')}` : '';
+
+    const total = this.provider.get<{ count: number }>(
+      `SELECT COUNT(*) as count FROM memories ${wc}${wc ? ' AND' : ' WHERE'} archived_at IS NULL`,
+      params,
+    )!.count;
+
+    const archivedCount = this.provider.get<{ count: number }>(
+      `SELECT COUNT(*) as count FROM memories ${wc}${wc ? ' AND' : ' WHERE'} archived_at IS NOT NULL`,
+      params,
+    )!.count;
+
+    const byTypeRows = this.provider.all<{ key: string; count: number }>(
+      `SELECT type as key, COUNT(*) as count FROM memories ${wc}${wc ? ' AND' : ' WHERE'} archived_at IS NULL GROUP BY type`,
+      params,
+    );
+
+    const byProjectRows = this.provider.all<{ key: string; count: number }>(
+      `SELECT project_path as key, COUNT(*) as count FROM memories ${wc}${wc ? ' AND' : ' WHERE'} archived_at IS NULL GROUP BY project_path`,
+      params,
+    );
+
+    const dateRange = this.provider.get<{ oldest: number | null; newest: number | null }>(
+      `SELECT MIN(created_at) as oldest, MAX(created_at) as newest FROM memories ${wc}${wc ? ' AND' : ' WHERE'} archived_at IS NULL`,
+      params,
+    )!;
+
+    return {
+      total,
+      byType: Object.fromEntries(byTypeRows.map((r) => [r.key, r.count])),
+      byProject: Object.fromEntries(byProjectRows.map((r) => [r.key, r.count])),
+      oldest: dateRange.oldest,
+      newest: dateRange.newest,
+      archivedCount,
+    };
+  }
+
+  exportMemories(options?: {
+    projectPath?: string;
+    type?: string;
+    includeArchived?: boolean;
+  }): Memory[] {
+    const filters: string[] = [];
+    const params: Record<string, unknown> = {};
+    if (!options?.includeArchived) {
+      filters.push('archived_at IS NULL');
+    }
+    if (options?.projectPath) {
+      filters.push('project_path = @projectPath');
+      params.projectPath = options.projectPath;
+    }
+    if (options?.type) {
+      filters.push('type = @type');
+      params.type = options.type;
+    }
+    const wc = filters.length > 0 ? `WHERE ${filters.join(' AND ')}` : '';
+    const rows = this.provider.all<Record<string, unknown>>(
+      `SELECT * FROM memories ${wc} ORDER BY created_at ASC`,
+      Object.keys(params).length > 0 ? params : undefined,
+    );
+    return rows.map(rowToMemory);
+  }
+
+  importMemories(memories: Memory[]): { imported: number; skipped: number } {
+    const sql = `
+      INSERT OR IGNORE INTO memories (id, project_path, type, context, summary, topics, files_modified, tools_used, created_at, archived_at)
+      VALUES (@id, @projectPath, @type, @context, @summary, @topics, @filesModified, @toolsUsed, @createdAt, @archivedAt)
+    `;
+    let imported = 0;
+    let skipped = 0;
+    this.provider.transaction(() => {
+      for (const m of memories) {
+        const result = this.provider.run(sql, {
+          id: m.id,
+          projectPath: m.projectPath,
+          type: m.type,
+          context: m.context,
+          summary: m.summary,
+          topics: JSON.stringify(m.topics),
+          filesModified: JSON.stringify(m.filesModified),
+          toolsUsed: JSON.stringify(m.toolsUsed),
+          createdAt: m.createdAt,
+          archivedAt: m.archivedAt,
+        });
+        if (result.changes > 0) imported++;
+        else skipped++;
+      }
+    });
+    return { imported, skipped };
+  }
+
+  pruneMemories(olderThanDays: number): { pruned: number } {
+    const cutoff = Math.floor(Date.now() / 1000) - olderThanDays * 86400;
+    const result = this.provider.run(
+      'DELETE FROM memories WHERE created_at < ? AND archived_at IS NULL',
+      [cutoff],
+    );
+    return { pruned: result.changes };
+  }
+
+  deduplicateMemories(): { removed: number; groups: Array<{ kept: string; removed: string[] }> } {
+    const dupeRows = this.provider.all<{ id1: string; id2: string }>(`
+        SELECT m1.id as id1, m2.id as id2
+        FROM memories m1
+        JOIN memories m2 ON m1.summary = m2.summary
+          AND m1.project_path = m2.project_path
+          AND m1.type = m2.type
+          AND m1.id < m2.id
+          AND m1.archived_at IS NULL
+          AND m2.archived_at IS NULL
+      `);
+
+    const groupMap = new Map<string, Set<string>>();
+    for (const row of dupeRows) {
+      if (!groupMap.has(row.id1)) groupMap.set(row.id1, new Set());
+      groupMap.get(row.id1)!.add(row.id2);
+    }
+
+    const groups: Array<{ kept: string; removed: string[] }> = [];
+    const toRemove = new Set<string>();
+    for (const [kept, removedSet] of groupMap) {
+      const removed = [...removedSet].filter((id) => !toRemove.has(id));
+      if (removed.length > 0) {
+        groups.push({ kept, removed });
+        for (const id of removed) toRemove.add(id);
+      }
+    }
+
+    if (toRemove.size > 0) {
+      this.provider.transaction(() => {
+        for (const id of toRemove) {
+          this.provider.run('DELETE FROM memories WHERE id = ?', [id]);
+        }
+      });
+    }
+
+    return { removed: toRemove.size, groups };
+  }
+
+  memoryTopics(): Array<{ topic: string; count: number }> {
+    const rows = this.provider.all<{ topics: string }>(
+      'SELECT topics FROM memories WHERE archived_at IS NULL',
+    );
+
+    const topicCounts = new Map<string, number>();
+    for (const row of rows) {
+      const topics: string[] = JSON.parse(row.topics || '[]');
+      for (const topic of topics) {
+        topicCounts.set(topic, (topicCounts.get(topic) ?? 0) + 1);
+      }
+    }
+
+    return [...topicCounts.entries()]
+      .map(([topic, count]) => ({ topic, count }))
+      .sort((a, b) => b.count - a.count);
+  }
+
+  memoriesByProject(): Array<{ project: string; count: number; memories: Memory[] }> {
+    const rows = this.provider.all<{ project: string; count: number }>(
+      'SELECT project_path as project, COUNT(*) as count FROM memories WHERE archived_at IS NULL GROUP BY project_path ORDER BY count DESC',
+    );
+
+    return rows.map((row) => {
+      const memories = this.provider.all<Record<string, unknown>>(
+        'SELECT * FROM memories WHERE project_path = ? AND archived_at IS NULL ORDER BY created_at DESC',
+        [row.project],
+      );
+      return {
+        project: row.project,
+        count: row.count,
+        memories: memories.map(rowToMemory),
+      };
+    });
+  }
+
+  /**
+   * Rebuild the FTS5 index for the entries table.
+   * Useful after bulk operations or if the index gets out of sync.
+   */
+  rebuildFtsIndex(): void {
+    try {
+      this.provider.run("INSERT INTO entries_fts(entries_fts) VALUES('rebuild')");
+    } catch {
+      // Graceful degradation — FTS rebuild failed (e.g. table doesn't exist yet)
+    }
+  }
+
+  /**
+   * Get the underlying persistence provider.
+   */
+  getProvider(): PersistenceProvider {
+    return this.provider;
+  }
+
+  /**
+   * Get the raw better-sqlite3 Database (backward compat).
+   * Throws if the provider is not SQLite.
+   */
+  getDb(): import('better-sqlite3').Database {
+    if (this.sqliteProvider) {
+      return this.sqliteProvider.getDatabase();
+    }
+    throw new Error('getDb() is only available with SQLite provider');
   }
 
   close(): void {
-    this.db.close();
+    this.provider.close();
   }
 }
 
-function gc(db: Database.Database, col: string): Record<string, number> {
-  const rows = db
-    .prepare(`SELECT ${col} as key, COUNT(*) as count FROM entries GROUP BY ${col}`)
-    .all() as Array<{ key: string; count: number }>;
+function gc(provider: PersistenceProvider, col: string): Record<string, number> {
+  const rows = provider.all<{ key: string; count: number }>(
+    `SELECT ${col} as key, COUNT(*) as count FROM entries GROUP BY ${col}`,
+  );
   return Object.fromEntries(rows.map((r) => [r.key, r.count]));
 }
 
@@ -432,6 +907,8 @@ function rowToEntry(row: Record<string, unknown>): IntelligenceEntry {
     why: (row.why as string) ?? undefined,
     tags: JSON.parse((row.tags as string) || '[]'),
     appliesTo: JSON.parse((row.applies_to as string) || '[]'),
+    validFrom: (row.valid_from as number) ?? undefined,
+    validUntil: (row.valid_until as number) ?? undefined,
   };
 }