@framers/agentos 0.1.122 → 0.1.124

package/dist/memory/facade/Memory.js

@@ -63,7 +63,7 @@ function sha256(content) {
  *
  * ## Quick start
  * ```ts
- * const mem = new Memory({ store: 'sqlite', path: './brain.sqlite' });
+ * const mem = await Memory.create({ store: 'sqlite', path: './brain.sqlite' });
  *
  * await mem.remember('The user prefers dark mode');
  * const results = await mem.recall('dark mode preference');
@@ -74,67 +74,31 @@ function sha256(content) {
  */
 export class Memory {
     // -------------------------------------------------------------------
-    // Constructor
+    // Constructor (private — use Memory.create() instead)
     // -------------------------------------------------------------------
     /**
-     * Create a new Memory instance and wire together all subsystems.
-     *
-     * Initialization sequence:
-     * 1. Merge `config` with defaults (store='sqlite', path=tmpdir, graph=true,
-     *    selfImprove=true, decay=true).
-     * 2. Create `SqliteBrain(config.path)`.
-     * 3. Check embedding dimension compatibility (warn on mismatch).
-     * 4. Create `SqliteKnowledgeGraph(brain)`.
-     * 5. Create `SqliteMemoryGraph(brain)` and call `.initialize()`.
-     * 6. Create `LoaderRegistry()` (pre-registers all built-in loaders).
-     * 7. Create `FolderScanner(registry)`.
-     * 8. Create `ChunkingEngine()`.
-     * 9. If `selfImprove`: create `RetrievalFeedbackSignal(brain)` and
-     *    `ConsolidationLoop(brain, memoryGraph)`.
-     *
-     * @param config - Optional configuration; see {@link MemoryConfig}.
+     * Private constructor. Receives an already-opened SqliteBrain and
+     * pre-computed configuration. Use {@link Memory.create} to instantiate.
      */
-    constructor(config) {
+    constructor(brain, config) {
         /** HNSW sidecar index for O(log n) vector search alongside SQLite. */
         this._hnswSidecar = null;
-        // Step 1: merge with defaults.
-        const randomSuffix = Math.random().toString(36).slice(2, 10);
-        this._config = {
-            store: 'sqlite',
-            path: path.join(os.tmpdir(), `brain-${randomSuffix}.sqlite`),
-            graph: true,
-            selfImprove: true,
-            decay: true,
-            ...config,
-        };
+        this._brain = brain;
+        this._config = config;
         // Store the optional embedding function for vector search.
-        this._embed = config?.embed ?? null;
-        if (this._config.store !== 'sqlite') {
-            throw new Error(`Memory currently supports only the SQLite-backed facade at runtime. ` +
-                `Received store="${this._config.store}".`);
-        }
-        // Step 2: create SqliteBrain.
-        this._brain = new SqliteBrain(this._config.path);
-        // Step 3: check embedding dimension compatibility.
-        const dimensions = this._config.embeddings?.dimensions ?? 1536;
-        const compatible = this._brain.checkEmbeddingCompat(dimensions);
-        if (!compatible) {
-            console.warn(`[Memory] Embedding dimension mismatch: expected ${dimensions} but brain ` +
-                `was previously configured with a different dimension. Vector similarity ` +
-                `searches may produce incorrect results.`);
-        }
-        // Step 4: create SqliteKnowledgeGraph.
+        this._embed = config.embed ?? null;
+        // Create SqliteKnowledgeGraph.
         this._knowledgeGraph = new SqliteKnowledgeGraph(this._brain);
-        // Step 5: create SqliteMemoryGraph and initialize.
+        // Create SqliteMemoryGraph and initialize.
         this._memoryGraph = new SqliteMemoryGraph(this._brain);
         this._initPromise = this._memoryGraph.initialize();
-        // Step 6: create LoaderRegistry.
+        // Create LoaderRegistry.
         this._loaderRegistry = new LoaderRegistry();
-        // Step 7: create FolderScanner.
+        // Create FolderScanner.
         this._folderScanner = new FolderScanner(this._loaderRegistry);
-        // Step 8: create ChunkingEngine.
+        // Create ChunkingEngine.
         this._chunkingEngine = new ChunkingEngine();
-        // Step 9: self-improvement subsystems.
+        // Self-improvement subsystems.
         if (this._config.selfImprove) {
             this._feedbackSignal = new RetrievalFeedbackSignal(this._brain);
             this._consolidationLoop = new ConsolidationLoop(this._brain, this._memoryGraph);
@@ -143,7 +107,7 @@ export class Memory {
             this._feedbackSignal = null;
             this._consolidationLoop = null;
         }
-        // Step 10: HNSW sidecar index (O(log n) ANN alongside SQLite).
+        // HNSW sidecar index (O(log n) ANN alongside SQLite).
         // Loads existing index from disk if present; auto-builds when trace count
         // exceeds 1000 and embeddings are available. Falls back to FTS5-only
         // recall if hnswlib-node is not installed or no embeddings exist.
@@ -164,6 +128,55 @@ export class Memory {
             }
         });
     }
+    // -------------------------------------------------------------------
+    // Async factory
+    // -------------------------------------------------------------------
+    /**
+     * Create a new Memory instance and wire together all subsystems.
+     *
+     * Initialization sequence:
+     * 1. Merge `config` with defaults (store='sqlite', path=tmpdir, graph=true,
+     *    selfImprove=true, decay=true).
+     * 2. Await `SqliteBrain.open(config.path)`.
+     * 3. Check embedding dimension compatibility (warn on mismatch).
+     * 4. Create `SqliteKnowledgeGraph(brain)`.
+     * 5. Create `SqliteMemoryGraph(brain)` and call `.initialize()`.
+     * 6. Create `LoaderRegistry()` (pre-registers all built-in loaders).
+     * 7. Create `FolderScanner(registry)`.
+     * 8. Create `ChunkingEngine()`.
+     * 9. If `selfImprove`: create `RetrievalFeedbackSignal(brain)` and
+     *    `ConsolidationLoop(brain, memoryGraph)`.
+     *
+     * @param config - Optional configuration; see {@link MemoryConfig}.
+     * @returns A fully initialised Memory instance.
+     */
+    static async create(config) {
+        // Step 1: merge with defaults.
+        const randomSuffix = Math.random().toString(36).slice(2, 10);
+        const merged = {
+            store: 'sqlite',
+            path: path.join(os.tmpdir(), `brain-${randomSuffix}.sqlite`),
+            graph: true,
+            selfImprove: true,
+            decay: true,
+            ...config,
+        };
+        if (merged.store !== 'sqlite') {
+            throw new Error(`Memory currently supports only the SQLite-backed facade at runtime. ` +
+                `Received store="${merged.store}".`);
+        }
+        // Step 2: create SqliteBrain (async).
+        const brain = await SqliteBrain.open(merged.path);
+        // Step 3: check embedding dimension compatibility.
+        const dimensions = merged.embeddings?.dimensions ?? 1536;
+        const compatible = await brain.checkEmbeddingCompat(dimensions);
+        if (!compatible) {
+            console.warn(`[Memory] Embedding dimension mismatch: expected ${dimensions} but brain ` +
+                `was previously configured with a different dimension. Vector similarity ` +
+                `searches may produce incorrect results.`);
+        }
+        return new Memory(brain, merged);
+    }
     // =========================================================================
     // Core memory operations
     // =========================================================================
@@ -184,7 +197,7 @@ export class Memory {
         const type = options?.type ?? 'episodic';
         const scope = options?.scope ?? 'user';
         const scopeId = options?.scopeId ?? '';
-        const existing = this._findExistingTraceByHash(contentHash, type, scope, scopeId);
+        const existing = await this._findExistingTraceByHash(contentHash, type, scope, scopeId);
         if (existing) {
             return this._buildTrace(existing);
         }
@@ -207,22 +220,28 @@ export class Memory {
             }
         }
         // Insert into memory_traces.
-        this._brain.db
-            .prepare(`INSERT INTO memory_traces
-           (id, type, scope, content, embedding, strength, created_at,
-            last_accessed, retrieval_count, tags, emotions, metadata, deleted)
-         VALUES (?, ?, ?, ?, ?, ?, ?, NULL, 0, ?, ?, ?, 0)`)
-            .run(id, type, scope, content, embeddingBlob, // Binary blob or null
-        importance, now, JSON.stringify(tags), JSON.stringify({}), JSON.stringify(buildInitialTraceMetadata({}, { contentHash, entities, scopeId })));
+        await this._brain.run(`INSERT INTO memory_traces
+         (id, type, scope, content, embedding, strength, created_at,
+          last_accessed, retrieval_count, tags, emotions, metadata, deleted)
+       VALUES (?, ?, ?, ?, ?, ?, ?, NULL, 0, ?, ?, ?, 0)`, [
+            id,
+            type,
+            scope,
+            content,
+            embeddingBlob, // Binary blob or null
+            importance,
+            now,
+            JSON.stringify(tags),
+            JSON.stringify({}),
+            JSON.stringify(buildInitialTraceMetadata({}, { contentHash, entities, scopeId })),
+        ]);
         // Sync FTS5 index. The external-content FTS5 table needs explicit insert.
-        this._brain.db
-            .prepare(`INSERT INTO memory_traces_fts (rowid, content, tags)
-         VALUES (
-           (SELECT rowid FROM memory_traces WHERE id = ?),
-           ?,
-           ?
-         )`)
-            .run(id, content, JSON.stringify(tags));
+        await this._brain.run(`INSERT INTO memory_traces_fts (rowid, content, tags)
+       VALUES (
+         (SELECT rowid FROM memory_traces WHERE id = ?),
+         ?,
+         ?
+       )`, [id, content, JSON.stringify(tags)]);
         // Add to memory graph if available.
         if (this._config.graph) {
             await this._memoryGraph.addNode(id, {
@@ -237,20 +256,17 @@ export class Memory {
         // The embedding is stored in the memory_traces table; if it's non-null,
         // also index it in the HNSW sidecar for fast ANN recall.
         if (this._hnswSidecar) {
-            const row = this._brain.db
-                .prepare('SELECT embedding FROM memory_traces WHERE id = ?')
-                .get(id);
+            const row = await this._brain.get('SELECT embedding FROM memory_traces WHERE id = ?', [id]);
             if (row?.embedding && row.embedding.length > 0) {
                 const { blobToEmbedding, isLegacyJsonBlob } = await import('../../rag/utils/vectorMath.js');
                 const vec = isLegacyJsonBlob(row.embedding)
                     ? JSON.parse(row.embedding)
                     : blobToEmbedding(row.embedding);
-                const count = this._brain.db.prepare('SELECT COUNT(*) as c FROM memory_traces WHERE deleted = 0').get().c;
+                const countRow = await this._brain.get('SELECT COUNT(*) as c FROM memory_traces WHERE deleted = 0');
+                const count = countRow?.c ?? 0;
                 if (!this._hnswSidecar.isActive && count >= 1000) {
                     // Threshold crossed — rebuild full index from all embeddings.
-                    const allRows = this._brain.db
-                        .prepare('SELECT id, embedding FROM memory_traces WHERE deleted = 0 AND embedding IS NOT NULL')
-                        .all();
+                    const allRows = await this._brain.all('SELECT id, embedding FROM memory_traces WHERE deleted = 0 AND embedding IS NOT NULL');
                     const data = allRows
                         .filter(r => r.embedding && r.embedding.length > 0)
                         .map(r => ({
@@ -363,9 +379,7 @@ export class Memory {
           ORDER BY abs(fts.rank) DESC
           LIMIT ?
         `;
-                const ftsRows = this._brain.db
-                    .prepare(ftsSql)
-                    .all(...params, ftsQuery, limit * 3);
+                const ftsRows = await this._brain.all(ftsSql, [...params, ftsQuery, limit * 3]);
                 const ftsRank = new Map(ftsRows.map((r, i) => [r.id, i + 1]));
                 // Merge all candidate IDs.
                 const allIds = new Set([...hnswIds, ...ftsRows.map(r => r.id)]);
@@ -384,10 +398,8 @@ export class Memory {
                 // Fetch full rows for the top candidates.
                 if (topIds.length > 0) {
                     const placeholders = topIds.map(() => '?').join(',');
-                    const fullRows = this._brain.db
-                        .prepare(`SELECT t.*, 0.0 as rank FROM memory_traces t WHERE t.id IN (${placeholders}) AND t.deleted = 0`)
-                        .all(...topIds);
-                    const updatedRows = this._applyRecallAccessUpdates(fullRows);
+                    const fullRows = await this._brain.all(`SELECT t.*, 0.0 as rank FROM memory_traces t WHERE t.id IN (${placeholders}) AND t.deleted = 0`, topIds);
+                    const updatedRows = await this._applyRecallAccessUpdates(fullRows);
                     const rrfMap = new Map(scored.map(s => [s.id, s.rrfScore]));
                     return updatedRows.map((row) => ({
                         trace: this._buildTrace(row),
@@ -409,10 +421,8 @@ export class Memory {
       LIMIT ?
     `;
         params.push(ftsQuery, limit);
-        const rows = this._brain.db
-            .prepare(sql)
-            .all(...params);
-        const updatedRows = this._applyRecallAccessUpdates(rows);
+        const rows = await this._brain.all(sql, params);
+        const updatedRows = await this._applyRecallAccessUpdates(rows);
         return updatedRows.map((row) => ({
             trace: this._buildTrace(row),
             score: row.strength * Math.abs(row.rank),
@@ -428,9 +438,7 @@ export class Memory {
      */
     async forget(traceId) {
         await this._initPromise;
-        this._brain.db
-            .prepare('UPDATE memory_traces SET deleted = 1 WHERE id = ?')
-            .run(traceId);
+        await this._brain.run('UPDATE memory_traces SET deleted = 1 WHERE id = ?', [traceId]);
     }
     // =========================================================================
     // Document ingestion
@@ -618,28 +626,24 @@ export class Memory {
     /**
      * Record retrieval feedback for a memory trace.
      *
-     * Fire-and-forget: the feedback is persisted asynchronously and this method
-     * returns immediately without waiting for the write to complete.
+     * The feedback is persisted asynchronously. This method returns a Promise
+     * that resolves once the feedback has been written.
      *
      * @param traceId - The ID of the trace being evaluated.
      * @param signal  - Whether the trace was `'used'` or `'ignored'` by the LLM.
      */
-    feedback(traceId, signal) {
+    async feedback(traceId, signal) {
         if (!this._feedbackSignal)
             return;
         try {
             const now = Date.now();
-            const row = this._brain.db
-                .prepare(`SELECT id, type, scope, content, embedding, strength, created_at,
-                  last_accessed, retrieval_count, tags, emotions, metadata, deleted
-           FROM memory_traces
-           WHERE id = ?
-           LIMIT 1`)
-                .get(traceId);
-            this._brain.db
-                .prepare(`INSERT INTO retrieval_feedback (trace_id, signal, query, created_at)
-           VALUES (?, ?, NULL, ?)`)
-                .run(traceId, signal, now);
+            const row = await this._brain.get(`SELECT id, type, scope, content, embedding, strength, created_at,
+                last_accessed, retrieval_count, tags, emotions, metadata, deleted
+         FROM memory_traces
+         WHERE id = ?
+         LIMIT 1`, [traceId]);
+            await this._brain.run(`INSERT INTO retrieval_feedback (trace_id, signal, query, created_at)
+         VALUES (?, ?, NULL, ?)`, [traceId, signal, now]);
             if (!row)
                 return;
             if (signal === 'used') {
@@ -650,11 +654,15 @@ export class Memory {
                     reinforcementInterval: update.reinforcementInterval,
                     nextReinforcementAt: update.nextReinforcementAt,
                 }));
-                this._brain.db
-                    .prepare(`UPDATE memory_traces
-             SET strength = ?, last_accessed = ?, retrieval_count = ?, metadata = ?
-             WHERE id = ?`)
-                    .run(update.encodingStrength, update.lastAccessedAt, update.retrievalCount, metadata, traceId);
+                await this._brain.run(`UPDATE memory_traces
+           SET strength = ?, last_accessed = ?, retrieval_count = ?, metadata = ?
+           WHERE id = ?`, [
+                    update.encodingStrength,
+                    update.lastAccessedAt,
+                    update.retrievalCount,
+                    metadata,
+                    traceId,
+                ]);
                 return;
             }
             const penalty = penalizeUnused(this._buildTrace(row), now);
@@ -667,11 +675,9 @@ export class Memory {
                     ? { nextReinforcementAt: existingDecay.nextReinforcementAt }
                     : {}),
             }));
-            this._brain.db
-                .prepare(`UPDATE memory_traces
-           SET strength = ?, last_accessed = ?, metadata = ?
-           WHERE id = ?`)
-                .run(penalty.encodingStrength, penalty.lastAccessedAt, metadata, traceId);
+            await this._brain.run(`UPDATE memory_traces
+         SET strength = ?, last_accessed = ?, metadata = ?
+         WHERE id = ?`, [penalty.encodingStrength, penalty.lastAccessedAt, metadata, traceId]);
         }
         catch {
             // Explicit feedback is best-effort; the caller should not fail on analytics updates.
@@ -758,7 +764,7 @@ export class Memory {
                 break;
         }
         if (result.imported > 0) {
-            this._rebuildFtsIndex();
+            await this._rebuildFtsIndex();
         }
         return result;
     }
@@ -807,63 +813,42 @@ export class Memory {
      */
     async health() {
         await this._initPromise;
-        const db = this._brain.db;
         // Total traces (active + deleted).
-        const totalRow = db
-            .prepare('SELECT COUNT(*) AS cnt FROM memory_traces')
-            .get();
+        const totalRow = await this._brain.get('SELECT COUNT(*) AS cnt FROM memory_traces');
         const totalTraces = totalRow?.cnt ?? 0;
         // Active traces (not deleted).
-        const activeRow = db
-            .prepare('SELECT COUNT(*) AS cnt FROM memory_traces WHERE deleted = 0')
-            .get();
+        const activeRow = await this._brain.get('SELECT COUNT(*) AS cnt FROM memory_traces WHERE deleted = 0');
         const activeTraces = activeRow?.cnt ?? 0;
         // Average strength of active traces.
-        const avgRow = db
-            .prepare('SELECT AVG(strength) AS avg_s FROM memory_traces WHERE deleted = 0')
-            .get();
+        const avgRow = await this._brain.get('SELECT AVG(strength) AS avg_s FROM memory_traces WHERE deleted = 0');
         const avgStrength = avgRow?.avg_s ?? 0;
         // Weakest active trace.
-        const weakRow = db
-            .prepare('SELECT MIN(strength) AS min_s FROM memory_traces WHERE deleted = 0')
-            .get();
+        const weakRow = await this._brain.get('SELECT MIN(strength) AS min_s FROM memory_traces WHERE deleted = 0');
         const weakestTraceStrength = weakRow?.min_s ?? 0;
         // Knowledge graph counts.
-        const nodesRow = db
-            .prepare('SELECT COUNT(*) AS cnt FROM knowledge_nodes')
-            .get();
+        const nodesRow = await this._brain.get('SELECT COUNT(*) AS cnt FROM knowledge_nodes');
         const graphNodes = nodesRow?.cnt ?? 0;
-        const edgesRow = db
-            .prepare('SELECT COUNT(*) AS cnt FROM knowledge_edges')
-            .get();
+        const edgesRow = await this._brain.get('SELECT COUNT(*) AS cnt FROM knowledge_edges');
         const graphEdges = edgesRow?.cnt ?? 0;
         // Last consolidation timestamp.
-        const lastConsolRow = db
-            .prepare('SELECT ran_at FROM consolidation_log ORDER BY ran_at DESC LIMIT 1')
-            .get();
+        const lastConsolRow = await this._brain.get('SELECT ran_at FROM consolidation_log ORDER BY ran_at DESC LIMIT 1');
         const lastConsolidation = lastConsolRow
             ? new Date(lastConsolRow.ran_at).toISOString()
             : null;
         // Traces per type.
-        const typeRows = db
-            .prepare('SELECT type, COUNT(*) AS cnt FROM memory_traces WHERE deleted = 0 GROUP BY type')
-            .all();
+        const typeRows = await this._brain.all('SELECT type, COUNT(*) AS cnt FROM memory_traces WHERE deleted = 0 GROUP BY type');
         const tracesPerType = {};
         for (const row of typeRows) {
             tracesPerType[row.type] = row.cnt;
         }
         // Traces per scope.
-        const scopeRows = db
-            .prepare('SELECT scope, COUNT(*) AS cnt FROM memory_traces WHERE deleted = 0 GROUP BY scope')
-            .all();
+        const scopeRows = await this._brain.all('SELECT scope, COUNT(*) AS cnt FROM memory_traces WHERE deleted = 0 GROUP BY scope');
         const tracesPerScope = {};
         for (const row of scopeRows) {
             tracesPerScope[row.scope] = row.cnt;
         }
         // Total document chunks.
-        const docsRow = db
-            .prepare('SELECT COUNT(*) AS cnt FROM documents')
-            .get();
+        const docsRow = await this._brain.get('SELECT COUNT(*) AS cnt FROM documents');
         const documentsIngested = docsRow?.cnt ?? 0;
         return {
             totalTraces,
@@ -889,7 +874,7 @@ export class Memory {
      */
     async close() {
         await this._initPromise;
-        this._brain.close();
+        await this._brain.close();
     }
     // =========================================================================
     // Private helpers
@@ -956,50 +941,58 @@ export class Memory {
      * importer-used `import_hash` key so dedup works across facade and import
      * workflows.
      */
-    _findExistingTraceByHash(contentHash, type, scope, scopeId) {
-        return this._brain.db
-            .prepare(`SELECT id, type, scope, content, embedding, strength, created_at,
-                last_accessed, retrieval_count, tags, emotions, metadata, deleted
-         FROM memory_traces
-         WHERE deleted = 0
-           AND type = ?
-           AND scope = ?
-           AND ifnull(json_extract(metadata, '$.scopeId'), '') = ?
-           AND (
-             json_extract(metadata, '$.content_hash') = ?
-             OR json_extract(metadata, '$.import_hash') = ?
-           )
-         LIMIT 1`)
-            .get(type, scope, scopeId, contentHash, contentHash);
+    async _findExistingTraceByHash(contentHash, type, scope, scopeId) {
+        const row = await this._brain.get(`SELECT id, type, scope, content, embedding, strength, created_at,
+              last_accessed, retrieval_count, tags, emotions, metadata, deleted
+       FROM memory_traces
+       WHERE deleted = 0
+         AND type = ?
+         AND scope = ?
+         AND ifnull(json_extract(metadata, '$.scopeId'), '') = ?
+         AND (
+           json_extract(metadata, '$.content_hash') = ?
+           OR json_extract(metadata, '$.import_hash') = ?
+         )
+       LIMIT 1`, [type, scope, scopeId, contentHash, contentHash]);
+        return row ?? undefined;
     }
     /**
      * Apply spaced-repetition access updates to recalled rows and persist the
      * updated retrieval metadata back to SQLite.
      */
-    _applyRecallAccessUpdates(rows) {
+    async _applyRecallAccessUpdates(rows) {
         if (rows.length === 0)
             return rows;
         const now = Date.now();
-        const updateStmt = this._brain.db.prepare(`UPDATE memory_traces
-       SET strength = ?, last_accessed = ?, retrieval_count = ?, metadata = ?
-       WHERE id = ?`);
-        return this._brain.db.transaction(() => rows.map((row) => {
-            const update = updateOnRetrieval(this._buildTrace(row), now);
-            const metadata = JSON.stringify(withPersistedDecayState(parseTraceMetadata(row.metadata), {
-                stability: update.stability,
-                accessCount: update.accessCount,
-                reinforcementInterval: update.reinforcementInterval,
-                nextReinforcementAt: update.nextReinforcementAt,
-            }));
-            updateStmt.run(update.encodingStrength, update.lastAccessedAt, update.retrievalCount, metadata, row.id);
-            return {
-                ...row,
-                strength: update.encodingStrength,
-                last_accessed: update.lastAccessedAt,
-                retrieval_count: update.retrievalCount,
-                metadata,
-            };
-        }))();
+        return this._brain.transaction(async (trx) => {
+            const results = [];
+            for (const row of rows) {
+                const update = updateOnRetrieval(this._buildTrace(row), now);
+                const metadata = JSON.stringify(withPersistedDecayState(parseTraceMetadata(row.metadata), {
+                    stability: update.stability,
+                    accessCount: update.accessCount,
+                    reinforcementInterval: update.reinforcementInterval,
+                    nextReinforcementAt: update.nextReinforcementAt,
+                }));
+                await trx.run(`UPDATE memory_traces
+           SET strength = ?, last_accessed = ?, retrieval_count = ?, metadata = ?
+           WHERE id = ?`, [
+                    update.encodingStrength,
+                    update.lastAccessedAt,
+                    update.retrievalCount,
+                    metadata,
+                    row.id,
+                ]);
+                results.push({
+                    ...row,
+                    strength: update.encodingStrength,
+                    last_accessed: update.lastAccessedAt,
+                    retrieval_count: update.retrievalCount,
+                    metadata,
+                });
+            }
+            return results;
+        });
     }
     /**
      * Persist one loaded document into the documents/chunks/traces tables.
@@ -1009,40 +1002,46 @@ export class Memory {
      */
     async _ingestLoadedDocument(source, doc, chunking, result) {
         const contentHash = sha256(doc.content);
-        const existingDoc = this._brain.db
-            .prepare(`SELECT id FROM documents WHERE content_hash = ? LIMIT 1`)
-            .get(contentHash);
+        const existingDoc = await this._brain.get(`SELECT id FROM documents WHERE content_hash = ? LIMIT 1`, [contentHash]);
         if (existingDoc) {
             return;
         }
         const chunks = await this._chunkingEngine.chunk(doc.content, chunking);
         const docId = `doc_${crypto.randomUUID()}`;
-        this._brain.db
-            .prepare(`INSERT INTO documents
-           (id, path, format, title, content_hash, chunk_count, metadata, ingested_at)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
-            .run(docId, doc.metadata.source ?? source, doc.format, doc.metadata.title ?? null, contentHash, chunks.length, JSON.stringify(doc.metadata), Date.now());
+        await this._brain.run(`INSERT INTO documents
+         (id, path, format, title, content_hash, chunk_count, metadata, ingested_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, [
+            docId,
+            doc.metadata.source ?? source,
+            doc.format,
+            doc.metadata.title ?? null,
+            contentHash,
+            chunks.length,
+            JSON.stringify(doc.metadata),
+            Date.now(),
+        ]);
         for (const chunk of chunks) {
             const chunkId = `chunk_${crypto.randomUUID()}`;
             const traceId = nextTraceId();
             const createdAt = Date.now();
-            this._brain.db
-                .prepare(`INSERT INTO memory_traces
-             (id, type, scope, content, embedding, strength, created_at,
-              last_accessed, retrieval_count, tags, emotions, metadata, deleted)
-           VALUES (?, 'semantic', 'user', ?, NULL, 1.0, ?, NULL, 0, '[]', '{}', ?, 0)`)
-                .run(traceId, chunk.content, createdAt, JSON.stringify(buildInitialTraceMetadata({
-                document_id: docId,
-                chunk_index: chunk.index,
-            }, { contentHash: sha256(chunk.content) })));
-            this._brain.db
-                .prepare(`INSERT INTO memory_traces_fts (rowid, content, tags)
-           VALUES (
-             (SELECT rowid FROM memory_traces WHERE id = ?),
-             ?,
-             '[]'
-           )`)
-                .run(traceId, chunk.content);
+            await this._brain.run(`INSERT INTO memory_traces
+           (id, type, scope, content, embedding, strength, created_at,
+            last_accessed, retrieval_count, tags, emotions, metadata, deleted)
+         VALUES (?, 'semantic', 'user', ?, NULL, 1.0, ?, NULL, 0, '[]', '{}', ?, 0)`, [
+                traceId,
+                chunk.content,
+                createdAt,
+                JSON.stringify(buildInitialTraceMetadata({
+                    document_id: docId,
+                    chunk_index: chunk.index,
+                }, { contentHash: sha256(chunk.content) })),
+            ]);
+            await this._brain.run(`INSERT INTO memory_traces_fts (rowid, content, tags)
+         VALUES (
+           (SELECT rowid FROM memory_traces WHERE id = ?),
+           ?,
+           '[]'
+         )`, [traceId, chunk.content]);
             if (this._config.graph && !this._memoryGraph.hasNode(traceId)) {
                 await this._memoryGraph.addNode(traceId, {
                     type: 'semantic',
@@ -1052,10 +1051,15 @@ export class Memory {
                     createdAt,
                 });
             }
-            this._brain.db
-                .prepare(`INSERT INTO document_chunks (id, document_id, trace_id, content, chunk_index, page_number, embedding)
-           VALUES (?, ?, ?, ?, ?, ?, NULL)`)
-                .run(chunkId, docId, traceId, chunk.content, chunk.index, chunk.pageNumber ?? null);
+            await this._brain.run(`INSERT INTO document_chunks (id, document_id, trace_id, content, chunk_index, page_number, embedding)
+         VALUES (?, ?, ?, ?, ?, ?, NULL)`, [
+                chunkId,
+                docId,
+                traceId,
+                chunk.content,
+                chunk.index,
+                chunk.pageNumber ?? null,
+            ]);
             result.chunksCreated++;
             result.tracesCreated++;
         }
@@ -1063,9 +1067,9 @@ export class Memory {
     /**
      * Rebuild the external-content FTS index after bulk import operations.
      */
-    _rebuildFtsIndex() {
+    async _rebuildFtsIndex() {
         try {
-            this._brain.db.exec(`INSERT INTO memory_traces_fts(memory_traces_fts) VALUES('rebuild')`);
+            await this._brain.exec(`INSERT INTO memory_traces_fts(memory_traces_fts) VALUES('rebuild')`);
         }
         catch {
             // Best-effort; imports still succeed even if the FTS rebuild is unavailable.