@monoes/memory 1.0.10 → 1.0.12

package/dist/sqlite-backend.js

@@ -1,18 +1,27 @@
 /**
- * SQLite Memory Backend
+ * SQLite Memory Backend (better-sqlite3)
  *
- * Provides structured storage for memory entries using SQLite.
- * Optimized for ACID transactions, exact matches, and complex queries.
- * Part of ADR-009: Hybrid Memory Backend (SQLite + LanceDB)
+ * A thin driver-selecting wrapper around SqlBackend, which holds all the
+ * behaviour. This file previously carried a full ~930-line IMemoryBackend
+ * implementation that was near-duplicated in sqljs-backend.ts; the two drifted
+ * into different schemas and different query semantics. See sql-backend.ts.
+ *
+ * The class name and config shape are unchanged — this is the published API.
  *
  * @module v1/memory/sqlite-backend
  */
-import { EventEmitter } from 'node:events';
-import Database from 'better-sqlite3';
-import { cosineSimilarity } from './math-utils.js';
-/**
- * Default configuration values
- */
+// better-sqlite3 is an OPTIONAL dependency — sql.js is the documented fallback,
+// and database-provider.ts recommends it outright on Windows, where node-gyp
+// routinely fails to build native modules. This import must therefore be lazy.
+//
+// It used to be a static top-level import, and because index.ts re-exports
+// SQLiteBackend, that made `import '@monoes/memory'` throw
+// ERR_MODULE_NOT_FOUND for anyone without better-sqlite3 — the whole package,
+// including the pure-WASM sql.js path, was unusable in exactly the situation
+// the fallback exists for. Local test suites never caught it because
+// better-sqlite3 is always installed here.
+import { SqlBackend } from './sql-backend.js';
+import { BetterSqliteDriver } from './sql-driver.js';
 const DEFAULT_CONFIG = {
     databasePath: ':memory:',
     walMode: true,
@@ -22,729 +31,48 @@ const DEFAULT_CONFIG = {
     verbose: false,
 };
 /**
- * SQLite Backend for Structured Memory Storage
+ * SQLite backend for structured memory storage.
  *
- * Provides:
- * - ACID transactions for data consistency
- * - Efficient indexing for exact matches and prefix queries
- * - Full-text search capabilities
- * - Complex SQL queries with joins and aggregations
- * - Persistent storage with WAL mode
+ * Provides ACID transactions, indexed lookups, and persistent storage with
+ * WAL mode. Behaviour lives in SqlBackend; this class supplies the driver.
  */
-export class SQLiteBackend extends EventEmitter {
-    config;
-    db = null;
-    initialized = false;
-    // Performance tracking
-    stats = {
-        queryCount: 0,
-        totalQueryTime: 0,
-        writeCount: 0,
-        totalWriteTime: 0,
-    };
-    // Cached prepared statements — prepared once in initialize() to avoid N+1 re-prepare
-    stmtGetEmbedding = null;
-    stmtInsertEntry = null;
-    stmtInsertEmbedding = null;
-    stmtDeleteTags = null;
-    stmtInsertTag = null;
-    // Debounce counter for checkAndPromoteEntry (H2: avoid full-table purge on every get)
-    _readCount = 0;
+export class SQLiteBackend extends SqlBackend {
+    sqliteConfig;
     constructor(config = {}) {
-        super();
-        this.config = { ...DEFAULT_CONFIG, ...config };
-    }
-    /**
-     * Initialize the SQLite backend
-     */
-    async initialize() {
-        if (this.initialized)
-            return;
-        // Open database connection
-        this.db = new Database(this.config.databasePath, {
-            verbose: this.config.verbose ? console.log : undefined,
+        const merged = { ...DEFAULT_CONFIG, ...config };
+        super({
+            defaultNamespace: merged.defaultNamespace,
+            embeddingGenerator: merged.embeddingGenerator,
+            maxEntries: merged.maxEntries,
+            verbose: merged.verbose,
         });
-        // Enable WAL mode for better concurrency
-        if (this.config.walMode) {
-            this.db.pragma('journal_mode = WAL');
-        }
-        // Enable FK enforcement — required for ON DELETE CASCADE to fire
-        this.db.pragma('foreign_keys = ON');
-        // Performance optimizations
-        if (this.config.optimize) {
-            this.db.pragma('synchronous = NORMAL');
-            this.db.pragma('cache_size = 10000');
-            this.db.pragma('temp_store = MEMORY');
-        }
-        // Create schema
-        this.createSchema();
-        // Pre-compile hot-path statements to avoid N+1 re-prepare
-        this.stmtGetEmbedding = this.db.prepare('SELECT embedding FROM memory_embeddings WHERE entry_id = ?');
-        this.stmtInsertEntry = this.db.prepare(`
-      INSERT OR REPLACE INTO memory_entries (
-        id, key, content, type, namespace, tags, metadata,
-        owner_id, access_level, created_at, updated_at, expires_at,
-        event_at, version, "references", access_count, last_accessed_at
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-    `);
-        this.stmtInsertEmbedding = this.db.prepare('INSERT OR REPLACE INTO memory_embeddings (entry_id, embedding) VALUES (?, ?)');
-        this.stmtDeleteTags = this.db.prepare('DELETE FROM memory_entry_tags WHERE entry_id = ?');
-        this.stmtInsertTag = this.db.prepare('INSERT OR IGNORE INTO memory_entry_tags (entry_id, tag) VALUES (?, ?)');
-        this.initialized = true;
-        this.emit('initialized');
-    }
-    /**
-     * Shutdown the backend
-     */
-    async shutdown() {
-        if (!this.initialized || !this.db)
-            return;
-        // Optimize database before closing
-        if (this.config.optimize) {
-            this.db.pragma('optimize');
-        }
-        this.db.close();
-        this.db = null;
-        this.stmtGetEmbedding = null;
-        this.stmtInsertEntry = null;
-        this.stmtInsertEmbedding = null;
-        this.stmtDeleteTags = null;
-        this.stmtInsertTag = null;
-        this.initialized = false;
-        this.emit('shutdown');
-    }
-    /**
-     * Store a memory entry
-     */
-    async store(entry) {
-        this.ensureInitialized();
-        const startTime = performance.now();
-        this.validateTags(entry.tags);
-        const doStore = this.db.transaction((e) => {
-            // Read existing embedding BEFORE INSERT OR REPLACE fires CASCADE and deletes it
-            let embeddingToStore = e.embedding;
-            if (!embeddingToStore) {
-                const existingEmb = this.stmtGetEmbedding.get(e.id);
-                if (existingEmb?.embedding) {
-                    const buf = existingEmb.embedding;
-                    embeddingToStore = new Float32Array(buf.buffer, buf.byteOffset, buf.byteLength / 4);
-                }
-            }
-            this.stmtInsertEntry.run(e.id, e.key, e.content, e.type, e.namespace, JSON.stringify(e.tags), JSON.stringify(e.metadata), e.ownerId || null, e.accessLevel, e.createdAt, e.updatedAt, e.expiresAt || null, e.eventAt ?? null, e.version, JSON.stringify(e.references), e.accessCount, e.lastAccessedAt);
-            this.stmtDeleteTags.run(e.id);
-            for (const tag of e.tags) {
-                this.stmtInsertTag.run(e.id, tag);
-            }
-            if (embeddingToStore) {
-                this.stmtInsertEmbedding.run(e.id, Buffer.from(embeddingToStore.buffer, embeddingToStore.byteOffset, embeddingToStore.byteLength));
-            }
-        });
-        doStore(entry);
-        const duration = performance.now() - startTime;
-        this.stats.writeCount++;
-        this.stats.totalWriteTime += duration;
-        this.emit('entry:stored', { id: entry.id, duration });
-    }
-    /**
-     * Get a memory entry by ID
-     */
-    async get(id, agentId) {
-        this.ensureInitialized();
-        const stmt = this.db.prepare('SELECT * FROM memory_entries WHERE id = ?');
-        const row = stmt.get(id);
-        if (!row)
-            return null;
-        // Collaborative memory promotion: track per-agent reads for auto-promotion
-        // Source: https://arxiv.org/abs/2505.18279
-        const AGENT_ID_RE = /^[a-zA-Z0-9_-]{1,128}$/;
-        if (agentId && AGENT_ID_RE.test(agentId)) {
-            try {
-                this.db.prepare('INSERT OR IGNORE INTO agent_reads (entry_id, agent_id, read_at) VALUES (?, ?, ?)').run(id, agentId, Date.now());
-                // Debounce: run full-table purge only every 1000 reads (H2)
-                this._readCount++;
-                if (this._readCount % 1000 === 0) {
-                    void this.checkAndPromoteEntry(id);
-                }
-            }
-            catch { /* non-critical */ }
-        }
-        return this.rowToEntry(row);
-    }
-    /**
-     * Auto-promote an entry's access_level to 'team' when 3+ distinct agents
-     * have read it within the past 24 hours.
-     * Source: https://arxiv.org/abs/2505.18279
-     */
-    checkAndPromoteEntry(entryId) {
-        if (!this.db)
-            return;
-        const cutoff = Date.now() - 24 * 60 * 60 * 1000;
-        // Purge stale read records to keep table size bounded
-        this.db.prepare('DELETE FROM agent_reads WHERE read_at <= ?').run(cutoff);
-        const countRow = this.db.prepare('SELECT COUNT(DISTINCT agent_id) as cnt FROM agent_reads WHERE entry_id = ? AND read_at > ?').get(entryId, cutoff);
-        if ((countRow?.cnt ?? 0) >= 3) {
-            this.db.prepare("UPDATE memory_entries SET access_level = 'team' WHERE id = ? AND access_level = 'private'").run(entryId);
-        }
-    }
-    /**
-     * Get a memory entry by key within a namespace
-     */
-    async getByKey(namespace, key) {
-        this.ensureInitialized();
-        const stmt = this.db.prepare(`
-      SELECT * FROM memory_entries
-      WHERE namespace = ? AND key = ?
-    `);
-        const row = stmt.get(namespace, key);
-        if (!row)
-            return null;
-        return this.rowToEntry(row);
-    }
-    /**
-     * Update a memory entry
-     */
-    async update(id, update) {
-        this.ensureInitialized();
-        const entry = await this.get(id);
-        if (!entry)
-            return null;
-        // Apply updates
-        if (update.content !== undefined)
-            entry.content = update.content;
-        if (update.tags !== undefined)
-            entry.tags = update.tags;
-        if (update.metadata !== undefined) {
-            entry.metadata = { ...entry.metadata, ...update.metadata };
-        }
-        if (update.accessLevel !== undefined)
-            entry.accessLevel = update.accessLevel;
-        if (update.expiresAt !== undefined)
-            entry.expiresAt = update.expiresAt;
-        if (update.references !== undefined)
-            entry.references = update.references;
-        entry.updatedAt = Date.now();
-        entry.version++;
-        // Store updated entry
-        await this.store(entry);
-        this.emit('entry:updated', { id });
-        return entry;
+        this.sqliteConfig = merged;
     }
-    /**
-     * Delete a memory entry
-     */
-    async delete(id) {
-        this.ensureInitialized();
-        const deleteEntry = this.db.prepare('DELETE FROM memory_entries WHERE id = ?');
-        // Explicit tag cleanup before entry delete (belt-and-suspenders with CASCADE)
-        this.stmtDeleteTags.run(id);
-        const result = deleteEntry.run(id);
-        if (result.changes > 0) {
-            this.emit('entry:deleted', { id });
-            return true;
-        }
-        return false;
-    }
-    /**
-     * Query memory entries with filters
-     */
-    async query(query) {
-        this.ensureInitialized();
-        const startTime = performance.now();
-        let sql = 'SELECT * FROM memory_entries WHERE 1=1';
-        const params = [];
-        // Build WHERE clauses
-        if (query.namespace) {
-            sql += ' AND namespace = ?';
-            params.push(query.namespace);
-        }
-        if (query.key) {
-            sql += ' AND key = ?';
-            params.push(query.key);
-        }
-        if (query.keyPrefix) {
-            sql += ' AND key LIKE ?';
-            params.push(`${query.keyPrefix}%`);
-        }
-        if (query.memoryType) {
-            sql += ' AND type = ?';
-            params.push(query.memoryType);
-        }
-        if (query.accessLevel) {
-            sql += ' AND access_level = ?';
-            params.push(query.accessLevel);
-        }
-        if (query.ownerId) {
-            sql += ' AND owner_id = ?';
-            params.push(query.ownerId);
-        }
-        if (query.createdAfter) {
-            sql += ' AND created_at >= ?';
-            params.push(query.createdAfter);
-        }
-        if (query.createdBefore) {
-            sql += ' AND created_at <= ?';
-            params.push(query.createdBefore);
-        }
-        if (query.updatedAfter) {
-            sql += ' AND updated_at >= ?';
-            params.push(query.updatedAfter);
-        }
-        if (query.updatedBefore) {
-            sql += ' AND updated_at <= ?';
-            params.push(query.updatedBefore);
-        }
-        // Bi-temporal event-time filters (arXiv:2501.13956 — Zep/Graphiti)
-        if (query.eventAfter) {
-            sql += ' AND event_at >= ?';
-            params.push(query.eventAfter);
-        }
-        if (query.eventBefore) {
-            sql += ' AND event_at <= ?';
-            params.push(query.eventBefore);
-        }
-        if (!query.includeExpired) {
-            sql += ' AND (expires_at IS NULL OR expires_at > ?)';
-            params.push(Date.now());
-        }
-        // Tag filtering — uses indexed memory_entry_tags table (no json_each scan)
-        if (query.tags && query.tags.length > 0) {
-            this.validateTags(query.tags);
-            const tagPlaceholders = query.tags.map(() => '?').join(', ');
-            sql += ` AND EXISTS (
-        SELECT 1 FROM memory_entry_tags t
-        WHERE t.entry_id = memory_entries.id AND t.tag IN (${tagPlaceholders})
-      )`;
-            params.push(...query.tags);
-        }
-        // Pagination — always enforce a cap to prevent full-table scans
-        const MAX_QUERY_LIMIT = 10_000;
-        const effectiveLimit = Math.min(Math.max(1, query.limit ?? MAX_QUERY_LIMIT), MAX_QUERY_LIMIT);
-        const colMap = {
-            createdAt: 'created_at', updatedAt: 'updated_at',
-            lastAccessedAt: 'last_accessed_at', accessCount: 'access_count', key: 'key',
-        };
-        const orderCol = (query.sortField && query.sortField !== 'score' && colMap[query.sortField])
-            ? colMap[query.sortField]
-            : 'created_at';
-        const orderDir = query.sortDirection === 'asc' ? 'ASC' : 'DESC';
-        sql += ` ORDER BY ${orderCol} ${orderDir}`;
-        sql += ' LIMIT ?';
-        params.push(effectiveLimit);
-        if (query.offset) {
-            sql += ' OFFSET ?';
-            params.push(query.offset);
-        }
-        const stmt = this.db.prepare(sql);
-        const rows = stmt.all(...params);
-        const results = rows.map((row) => this.rowToEntry(row));
-        const duration = performance.now() - startTime;
-        this.stats.queryCount++;
-        this.stats.totalQueryTime += duration;
-        return results;
-    }
-    /**
-     * Semantic vector search (not optimized for SQLite, returns empty)
-     * Use HybridBackend for semantic search with LanceDB
-     */
-    async search(embedding, options) {
-        this.ensureInitialized();
-        // Brute-force cosine over stored embeddings, namespace-scoped and
-        // TTL-filtered in SQL. iterate() streams rows one at a time instead of
-        // materializing the whole embedding table (.all() held every BLOB in
-        // memory at once). At second-brain scale (10^3–10^5 vectors of 384 dims)
-        // this is a few tens of ms; swap in the HNSW index if a profiled
-        // workload outgrows it.
-        const ns = options.filters?.namespace;
-        const rows = this.db.prepare(`
-      SELECT e.*, emb.embedding AS _emb
-      FROM memory_entries e
-      JOIN memory_embeddings emb ON emb.entry_id = e.id
-      WHERE (e.expires_at IS NULL OR e.expires_at = 0 OR e.expires_at > ?)
-      ${ns ? 'AND e.namespace = ?' : ''}
-    `).iterate(...(ns ? [Date.now(), ns] : [Date.now()]));
-        const results = [];
-        for (const row of rows) {
-            const buf = row._emb;
-            if (!buf || buf.byteLength % 4 !== 0)
-                continue;
-            const vec = new Float32Array(buf.buffer, buf.byteOffset, buf.byteLength / 4);
-            if (vec.length !== embedding.length)
-                continue;
-            const similarity = cosineSimilarity(embedding, vec);
-            if (options.threshold !== undefined && similarity < options.threshold)
-                continue;
-            delete row._emb;
-            results.push({ entry: this.rowToEntry(row), score: similarity, distance: 1 - similarity });
-        }
-        results.sort((a, b) => b.score - a.score);
-        return results.slice(0, options.k);
-    }
-    /**
-     * Bulk insert entries
-     */
-    async bulkInsert(entries) {
-        this.ensureInitialized();
-        const transaction = this.db.transaction((entries) => {
-            for (const entry of entries) {
-                this.storeSync(entry);
-            }
-        });
-        transaction(entries);
-        this.emit('bulk:inserted', { count: entries.length });
-    }
-    /**
-     * Bulk delete entries
-     */
-    async bulkDelete(ids) {
-        this.ensureInitialized();
-        const deleteEntry = this.db.prepare('DELETE FROM memory_entries WHERE id = ?');
-        const transaction = this.db.transaction((ids) => {
-            let deleted = 0;
-            for (const id of ids) {
-                this.stmtDeleteTags.run(id);
-                const result = deleteEntry.run(id);
-                if (result.changes > 0)
-                    deleted++;
-            }
-            return deleted;
-        });
-        return transaction(ids);
-    }
-    /**
-     * Get entry count
-     */
-    async count(namespace) {
-        this.ensureInitialized();
-        let sql = 'SELECT COUNT(*) as count FROM memory_entries';
-        const params = [];
-        if (namespace) {
-            sql += ' WHERE namespace = ?';
-            params.push(namespace);
-        }
-        const stmt = this.db.prepare(sql);
-        const result = stmt.get(...params);
-        return result.count;
-    }
-    /**
-     * List all namespaces
-     */
-    async listNamespaces() {
-        this.ensureInitialized();
-        const stmt = this.db.prepare('SELECT DISTINCT namespace FROM memory_entries');
-        const rows = stmt.all();
-        return rows.map((row) => row.namespace);
-    }
-    /**
-     * Clear all entries in a namespace
-     */
-    async clearNamespace(namespace) {
-        this.ensureInitialized();
-        const deleteTags = this.db.prepare(`
-      DELETE FROM memory_entry_tags
-      WHERE entry_id IN (SELECT id FROM memory_entries WHERE namespace = ?)
-    `);
-        const deleteEntries = this.db.prepare('DELETE FROM memory_entries WHERE namespace = ?');
-        const deleteOrphanEmbeddings = this.db.prepare(`
-      DELETE FROM memory_embeddings
-      WHERE entry_id NOT IN (SELECT id FROM memory_entries)
-    `);
-        let changes = 0;
-        this.db.transaction(() => {
-            deleteTags.run(namespace);
-            changes = deleteEntries.run(namespace).changes;
-            deleteOrphanEmbeddings.run();
-        })();
-        return changes;
-    }
-    /**
-     * Get backend statistics
-     */
-    async getStats() {
-        this.ensureInitialized();
-        // Count by namespace
-        const namespaceStmt = this.db.prepare(`
-      SELECT namespace, COUNT(*) as count
-      FROM memory_entries
-      GROUP BY namespace
-    `);
-        const namespaceRows = namespaceStmt.all();
-        const entriesByNamespace = {};
-        for (const row of namespaceRows) {
-            entriesByNamespace[row.namespace] = row.count;
-        }
-        // Count by type
-        const typeStmt = this.db.prepare(`
-      SELECT type, COUNT(*) as count
-      FROM memory_entries
-      GROUP BY type
-    `);
-        const typeRows = typeStmt.all();
-        const entriesByType = {
-            episodic: 0,
-            semantic: 0,
-            working: 0,
-            cache: 0,
-        };
-        for (const row of typeRows) {
-            entriesByType[row.type] = row.count;
-        }
-        // Get database size
-        const pageCount = this.db.pragma('page_count', { simple: true });
-        const pageSize = this.db.pragma('page_size', { simple: true });
-        const memoryUsage = pageCount * pageSize;
-        const totalEntries = await this.count();
-        return {
-            totalEntries,
-            entriesByNamespace,
-            entriesByType,
-            memoryUsage,
-            avgQueryTime: this.stats.queryCount > 0
-                ? this.stats.totalQueryTime / this.stats.queryCount
-                : 0,
-            avgSearchTime: 0, // Not applicable for SQLite
-        };
-    }
-    /**
-     * Perform health check
-     */
-    async healthCheck() {
-        const issues = [];
-        const recommendations = [];
-        if (!this.initialized || !this.db) {
-            return {
-                status: 'unhealthy',
-                components: {
-                    storage: { status: 'unhealthy', latency: 0, message: 'Not initialized' },
-                    index: { status: 'healthy', latency: 0 },
-                    cache: { status: 'healthy', latency: 0 },
-                },
-                timestamp: Date.now(),
-                issues: ['Backend not initialized'],
-                recommendations: ['Call initialize() before using'],
-            };
-        }
-        // Check database integrity
-        let storageHealth;
+    async openDriver() {
+        let Database;
         try {
-            const integrityCheck = this.db.pragma('integrity_check', { simple: true });
-            if (integrityCheck === 'ok') {
-                storageHealth = { status: 'healthy', latency: 0 };
-            }
-            else {
-                issues.push('Database integrity check failed');
-                recommendations.push('Run VACUUM to repair database');
-                storageHealth = { status: 'unhealthy', latency: 0, message: 'Integrity check failed' };
-            }
+            const mod = await import('better-sqlite3');
+            Database = mod.default;
         }
         catch (error) {
-            issues.push('Failed to check database integrity');
-            storageHealth = { status: 'unhealthy', latency: 0, message: String(error) };
-        }
-        // Check utilization
-        const totalEntries = await this.count();
-        const utilizationPercent = (totalEntries / this.config.maxEntries) * 100;
-        if (utilizationPercent > 95) {
-            issues.push('Storage utilization critical (>95%)');
-            recommendations.push('Cleanup old data or increase maxEntries');
-            storageHealth = { status: 'unhealthy', latency: 0, message: 'Near capacity' };
-        }
-        else if (utilizationPercent > 80) {
-            issues.push('Storage utilization high (>80%)');
-            recommendations.push('Consider cleanup');
-            if (storageHealth.status === 'healthy') {
-                storageHealth = { status: 'degraded', latency: 0, message: 'High utilization' };
-            }
-        }
-        const status = storageHealth.status === 'unhealthy'
-            ? 'unhealthy'
-            : storageHealth.status === 'degraded'
-                ? 'degraded'
-                : 'healthy';
-        return {
-            status,
-            components: {
-                storage: storageHealth,
-                index: { status: 'healthy', latency: 0 },
-                cache: { status: 'healthy', latency: 0 },
-            },
-            timestamp: Date.now(),
-            issues,
-            recommendations,
-        };
-    }
-    // ===== Private Methods =====
-    // Every tag write below is parameterized — validation is shape sanity, not
-    // injection defense. `src:<absolute path>` provenance tags are first-class
-    // in the knowledge pipeline and paths legitimately contain @, #, spaces,
-    // unicode, parentheses… so src: tags only exclude control characters.
-    // (The sql.js backend has never validated tags at all; a strict charset
-    // here made store success silently depend on which backend loaded.)
-    static TAG_RE = /^[a-zA-Z0-9_\-.:/~ ]+$/;
-    static SRC_TAG_RE = /^src:[^\x00-\x1f\x7f]+$/;
-    static MAX_TAG_LEN = 512;
-    validateTags(tags) {
-        for (const tag of tags) {
-            const ok = typeof tag === 'string' && tag.length <= SQLiteBackend.MAX_TAG_LEN
-                && (tag.startsWith('src:') ? SQLiteBackend.SRC_TAG_RE.test(tag) : SQLiteBackend.TAG_RE.test(tag));
-            if (!ok)
-                throw new Error(`Invalid tag format: "${String(tag).slice(0, 80)}"`);
-        }
-    }
-    ensureInitialized() {
-        if (!this.initialized || !this.db) {
-            throw new Error('SQLiteBackend not initialized. Call initialize() first.');
-        }
-    }
-    createSchema() {
-        if (!this.db)
-            return;
-        // Main entries table
-        this.db.exec(`
-      CREATE TABLE IF NOT EXISTS memory_entries (
-        id TEXT PRIMARY KEY,
-        key TEXT NOT NULL,
-        content TEXT NOT NULL,
-        type TEXT NOT NULL,
-        namespace TEXT NOT NULL,
-        tags TEXT NOT NULL,
-        metadata TEXT NOT NULL,
-        owner_id TEXT,
-        access_level TEXT NOT NULL,
-        created_at INTEGER NOT NULL,
-        updated_at INTEGER NOT NULL,
-        expires_at INTEGER,
-        event_at INTEGER,
-        version INTEGER NOT NULL,
-        "references" TEXT NOT NULL,
-        access_count INTEGER NOT NULL,
-        last_accessed_at INTEGER NOT NULL
-      );
-
-      CREATE INDEX IF NOT EXISTS idx_namespace ON memory_entries(namespace);
-      CREATE INDEX IF NOT EXISTS idx_key ON memory_entries(key);
-      CREATE INDEX IF NOT EXISTS idx_type ON memory_entries(type);
-      CREATE INDEX IF NOT EXISTS idx_owner_id ON memory_entries(owner_id);
-      CREATE INDEX IF NOT EXISTS idx_created_at ON memory_entries(created_at);
-      CREATE INDEX IF NOT EXISTS idx_updated_at ON memory_entries(updated_at);
-      CREATE INDEX IF NOT EXISTS idx_expires_at ON memory_entries(expires_at);
-
-      CREATE TABLE IF NOT EXISTS memory_embeddings (
-        entry_id TEXT PRIMARY KEY,
-        embedding BLOB,
-        FOREIGN KEY (entry_id) REFERENCES memory_entries(id) ON DELETE CASCADE
-      );
-    `);
-        // UNIQUE(namespace,key): the sql.js schema has always enforced it; this
-        // backend only had a plain index, so repeated stores under the same key
-        // accumulated duplicates and getByKey returned an arbitrary one. Existing
-        // databases may already hold duplicates — dedupe (keep newest) before the
-        // unique index can be created, then upgrade the index.
-        try {
-            this.db.exec(`
-        DELETE FROM memory_entries WHERE id NOT IN (
-          SELECT id FROM (
-            SELECT id, ROW_NUMBER() OVER (PARTITION BY namespace, key ORDER BY updated_at DESC, id DESC) AS rn
-            FROM memory_entries
-          ) WHERE rn = 1
-        );
-        DROP INDEX IF EXISTS idx_namespace_key;
-        CREATE UNIQUE INDEX IF NOT EXISTS idx_namespace_key_unique ON memory_entries(namespace, key);
-      `);
-        }
-        catch {
-            // Very old SQLite without window functions: keep the plain index rather
-            // than failing initialization — dup accumulation is the lesser evil.
-            this.db.exec('CREATE INDEX IF NOT EXISTS idx_namespace_key ON memory_entries(namespace, key);');
-        }
-        this.db.exec(`
-
-      CREATE TABLE IF NOT EXISTS agent_reads (
-        entry_id TEXT NOT NULL,
-        agent_id TEXT NOT NULL,
-        read_at INTEGER NOT NULL,
-        UNIQUE(entry_id, agent_id)
-      );
-      CREATE INDEX IF NOT EXISTS idx_agent_reads_entry ON agent_reads(entry_id);
-      CREATE INDEX IF NOT EXISTS idx_agent_reads_at ON agent_reads(read_at);
-
-      CREATE TABLE IF NOT EXISTS memory_entry_tags (
-        entry_id TEXT NOT NULL,
-        tag TEXT NOT NULL,
-        PRIMARY KEY (entry_id, tag),
-        FOREIGN KEY (entry_id) REFERENCES memory_entries(id) ON DELETE CASCADE
-      );
-      CREATE INDEX IF NOT EXISTS idx_entry_tag ON memory_entry_tags(tag, entry_id);
-    `);
-        // One-time backfill gated by user_version — wrapped in a transaction to hold
-        // a write lock and prevent double-backfill under concurrent process startup.
-        this.db.transaction(() => {
-            const schemaVersion = this.db.pragma('user_version', { simple: true });
-            if (schemaVersion < 1) {
-                this.db.exec(`
-          INSERT OR IGNORE INTO memory_entry_tags (entry_id, tag)
-            SELECT memory_entries.id, t.value
-            FROM memory_entries, json_each(tags) AS t
-            WHERE json_valid(tags) AND t.value IS NOT NULL AND t.value != '';
-        `);
-                this.db.pragma('user_version = 1');
-            }
-        })();
-    }
-    rowToEntry(row) {
-        // Get embedding if exists — use pre-compiled statement to avoid N+1 re-prepare
-        let embedding;
-        const embeddingRow = this.stmtGetEmbedding.get(row.id);
-        if (embeddingRow && embeddingRow.embedding) {
-            // Slice only the intended byte range — Buffer.from(existingBuffer) for copies
-            // under Node's 8KB pool threshold returns a view into the SHARED pool
-            // ArrayBuffer at a nonzero offset, so `.buffer` alone spans unrelated pool
-            // memory (silent data corruption). byteOffset/byteLength scope it correctly.
-            const buf = embeddingRow.embedding;
-            embedding = new Float32Array(buf.buffer, buf.byteOffset, buf.byteLength / 4);
-        }
-        return {
-            id: row.id,
-            key: row.key,
-            content: row.content,
-            embedding,
-            type: row.type,
-            namespace: row.namespace,
-            tags: JSON.parse(row.tags),
-            metadata: JSON.parse(row.metadata),
-            ownerId: row.owner_id,
-            accessLevel: row.access_level,
-            createdAt: row.created_at,
-            updatedAt: row.updated_at,
-            expiresAt: row.expires_at,
-            eventAt: row.event_at ?? undefined,
-            version: row.version,
-            references: JSON.parse(row.references),
-            accessCount: row.access_count,
-            lastAccessedAt: row.last_accessed_at,
-        };
-    }
-    /**
-     * Synchronous store for use in transactions
-     */
-    storeSync(entry) {
-        this.validateTags(entry.tags);
-        // Read existing embedding before INSERT OR REPLACE cascades-deletes it
-        let embeddingToStore = entry.embedding;
-        if (!embeddingToStore) {
-            const existingEmb = this.stmtGetEmbedding.get(entry.id);
-            if (existingEmb?.embedding) {
-                const buf = Buffer.from(existingEmb.embedding);
-                embeddingToStore = new Float32Array(buf.buffer, buf.byteOffset, buf.byteLength / 4);
-            }
-        }
-        this.stmtInsertEntry.run(entry.id, entry.key, entry.content, entry.type, entry.namespace, JSON.stringify(entry.tags), JSON.stringify(entry.metadata), entry.ownerId || null, entry.accessLevel, entry.createdAt, entry.updatedAt, entry.expiresAt || null, entry.eventAt ?? null, entry.version, JSON.stringify(entry.references), entry.accessCount, entry.lastAccessedAt);
-        this.stmtDeleteTags.run(entry.id);
-        for (const tag of entry.tags) {
-            this.stmtInsertTag.run(entry.id, tag);
-        }
-        if (embeddingToStore) {
-            this.stmtInsertEmbedding.run(entry.id, Buffer.from(embeddingToStore.buffer, embeddingToStore.byteOffset, embeddingToStore.byteLength));
-        }
+            // Reaching here means this backend was chosen explicitly while the native
+            // module is unavailable. Say so, instead of surfacing a bare
+            // ERR_MODULE_NOT_FOUND from deep inside the driver.
+            throw new Error('SQLiteBackend requires the optional dependency better-sqlite3, which is not installed ' +
+                `(${error.message}). Use SqlJsBackend, or select the 'sql.js' provider, ` +
+                'for environments where the native module cannot be built.');
+        }
+        const db = new Database(this.sqliteConfig.databasePath, {
+            verbose: this.sqliteConfig.verbose ? console.log : undefined,
+        });
+        if (this.sqliteConfig.walMode)
+            db.pragma('journal_mode = WAL');
+        if (this.sqliteConfig.optimize) {
+            db.pragma('synchronous = NORMAL');
+            db.pragma('cache_size = 10000');
+            db.pragma('temp_store = MEMORY');
+        }
+        return new BetterSqliteDriver(db);
     }
 }
 export default SQLiteBackend;