agentdb 3.0.0-alpha.9 → 3.1.0

package/dist/src/controllers/ReflexionMemory.js

@@ -7,31 +7,73 @@
  * Based on: "Reflexion: Language Agents with Verbal Reinforcement Learning"
  * https://arxiv.org/abs/2303.11366
  */
+import { normalizeRowId } from '../types/database.types.js';
+import { searchVectors } from '../backends/VectorBackend.js';
+import { sqlExactSource } from '../backends/ExactSearch.js';
 import { NodeIdMapper } from '../utils/NodeIdMapper.js';
-import { cosineSimilarity } from '../utils/vector-math.js';
+import { QueryCache } from '../core/QueryCache.js';
+import { TopK, squaredNorm, cosineWithQueryNorm } from '../utils/top-k.js';
+function finiteNumber(value, name) {
+    const n = Number(value);
+    if (!Number.isFinite(n))
+        throw new Error(`${name} must be a finite number`);
+    return n;
+}
+function positiveInt(value, name) {
+    const n = Math.floor(finiteNumber(value, name));
+    if (n < 1)
+        throw new Error(`${name} must be a positive integer`);
+    return n;
+}
+/** Vector ids this controller writes: the bare episode row id */
+const EPISODE_VECTOR_ID = /^\d+$/;
+/** Parse JSON from DB row values without throwing on malformed data. */
+function safeJsonParse(value, fallback) {
+    if (!value)
+        return fallback;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return fallback;
+    }
+}
 export class ReflexionMemory {
     db;
     embedder;
     vectorBackend;
     learningBackend;
     graphBackend;
-    constructor(db, embedder, vectorBackend, learningBackend, graphBackend) {
+    queryCache;
+    constructor(db, embedder, vectorBackend, learningBackend, graphBackend, cacheConfig) {
         this.db = db;
         this.embedder = embedder;
         this.vectorBackend = vectorBackend;
         this.learningBackend = learningBackend;
         this.graphBackend = graphBackend;
+        this.queryCache = new QueryCache(cacheConfig);
     }
     /**
      * Store a new episode with its critique and outcome
+     * Invalidates relevant cache entries
+     *
+     * Persistence guarantee (issue #128 fix):
+     *   storeEpisode() always writes to the SQLite `episodes` and
+     *   `episode_embeddings` tables when a SQL-capable connection is present,
+     *   even when a graph or vector backend handles the primary index. This
+     *   ensures data survives process restarts (graph/vector backends are
+     *   often in-memory or rebuildable from SQL).
      */
     async storeEpisode(episode) {
+        // Invalidate episode caches on write
+        this.queryCache.invalidateCategory('episodes');
+        this.queryCache.invalidateCategory('task-stats');
         // Use GraphDatabaseAdapter if available (AgentDB v2)
         if (this.graphBackend && 'storeEpisode' in this.graphBackend) {
             // GraphDatabaseAdapter has specialized storeEpisode method
             const graphAdapter = this.graphBackend;
             // Generate embedding for the task
-            const taskEmbedding = await this.embedder.embed(episode.task);
+            const taskEmbedding = await this.embedder.embedPassage(episode.task);
             // Create episode node using GraphDatabaseAdapter
             const nodeId = await graphAdapter.storeEpisode({
                 id: episode.id ? `episode-${episode.id}` : `episode-${Date.now()}-${Math.random()}`,
@@ -44,18 +86,21 @@ export class ReflexionMemory {
                 critique: episode.critique,
                 createdAt: episode.ts ? episode.ts * 1000 : Date.now(),
                 tokensUsed: episode.tokensUsed,
-                latencyMs: episode.latencyMs
+                latencyMs: episode.latencyMs,
             }, taskEmbedding);
             // Return a numeric ID (parse from string ID)
             const numericId = parseInt(nodeId.split('-').pop() || '0', 36);
             // Register mapping for later use by CausalMemoryGraph
             NodeIdMapper.getInstance().register(numericId, nodeId);
+            // #128: dual-write to SQL for restart-safe persistence. Graph adapter
+            // index is typically in-memory; SQL is the durable record.
+            this.dualWriteEpisodeToSQL(episode, taskEmbedding);
             return numericId;
         }
         // Use generic GraphBackend if available
         if (this.graphBackend) {
             // Generate embedding for the task
-            const taskEmbedding = await this.embedder.embed(episode.task);
+            const taskEmbedding = await this.embedder.embedPassage(episode.task);
             // Create episode node ID
             const nodeId = await this.graphBackend.createNode(['Episode'], {
                 sessionId: episode.sessionId,
@@ -69,22 +114,21 @@ export class ReflexionMemory {
                 tokensUsed: episode.tokensUsed || 0,
                 tags: episode.tags ? JSON.stringify(episode.tags) : '[]',
                 metadata: episode.metadata ? JSON.stringify(episode.metadata) : '{}',
-                createdAt: Date.now()
+                createdAt: Date.now(),
             });
             // Store embedding using vectorBackend if available
             if (this.vectorBackend && taskEmbedding) {
-                try {
-                    this.vectorBackend.insert(nodeId, taskEmbedding, {
-                        type: 'episode',
-                        sessionId: episode.sessionId
-                    });
-                }
-                catch { /* vectorBackend insert failed — graph node still created */ }
+                this.vectorBackend.insert(nodeId, taskEmbedding, {
+                    type: 'episode',
+                    sessionId: episode.sessionId,
+                });
             }
             // Return a numeric ID (parse from string ID)
             const numericId = parseInt(nodeId.split('-').pop() || '0', 36);
             // Register mapping for later use by CausalMemoryGraph
             NodeIdMapper.getInstance().register(numericId, nodeId);
+            // #128: dual-write to SQL for restart-safe persistence.
+            this.dualWriteEpisodeToSQL(episode, taskEmbedding);
             return numericId;
         }
         // Fallback to SQLite (v1 compatibility)
@@ -97,16 +141,13 @@ export class ReflexionMemory {
         const tags = episode.tags ? JSON.stringify(episode.tags) : null;
         const metadata = episode.metadata ? JSON.stringify(episode.metadata) : null;
         const result = stmt.run(episode.sessionId, episode.task, episode.input || null, episode.output || null, episode.critique || null, episode.reward, episode.success ? 1 : 0, episode.latencyMs || null, episode.tokensUsed || null, tags, metadata);
-        const episodeId = result.lastInsertRowid;
+        const episodeId = normalizeRowId(result.lastInsertRowid);
         // Generate and store embedding
         const text = this.buildEpisodeText(episode);
-        const embedding = await this.embedder.embed(text);
+        const embedding = await this.embedder.embedPassage(text);
         // Use vector backend if available (150x faster retrieval)
         if (this.vectorBackend) {
-            try {
-                this.vectorBackend.insert(episodeId.toString(), embedding);
-            }
-            catch { /* vectorBackend insert failed — SQL fallback used */ }
+            this.vectorBackend.insert(episodeId.toString(), embedding);
         }
         // Also store in SQL for fallback
         this.storeEmbedding(episodeId, embedding);
@@ -124,155 +165,213 @@ export class ReflexionMemory {
                     task: episode.task,
                     sessionId: episode.sessionId,
                     latencyMs: episode.latencyMs,
-                    tokensUsed: episode.tokensUsed
-                }
+                    tokensUsed: episode.tokensUsed,
+                },
             });
         }
         return episodeId;
     }
     /**
      * Retrieve relevant past episodes for a new task attempt
+     * Results are cached for improved performance
      */
     async retrieveRelevant(query) {
-        const { task, currentState = '', k = 5, minReward, onlyFailures = false, onlySuccesses = false, timeWindowDays } = query;
-        // Generate query embedding
+        const { task, currentState = '', k = 5, minReward, onlyFailures = false, onlySuccesses = false, timeWindowDays, } = query;
+        // Check cache first
+        const cacheKey = this.queryCache.generateKey('retrieveRelevant', [task, currentState, k, minReward, onlyFailures, onlySuccesses, timeWindowDays], 'episodes');
+        const cached = this.queryCache.get(cacheKey);
+        if (cached) {
+            return cached;
+        }
+        // Generate and enhance query embedding
+        const queryEmbedding = await this.prepareQueryEmbedding(task, currentState, k);
+        // Try different retrieval strategies in order of preference
+        let episodes = [];
+        if (this.graphBackend && 'searchSimilarEpisodes' in this.graphBackend) {
+            episodes = await this.retrieveFromGraphAdapter(queryEmbedding, query);
+        }
+        else if (this.graphBackend && 'execute' in this.graphBackend) {
+            episodes = await this.retrieveFromGenericGraph(query);
+        }
+        else if (this.vectorBackend) {
+            episodes = await this.retrieveFromVectorBackend(queryEmbedding, query);
+        }
+        else {
+            episodes = await this.retrieveFromSQLFallback(queryEmbedding, query);
+        }
+        // Cache and return results
+        this.queryCache.set(cacheKey, episodes);
+        return episodes;
+    }
+    /**
+     * Prepare and enhance query embedding for search
+     */
+    async prepareQueryEmbedding(task, currentState, k) {
         const queryText = currentState ? `${task}\n${currentState}` : task;
-        let queryEmbedding = await this.embedder.embed(queryText);
+        let queryEmbedding = await this.embedder.embedQuery(queryText);
         // Enhance query with GNN if learning backend available
         if (this.learningBackend) {
             queryEmbedding = await this.enhanceQueryWithGNN(queryEmbedding, k);
         }
-        // Use GraphDatabaseAdapter if available (AgentDB v2)
-        if (this.graphBackend && 'searchSimilarEpisodes' in this.graphBackend) {
-            const graphAdapter = this.graphBackend;
-            // Search using vector similarity
-            const results = await graphAdapter.searchSimilarEpisodes(queryEmbedding, k * 3);
-            // Apply filters
-            const filtered = results.filter((ep) => {
-                if (minReward !== undefined && ep.reward < minReward)
-                    return false;
-                if (onlyFailures && ep.success)
-                    return false;
-                if (onlySuccesses && !ep.success)
-                    return false;
-                if (timeWindowDays && ep.createdAt < (Date.now() - timeWindowDays * 86400000))
-                    return false;
-                return true;
-            });
-            // Convert to EpisodeWithEmbedding format
-            const episodes = filtered.slice(0, k).map((ep) => ({
-                id: parseInt(ep.id.split('-').pop() || '0', 36),
-                sessionId: ep.sessionId,
-                task: ep.task,
-                input: ep.input,
-                output: ep.output,
-                critique: ep.critique,
-                reward: ep.reward,
-                success: ep.success,
-                latencyMs: ep.latencyMs,
-                tokensUsed: ep.tokensUsed,
-                ts: Math.floor(ep.createdAt / 1000)
-            }));
-            return episodes;
-        }
-        // Use generic GraphBackend if available
-        if (this.graphBackend && 'execute' in this.graphBackend) {
-            // Build Cypher query with filters
-            let cypherQuery = 'MATCH (e:Episode) WHERE 1=1';
-            if (minReward !== undefined) {
-                cypherQuery += ` AND e.reward >= ${minReward}`;
-            }
-            if (onlyFailures) {
-                cypherQuery += ` AND e.success = false`;
-            }
-            if (onlySuccesses) {
-                cypherQuery += ` AND e.success = true`;
-            }
-            if (timeWindowDays) {
-                const cutoff = Date.now() - timeWindowDays * 86400000;
-                cypherQuery += ` AND e.createdAt >= ${cutoff}`;
+        return queryEmbedding;
+    }
+    /**
+     * Retrieve episodes using GraphDatabaseAdapter (AgentDB v2)
+     */
+    async retrieveFromGraphAdapter(queryEmbedding, query) {
+        const { k = 5, minReward, onlyFailures, onlySuccesses, timeWindowDays } = query;
+        const graphAdapter = this.graphBackend;
+        // Search using vector similarity
+        const results = await graphAdapter.searchSimilarEpisodes(queryEmbedding, k * 3);
+        // Apply filters
+        const filtered = this.applyEpisodeFilters(results, {
+            minReward,
+            onlyFailures,
+            onlySuccesses,
+            timeWindowDays,
+        });
+        // Convert to EpisodeWithEmbedding format
+        return filtered.slice(0, k).map((ep) => this.convertGraphEpisode(ep));
+    }
+    /**
+     * Retrieve episodes using generic GraphBackend
+     */
+    async retrieveFromGenericGraph(query) {
+        const { k = 5 } = query;
+        const cypherQuery = this.buildCypherQuery(query);
+        const result = await this.graphBackend.execute(cypherQuery);
+        // Convert to EpisodeWithEmbedding format
+        const episodes = result.rows.map((row) => this.convertCypherEpisode(row.e));
+        return episodes.slice(0, k);
+    }
+    /**
+     * Retrieve episodes using VectorBackend (150x faster)
+     */
+    async retrieveFromVectorBackend(queryEmbedding, query) {
+        const { k = 5, minReward, onlyFailures, onlySuccesses, timeWindowDays } = query;
+        // Get candidates from vector backend; small or short answers are
+        // completed by exact cosine over episode_embeddings (ADR-015)
+        const searchResults = await searchVectors(this.vectorBackend, queryEmbedding, k * 3, { threshold: 0.0 }, sqlExactSource(this.db, {
+            table: 'episode_embeddings',
+            idColumn: 'episode_id',
+            vectorId: (id) => String(id),
+            owns: (hit) => EPISODE_VECTOR_ID.test(hit.id),
+        }));
+        // The vector backend may be shared with other controllers ("skill:N",
+        // "causal-edge:N"); episode vectors use the bare numeric row id.
+        const episodeResults = searchResults.filter((r) => EPISODE_VECTOR_ID.test(r.id));
+        const episodeIds = episodeResults.map((r) => Number(r.id));
+        if (episodeIds.length === 0) {
+            // No usable hits although episodes exist (empty or crowded-out index):
+            // answer from the SQL embeddings instead of returning nothing.
+            if (this.db.prepare('SELECT 1 FROM episode_embeddings LIMIT 1').get()) {
+                return this.retrieveFromSQLFallback(queryEmbedding, query);
             }
-            cypherQuery += ` RETURN e LIMIT ${k * 3}`;
-            const result = await this.graphBackend.execute(cypherQuery);
-            // Convert to EpisodeWithEmbedding format
-            const episodes = result.rows.map((row) => {
-                const node = row.e;
-                return {
-                    id: parseInt(node.id.split('-').pop() || '0', 36),
-                    sessionId: node.properties.sessionId,
-                    task: node.properties.task,
-                    input: node.properties.input,
-                    output: node.properties.output,
-                    critique: node.properties.critique,
-                    reward: typeof node.properties.reward === 'string' ? parseFloat(node.properties.reward) : node.properties.reward,
-                    success: typeof node.properties.success === 'string' ? node.properties.success === 'true' : node.properties.success,
-                    latencyMs: node.properties.latencyMs,
-                    tokensUsed: node.properties.tokensUsed,
-                    tags: node.properties.tags ? JSON.parse(node.properties.tags) : [],
-                    metadata: node.properties.metadata ? JSON.parse(node.properties.metadata) : {},
-                    ts: Math.floor(node.properties.createdAt / 1000)
-                };
-            });
-            return episodes.slice(0, k);
+            return [];
         }
-        // Use optimized vector backend if available (150x faster)
-        if (this.vectorBackend) {
-            try {
-                // Get candidates from vector backend
-                const searchResults = this.vectorBackend.search(queryEmbedding, k * 3, {
-                    threshold: 0.0
-                });
-                // Fetch full episode data from DB
-                const episodeIds = searchResults.map(r => parseInt(r.id));
-                if (episodeIds.length === 0) {
-                    return [];
-                }
-                const placeholders = episodeIds.map(() => '?').join(',');
-                const stmt = this.db.prepare(`
-        SELECT * FROM episodes
-        WHERE id IN (${placeholders})
-      `);
-                const rows = stmt.all(...episodeIds);
-                const episodeMap = new Map(rows.map(r => [r.id.toString(), r]));
-                // Map results back with similarity scores and apply filters
-                const episodes = [];
-                for (const result of searchResults) {
-                    const row = episodeMap.get(result.id);
-                    if (!row)
-                        continue;
-                    // Apply additional filters
-                    if (minReward !== undefined && row.reward < minReward)
-                        continue;
-                    if (onlyFailures && row.success === 1)
-                        continue;
-                    if (onlySuccesses && row.success === 0)
-                        continue;
-                    if (timeWindowDays && row.ts < (Date.now() / 1000 - timeWindowDays * 86400))
-                        continue;
-                    episodes.push({
-                        id: row.id,
-                        ts: row.ts,
-                        sessionId: row.session_id,
-                        task: row.task,
-                        input: row.input,
-                        output: row.output,
-                        critique: row.critique,
-                        reward: row.reward,
-                        success: row.success === 1,
-                        latencyMs: row.latency_ms,
-                        tokensUsed: row.tokens_used,
-                        tags: row.tags ? JSON.parse(row.tags) : undefined,
-                        metadata: row.metadata ? JSON.parse(row.metadata) : undefined,
-                        similarity: result.similarity
-                    });
-                    if (episodes.length >= k)
-                        break;
-                }
-                return episodes;
+        const rows = this.fetchEpisodesByIds(episodeIds);
+        const episodeMap = new Map(rows.map((r) => [r.id.toString(), r]));
+        // Map results with similarity scores and apply filters
+        const episodes = [];
+        for (const result of episodeResults) {
+            const row = episodeMap.get(result.id);
+            if (!row)
+                continue;
+            // Apply filters
+            if (!this.passesEpisodeFilters(row, { minReward, onlyFailures, onlySuccesses, timeWindowDays })) {
+                continue;
             }
-            catch { /* vectorBackend search failed — fall through to SQL */ }
+            episodes.push(this.convertDatabaseEpisode(row, result.similarity));
+            if (episodes.length >= k)
+                break;
+        }
+        return episodes;
+    }
+    /**
+     * Retrieve episodes using SQL-based similarity search (fallback)
+     */
+    async retrieveFromSQLFallback(queryEmbedding, query) {
+        const { k = 5 } = query;
+        const { whereClause, params } = this.buildSQLFilters(query);
+        const stmt = this.db.prepare(`
+      SELECT e.*, ee.embedding
+      FROM episodes e
+      JOIN episode_embeddings ee ON e.id = ee.episode_id
+      ${whereClause}
+      ORDER BY e.reward DESC
+    `);
+        const rows = stmt.all(...params);
+        // Bounded top-k over the scan; only the winners are converted. Ordering
+        // matches the old sort on (similarity || 0) with scan order on ties.
+        const queryNorm = Math.sqrt(squaredNorm(queryEmbedding));
+        const top = new TopK(k);
+        for (const row of rows) {
+            const embedding = this.deserializeEmbedding(row.embedding);
+            const similarity = cosineWithQueryNorm(queryEmbedding, queryNorm, embedding);
+            top.push(similarity || 0, { row, embedding, similarity });
+        }
+        return top
+            .sorted()
+            .map(({ item }) => this.convertDatabaseEpisode(item.row, item.similarity, item.embedding));
+    }
+    /**
+     * Apply episode filters to search results
+     */
+    applyEpisodeFilters(episodes, filters) {
+        return episodes.filter((ep) => {
+            if (filters.minReward !== undefined && ep.reward < filters.minReward)
+                return false;
+            if (filters.onlyFailures && ep.success)
+                return false;
+            if (filters.onlySuccesses && !ep.success)
+                return false;
+            if (filters.timeWindowDays && ep.createdAt < Date.now() - filters.timeWindowDays * 86400000)
+                return false;
+            return true;
+        });
+    }
+    /**
+     * Check if database row passes episode filters
+     */
+    passesEpisodeFilters(row, filters) {
+        if (filters.minReward !== undefined && row.reward < filters.minReward)
+            return false;
+        if (filters.onlyFailures && row.success === 1)
+            return false;
+        if (filters.onlySuccesses && row.success === 0)
+            return false;
+        if (filters.timeWindowDays && row.ts < Date.now() / 1000 - filters.timeWindowDays * 86400)
+            return false;
+        return true;
+    }
+    /**
+     * Build Cypher query with filters
+     */
+    buildCypherQuery(query) {
+        const { k = 5, minReward, onlyFailures, onlySuccesses, timeWindowDays } = query;
+        let cypherQuery = 'MATCH (e:Episode) WHERE 1=1';
+        // Values are spliced into Cypher text, so only finite numbers get through
+        if (minReward !== undefined) {
+            cypherQuery += ` AND e.reward >= ${finiteNumber(minReward, 'minReward')}`;
+        }
+        if (onlyFailures) {
+            cypherQuery += ` AND e.success = false`;
         }
-        // Fallback to SQL-based similarity search
+        if (onlySuccesses) {
+            cypherQuery += ` AND e.success = true`;
+        }
+        if (timeWindowDays) {
+            const cutoff = Date.now() - finiteNumber(timeWindowDays, 'timeWindowDays') * 86400000;
+            cypherQuery += ` AND e.createdAt >= ${cutoff}`;
+        }
+        cypherQuery += ` RETURN e LIMIT ${positiveInt(k, 'k') * 3}`;
+        return cypherQuery;
+    }
+    /**
+     * Build SQL WHERE clause and parameters for filters
+     */
+    buildSQLFilters(query) {
+        const { minReward, onlyFailures, onlySuccesses, timeWindowDays } = query;
         const filters = [];
         const params = [];
         if (minReward !== undefined) {
@@ -290,46 +389,93 @@ export class ReflexionMemory {
             params.push(timeWindowDays * 86400);
         }
         const whereClause = filters.length > 0 ? `WHERE ${filters.join(' AND ')}` : '';
+        return { whereClause, params };
+    }
+    /**
+     * Fetch episodes by IDs from database
+     */
+    fetchEpisodesByIds(episodeIds) {
+        const placeholders = episodeIds.map(() => '?').join(',');
         const stmt = this.db.prepare(`
-      SELECT
-        e.*,
-        ee.embedding
-      FROM episodes e
-      JOIN episode_embeddings ee ON e.id = ee.episode_id
-      ${whereClause}
-      ORDER BY e.reward DESC
+      SELECT * FROM episodes
+      WHERE id IN (${placeholders})
     `);
-        const rows = stmt.all(...params);
-        // Calculate similarities manually
-        const episodes = rows.map(row => {
-            const embedding = this.deserializeEmbedding(row.embedding);
-            const similarity = cosineSimilarity(queryEmbedding, embedding);
-            return {
-                id: row.id,
-                ts: row.ts,
-                sessionId: row.session_id,
-                task: row.task,
-                input: row.input,
-                output: row.output,
-                critique: row.critique,
-                reward: row.reward,
-                success: row.success === 1,
-                latencyMs: row.latency_ms,
-                tokensUsed: row.tokens_used,
-                tags: row.tags ? JSON.parse(row.tags) : undefined,
-                metadata: row.metadata ? JSON.parse(row.metadata) : undefined,
-                embedding,
-                similarity
-            };
-        });
-        // Sort by similarity and return top-k
-        episodes.sort((a, b) => (b.similarity || 0) - (a.similarity || 0));
-        return episodes.slice(0, k);
+        return stmt.all(...episodeIds);
+    }
+    /**
+     * Convert GraphDatabaseAdapter episode to EpisodeWithEmbedding
+     */
+    convertGraphEpisode(ep) {
+        return {
+            id: parseInt(ep.id.split('-').pop() || '0', 36),
+            sessionId: ep.sessionId,
+            task: ep.task,
+            input: ep.input,
+            output: ep.output,
+            critique: ep.critique,
+            reward: ep.reward,
+            success: ep.success,
+            latencyMs: ep.latencyMs,
+            tokensUsed: ep.tokensUsed,
+            ts: Math.floor(ep.createdAt / 1000),
+        };
     }
     /**
-     * Get statistics for a task
+     * Convert Cypher query result to EpisodeWithEmbedding
+     */
+    convertCypherEpisode(node) {
+        return {
+            id: parseInt(node.id.split('-').pop() || '0', 36),
+            sessionId: node.properties.sessionId,
+            task: node.properties.task,
+            input: node.properties.input,
+            output: node.properties.output,
+            critique: node.properties.critique,
+            reward: typeof node.properties.reward === 'string'
+                ? parseFloat(node.properties.reward)
+                : node.properties.reward,
+            success: typeof node.properties.success === 'string'
+                ? node.properties.success === 'true'
+                : node.properties.success,
+            latencyMs: node.properties.latencyMs,
+            tokensUsed: node.properties.tokensUsed,
+            tags: safeJsonParse(node.properties.tags, []),
+            metadata: safeJsonParse(node.properties.metadata, {}),
+            ts: Math.floor(node.properties.createdAt / 1000),
+        };
+    }
+    /**
+     * Convert database row to EpisodeWithEmbedding
+     */
+    convertDatabaseEpisode(row, similarity, embedding) {
+        return {
+            id: row.id,
+            ts: row.ts,
+            sessionId: row.session_id,
+            task: row.task,
+            input: row.input ?? undefined,
+            output: row.output ?? undefined,
+            critique: row.critique ?? undefined,
+            reward: row.reward,
+            success: row.success === 1,
+            latencyMs: row.latency_ms ?? undefined,
+            tokensUsed: row.tokens_used ?? undefined,
+            tags: safeJsonParse(row.tags, undefined),
+            metadata: safeJsonParse(row.metadata, undefined),
+            embedding,
+            similarity,
+        };
+    }
+    /**
+     * Get statistics for a task (cached)
      */
     getTaskStats(task, timeWindowDays) {
+        // Check cache first
+        const cacheKey = this.queryCache.generateKey('getTaskStats', [task, timeWindowDays], 'task-stats');
+        const cached = this.queryCache.get(cacheKey);
+        if (cached) {
+            return cached;
+        }
         const windowFilter = timeWindowDays
             ? `AND ts > strftime('%s', 'now') - ${timeWindowDays * 86400}`
             : '';
@@ -359,41 +505,59 @@ export class ReflexionMemory {
         const improvementTrend = trend.recent_reward && trend.older_reward
             ? (trend.recent_reward - trend.older_reward) / trend.older_reward
             : 0;
-        return {
-            totalAttempts: stats.total || 0,
-            successRate: stats.success_rate || 0,
-            avgReward: stats.avg_reward || 0,
-            avgLatency: stats.avg_latency || 0,
-            improvementTrend
+        const results = {
+            totalAttempts: stats?.total ?? 0,
+            successRate: stats?.success_rate ?? 0,
+            avgReward: stats?.avg_reward ?? 0,
+            avgLatency: stats?.avg_latency ?? 0,
+            improvementTrend,
         };
+        // Cache the results
+        this.queryCache.set(cacheKey, results);
+        return results;
     }
     /**
-     * Build critique summary from similar failed episodes
+     * Build critique summary from similar failed episodes (cached)
      */
     async getCritiqueSummary(query) {
+        // Check cache first
+        const cacheKey = this.queryCache.generateKey('getCritiqueSummary', [query.task, query.k], 'episodes');
+        const cached = this.queryCache.get(cacheKey);
+        if (cached) {
+            return cached;
+        }
         const failures = await this.retrieveRelevant({
             ...query,
             onlyFailures: true,
-            k: 3
+            k: 3,
         });
         if (failures.length === 0) {
             return 'No prior failures found for this task.';
         }
         const critiques = failures
-            .filter(ep => ep.critique)
+            .filter((ep) => ep.critique)
             .map((ep, i) => `${i + 1}. ${ep.critique} (reward: ${ep.reward.toFixed(2)})`)
             .join('\n');
-        return `Prior failures and lessons learned:\n${critiques}`;
+        const result = `Prior failures and lessons learned:\n${critiques}`;
+        // Cache the result
+        this.queryCache.set(cacheKey, result);
+        return result;
     }
     /**
-     * Get successful strategies for a task
+     * Get successful strategies for a task (cached)
      */
     async getSuccessStrategies(query) {
+        // Check cache first
+        const cacheKey = this.queryCache.generateKey('getSuccessStrategies', [query.task, query.k], 'episodes');
+        const cached = this.queryCache.get(cacheKey);
+        if (cached) {
+            return cached;
+        }
         const successes = await this.retrieveRelevant({
             ...query,
             onlySuccesses: true,
             minReward: 0.7,
-            k: 3
+            k: 3,
         });
         if (successes.length === 0) {
             return 'No successful strategies found for this task.';
@@ -404,7 +568,10 @@ export class ReflexionMemory {
             return `${i + 1}. Approach (reward ${ep.reward.toFixed(2)}): ${approach}...`;
         })
             .join('\n');
-        return `Successful strategies:\n${strategies}`;
+        const result = `Successful strategies:\n${strategies}`;
+        // Cache the result
+        this.queryCache.set(cacheKey, result);
+        return result;
     }
     /**
      * Get recent episodes for a session
@@ -417,24 +584,25 @@ export class ReflexionMemory {
       LIMIT ?
     `);
         const rows = stmt.all(sessionId, limit);
-        return rows.map(row => ({
+        return rows.map((row) => ({
             id: row.id,
             ts: row.ts,
             sessionId: row.session_id,
             task: row.task,
-            input: row.input,
-            output: row.output,
-            critique: row.critique,
+            input: row.input ?? undefined,
+            output: row.output ?? undefined,
+            critique: row.critique ?? undefined,
             reward: row.reward,
             success: row.success === 1,
-            latencyMs: row.latency_ms,
-            tokensUsed: row.tokens_used,
-            tags: row.tags ? JSON.parse(row.tags) : undefined,
-            metadata: row.metadata ? JSON.parse(row.metadata) : undefined
+            latencyMs: row.latency_ms ?? undefined,
+            tokensUsed: row.tokens_used ?? undefined,
+            tags: safeJsonParse(row.tags, undefined),
+            metadata: safeJsonParse(row.metadata, undefined),
         }));
     }
     /**
      * Prune low-quality episodes based on TTL and quality threshold
+     * Invalidates cache on completion
      */
     pruneEpisodes(config) {
         const { minReward = 0.3, maxAgeDays = 30, keepMinPerTask = 5 } = config;
@@ -455,6 +623,11 @@ export class ReflexionMemory {
       )
     `);
         const result = stmt.run(minReward, maxAgeDays * 86400, keepMinPerTask);
+        // Invalidate caches after pruning
+        if (result.changes > 0) {
+            this.queryCache.invalidateCategory('episodes');
+            this.queryCache.invalidateCategory('task-stats');
+        }
         return result.changes;
     }
     // ========================================================================
@@ -485,6 +658,17 @@ export class ReflexionMemory {
     deserializeEmbedding(buffer) {
         return new Float32Array(buffer.buffer, buffer.byteOffset, buffer.length / 4);
     }
+    cosineSimilarity(a, b) {
+        let dotProduct = 0;
+        let normA = 0;
+        let normB = 0;
+        for (let i = 0; i < a.length; i++) {
+            dotProduct += a[i] * b[i];
+            normA += a[i] * a[i];
+            normB += b[i] * b[i];
+        }
+        return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
+    }
     // ========================================================================
     // GNN and Graph Integration Methods
     // ========================================================================
@@ -503,7 +687,7 @@ export class ReflexionMemory {
             success: episode.success,
             timestamp: episode.ts || Date.now(),
             latencyMs: episode.latencyMs,
-            tokensUsed: episode.tokensUsed
+            tokensUsed: episode.tokensUsed,
         });
         // Find similar episodes using graph vector search
         const similarEpisodes = await this.graphBackend.vectorSearch(embedding, 5, nodeId);
@@ -511,8 +695,8 @@ export class ReflexionMemory {
         for (const similar of similarEpisodes) {
             if (similar.id !== nodeId && similar.properties.episodeId !== episodeId) {
                 await this.graphBackend.createRelationship(nodeId, similar.id, 'SIMILAR_TO', {
-                    similarity: cosineSimilarity(embedding, similar.embedding || new Float32Array()),
-                    createdAt: Date.now()
+                    similarity: this.cosineSimilarity(embedding, similar.embedding || new Float32Array()),
+                    createdAt: Date.now(),
                 });
             }
         }
@@ -523,13 +707,15 @@ export class ReflexionMemory {
             // Create session node if doesn't exist
             sessionNodeId = await this.graphBackend.createNode(['Session'], {
                 sessionId: episode.sessionId,
-                startTime: episode.ts || Date.now()
+                startTime: episode.ts || Date.now(),
             });
         }
         else {
             sessionNodeId = sessionNodes.rows[0].s.id;
         }
-        await this.graphBackend.createRelationship(nodeId, sessionNodeId, 'BELONGS_TO_SESSION', { timestamp: episode.ts || Date.now() });
+        await this.graphBackend.createRelationship(nodeId, sessionNodeId, 'BELONGS_TO_SESSION', {
+            timestamp: episode.ts || Date.now(),
+        });
         // If episode has critique, create causal relationship to previous failures
         if (episode.critique && !episode.success) {
             const previousFailures = await this.graphBackend.execute(`MATCH (e:Episode:Failure {sessionId: $sessionId})
@@ -540,7 +726,7 @@ export class ReflexionMemory {
             for (const prevFailure of previousFailures.rows) {
                 await this.graphBackend.createRelationship(nodeId, prevFailure.e.id, 'LEARNED_FROM', {
                     critique: episode.critique,
-                    improvementAttempt: true
+                    improvementAttempt: true,
                 });
             }
         }
@@ -554,8 +740,8 @@ export class ReflexionMemory {
         }
         try {
             // Get initial neighbors
-            const initialResults = this.vectorBackend.search(queryEmbedding, k * 2, {
-                threshold: 0.0
+            const initialResults = await searchVectors(this.vectorBackend, queryEmbedding, k * 2, {
+                threshold: 0.0,
             });
             if (initialResults.length === 0) {
                 return queryEmbedding;
@@ -563,14 +749,19 @@ export class ReflexionMemory {
             // Fetch neighbor embeddings
             const neighborEmbeddings = [];
             const weights = [];
-            const episodeIds = initialResults.map(r => r.id);
+            const episodeIds = initialResults.map((r) => r.id).filter((id) => EPISODE_VECTOR_ID.test(id));
+            if (episodeIds.length === 0) {
+                return queryEmbedding;
+            }
             const placeholders = episodeIds.map(() => '?').join(',');
-            const episodes = this.db.prepare(`
+            const episodes = this.db
+                .prepare(`
         SELECT ee.embedding, e.reward
         FROM episode_embeddings ee
         JOIN episodes e ON e.id = ee.episode_id
         WHERE ee.episode_id IN (${placeholders})
-      `).all(...episodeIds);
+      `)
+                .all(...episodeIds);
             for (const ep of episodes) {
                 const embedding = this.deserializeEmbedding(ep.embedding);
                 neighborEmbeddings.push(embedding);
@@ -607,7 +798,7 @@ export class ReflexionMemory {
         return {
             similar: (row.similar || []).filter((id) => id != null),
             session: row.session || '',
-            learnedFrom: (row.learnedFrom || []).filter((id) => id != null)
+            learnedFrom: (row.learnedFrom || []).filter((id) => id != null),
         };
     }
     /**
@@ -624,11 +815,11 @@ export class ReflexionMemory {
             return;
         }
         const result = await this.learningBackend.train(options);
-        console.log('[ReflexionMemory] GNN training complete:', {
+        console.error('[ReflexionMemory] GNN training complete:', {
             epochs: result.epochs,
             finalLoss: result.finalLoss.toFixed(4),
             improvement: `${(result.improvement * 100).toFixed(1)}%`,
-            duration: `${result.duration}ms`
+            duration: `${result.duration}ms`,
         });
     }
     /**
@@ -649,5 +840,281 @@ export class ReflexionMemory {
         }
         return this.graphBackend.getStats();
     }
+    /**
+     * Get query cache statistics
+     */
+    getCacheStats() {
+        return this.queryCache.getStatistics();
+    }
+    /**
+     * Clear query cache
+     */
+    clearCache() {
+        this.queryCache.clear();
+    }
+    /**
+     * Prune expired cache entries
+     */
+    pruneCache() {
+        return this.queryCache.pruneExpired();
+    }
+    /**
+     * Warm cache with common queries
+     */
+    async warmCache(sessionId) {
+        await this.queryCache.warm(async (cache) => {
+            // Warm cache with recent sessions if sessionId provided
+            if (sessionId) {
+                const recent = await this.getRecentEpisodes(sessionId, 10);
+                // Episodes are already loaded, cache will be populated on next access
+            }
+        });
+    }
+    /**
+     * Delete an episode by id. Closes the gap from issue #150 (downstream:
+     * ruflo#1784, RuVector#427) — once an episode is written there was no
+     * first-class way to remove it through any backend.
+     *
+     * Strategy mirrors storeEpisode: when a graph backend is present we go
+     * through it (`graphAdapter.deleteNode` / `graphBackend.deleteNode` —
+     * both Cypher-backed under the hood), and we ALWAYS also purge the SQL
+     * `episodes` and `episode_embeddings` rows so durable storage stays in
+     * sync. Vector backend entries are removed too when present.
+     *
+     * @returns True if the episode existed in any backend and was removed.
+     */
+    async deleteEpisode(id) {
+        const numericId = typeof id === 'number' ? id : parseInt(String(id), 10);
+        const stringId = String(id);
+        // Invalidate caches up front — failures below shouldn't leave stale reads.
+        this.queryCache.invalidateCategory('episodes');
+        this.queryCache.invalidateCategory('task-stats');
+        let removed = false;
+        // 1. Graph adapter (AgentDB v2 fast path)
+        if (this.graphBackend && 'storeEpisode' in this.graphBackend) {
+            const adapter = this.graphBackend;
+            if (typeof adapter.deleteNode === 'function') {
+                try {
+                    // Adapter accepts either the canonical "episode-<id>" key or a raw
+                    // id; try the canonical form first since that's what storeEpisode
+                    // emits.
+                    const r = await adapter.deleteNode(`episode-${numericId}`, { cascade: true });
+                    if (r?.deletedNode)
+                        removed = true;
+                    if (!removed) {
+                        const r2 = await adapter.deleteNode(stringId, { cascade: true });
+                        if (r2?.deletedNode)
+                            removed = true;
+                    }
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    // eslint-disable-next-line no-console
+                    console.warn(`[ReflexionMemory] deleteEpisode: graph adapter delete failed: ${msg}`);
+                }
+            }
+        }
+        // 2. Generic graph backend
+        else if (this.graphBackend && typeof this.graphBackend.deleteNode === 'function') {
+            try {
+                const r = await this.graphBackend.deleteNode(stringId);
+                if (r === true)
+                    removed = true;
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                // eslint-disable-next-line no-console
+                console.warn(`[ReflexionMemory] deleteEpisode: graph backend delete failed: ${msg}`);
+            }
+        }
+        // 3. Vector backend (HNSW/RuVector); some implementations don't expose
+        //    delete — guard with a feature check.
+        if (this.vectorBackend && typeof this.vectorBackend.delete === 'function') {
+            try {
+                const r = await this.vectorBackend.delete(String(numericId));
+                if (r === true)
+                    removed = true;
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                // eslint-disable-next-line no-console
+                console.warn(`[ReflexionMemory] deleteEpisode: vector backend delete failed: ${msg}`);
+            }
+        }
+        // 4. SQL durable storage — always attempt so persistence stays clean
+        //    even when the primary backend was a no-op.
+        if (this.db && typeof this.db.prepare === 'function' && Number.isFinite(numericId)) {
+            try {
+                const embStmt = this.db.prepare(`DELETE FROM episode_embeddings WHERE episode_id = ?`);
+                embStmt.run(numericId);
+                const stmt = this.db.prepare(`DELETE FROM episodes WHERE id = ?`);
+                const r = stmt.run(numericId);
+                const changes = r?.changes ?? 0;
+                if (changes > 0)
+                    removed = true;
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                if (!/no such table/i.test(msg)) {
+                    // eslint-disable-next-line no-console
+                    console.warn(`[ReflexionMemory] deleteEpisode: SQL delete failed: ${msg}`);
+                }
+            }
+        }
+        return removed;
+    }
+    /**
+     * Dual-write helper for issue #128.
+     *
+     * Inserts the given episode into the SQLite `episodes` and
+     * `episode_embeddings` tables when the underlying connection supports it.
+     * Used when a graph or vector backend handles the primary index but the
+     * caller still wants restart-safe persistence.
+     *
+     * Errors are swallowed and logged — the primary write to the graph/vector
+     * backend has already succeeded, and we don't want to fail the caller if
+     * SQL persistence is unavailable (e.g. read-only DB, schema not present).
+     */
+    dualWriteEpisodeToSQL(episode, embedding) {
+        if (!this.db || typeof this.db.prepare !== 'function')
+            return;
+        try {
+            const stmt = this.db.prepare(`
+        INSERT INTO episodes (
+          session_id, task, input, output, critique, reward, success,
+          latency_ms, tokens_used, tags, metadata
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `);
+            const tags = episode.tags ? JSON.stringify(episode.tags) : null;
+            const metadata = episode.metadata ? JSON.stringify(episode.metadata) : null;
+            const result = stmt.run(episode.sessionId, episode.task, episode.input ?? null, episode.output ?? null, episode.critique ?? null, episode.reward, episode.success ? 1 : 0, episode.latencyMs ?? null, episode.tokensUsed ?? null, tags, metadata);
+            if (embedding) {
+                const episodeId = normalizeRowId(result.lastInsertRowid);
+                this.storeEmbedding(episodeId, embedding);
+            }
+        }
+        catch (err) {
+            // The expected failure here is "no such table: episodes" on databases
+            // that intentionally don't carry the v1 schema. Don't escalate — the
+            // primary backend already has the data.
+            const msg = err instanceof Error ? err.message : String(err);
+            if (!/no such table/i.test(msg)) {
+                // eslint-disable-next-line no-console
+                console.warn('[ReflexionMemory] dualWriteEpisodeToSQL failed:', msg);
+            }
+        }
+    }
+    /**
+     * Rebuild the in-memory vector index from the SQLite `episodes` /
+     * `episode_embeddings` tables, going through the proper backend channels
+     * so `retrieveRelevant()` sees the data afterwards.
+     *
+     * Fixes the user's recovery use-case from issue #129: rather than calling
+     * `vectorBackend.getInner().insert()` directly (which bypasses the
+     * GuardedBackend wrapper and confuses retrieveRelevant), call this method
+     * to re-hydrate the vector and graph indices from durable storage.
+     *
+     * Returns the number of episodes re-indexed. No-ops cleanly when the SQL
+     * tables are empty or absent.
+     */
+    async rebuildIndex(options = {}) {
+        if (!this.db || typeof this.db.prepare !== 'function')
+            return 0;
+        const where = options.fromTimestamp !== undefined ? 'WHERE e.ts >= ?' : '';
+        const params = options.fromTimestamp !== undefined ? [options.fromTimestamp] : [];
+        let rows = [];
+        try {
+            const stmt = this.db.prepare(`
+        SELECT
+          e.id, e.ts, e.session_id, e.task, e.input, e.output, e.critique,
+          e.reward, e.success, e.latency_ms, e.tokens_used, e.tags, e.metadata,
+          ee.embedding
+        FROM episodes e
+        LEFT JOIN episode_embeddings ee ON ee.episode_id = e.id
+        ${where}
+        ORDER BY e.id ASC
+      `);
+            rows = stmt.all(...params);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (/no such table/i.test(msg))
+                return 0;
+            throw err;
+        }
+        let reindexed = 0;
+        for (const row of rows) {
+            const episode = {
+                id: row.id,
+                ts: row.ts,
+                sessionId: row.session_id,
+                task: row.task,
+                input: row.input ?? undefined,
+                output: row.output ?? undefined,
+                critique: row.critique ?? undefined,
+                reward: row.reward,
+                success: row.success === 1,
+                latencyMs: row.latency_ms ?? undefined,
+                tokensUsed: row.tokens_used ?? undefined,
+                tags: safeJsonParse(row.tags, undefined),
+                metadata: safeJsonParse(row.metadata, undefined),
+            };
+            // Prefer the stored embedding; fall back to recomputing if missing.
+            let embedding;
+            if (row.embedding) {
+                const buf = row.embedding;
+                embedding = new Float32Array(buf.buffer, buf.byteOffset, buf.length / 4);
+            }
+            else {
+                embedding = await this.embedder.embedPassage(this.buildEpisodeText(episode));
+            }
+            // Re-insert through the proper public APIs so the GuardedBackend
+            // wrapper, graph adapter, and HNSW all stay in sync.
+            if (this.vectorBackend) {
+                try {
+                    this.vectorBackend.insert(String(row.id), embedding, {
+                        type: 'episode',
+                        sessionId: episode.sessionId,
+                        reward: episode.reward,
+                        success: episode.success,
+                    });
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    // eslint-disable-next-line no-console
+                    console.warn(`[ReflexionMemory] rebuildIndex: vector insert failed for ${row.id}: ${msg}`);
+                }
+            }
+            if (this.graphBackend && 'storeEpisode' in this.graphBackend) {
+                const adapter = this.graphBackend;
+                try {
+                    await adapter.storeEpisode({
+                        id: `episode-${row.id}`,
+                        sessionId: episode.sessionId,
+                        task: episode.task,
+                        reward: episode.reward,
+                        success: episode.success,
+                        input: episode.input,
+                        output: episode.output,
+                        critique: episode.critique,
+                        createdAt: (episode.ts ?? Date.now() / 1000) * 1000,
+                        tokensUsed: episode.tokensUsed,
+                        latencyMs: episode.latencyMs,
+                    }, embedding);
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    // eslint-disable-next-line no-console
+                    console.warn(`[ReflexionMemory] rebuildIndex: graph store failed for ${row.id}: ${msg}`);
+                }
+            }
+            reindexed++;
+        }
+        // Bust any stale read caches so the next retrieveRelevant sees the
+        // freshly-rebuilt index.
+        this.queryCache.invalidateCategory('episodes');
+        this.queryCache.invalidateCategory('task-stats');
+        return reindexed;
+    }
 }
 //# sourceMappingURL=ReflexionMemory.js.map