agentdb 3.0.0-alpha.10 → 3.0.0-alpha.12

package/dist/src/controllers/ReflexionMemory.d.ts

@@ -7,11 +7,12 @@
  * Based on: "Reflexion: Language Agents with Verbal Reinforcement Learning"
  * https://arxiv.org/abs/2303.11366
  */
-type Database = any;
+import type { IDatabaseConnection } from '../types/database.types.js';
 import { EmbeddingService } from './EmbeddingService.js';
 import type { VectorBackend } from '../backends/VectorBackend.js';
 import type { LearningBackend } from '../backends/LearningBackend.js';
 import type { GraphBackend } from '../backends/GraphBackend.js';
+import { type QueryCacheConfig } from '../core/QueryCache.js';
 export interface Episode {
     id?: number;
     ts?: number;
@@ -46,17 +47,79 @@ export declare class ReflexionMemory {
     private vectorBackend?;
     private learningBackend?;
     private graphBackend?;
-    constructor(db: Database, embedder: EmbeddingService, vectorBackend?: VectorBackend, learningBackend?: LearningBackend, graphBackend?: GraphBackend);
+    private queryCache;
+    constructor(db: IDatabaseConnection, embedder: EmbeddingService, vectorBackend?: VectorBackend, learningBackend?: LearningBackend, graphBackend?: GraphBackend, cacheConfig?: QueryCacheConfig);
     /**
      * 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).
      */
     storeEpisode(episode: Episode): Promise<number>;
     /**
      * Retrieve relevant past episodes for a new task attempt
+     * Results are cached for improved performance
      */
     retrieveRelevant(query: ReflexionQuery): Promise<EpisodeWithEmbedding[]>;
     /**
-     * Get statistics for a task
+     * Prepare and enhance query embedding for search
+     */
+    private prepareQueryEmbedding;
+    /**
+     * Retrieve episodes using GraphDatabaseAdapter (AgentDB v2)
+     */
+    private retrieveFromGraphAdapter;
+    /**
+     * Retrieve episodes using generic GraphBackend
+     */
+    private retrieveFromGenericGraph;
+    /**
+     * Retrieve episodes using VectorBackend (150x faster)
+     */
+    private retrieveFromVectorBackend;
+    /**
+     * Retrieve episodes using SQL-based similarity search (fallback)
+     */
+    private retrieveFromSQLFallback;
+    /**
+     * Apply episode filters to search results
+     */
+    private applyEpisodeFilters;
+    /**
+     * Check if database row passes episode filters
+     */
+    private passesEpisodeFilters;
+    /**
+     * Build Cypher query with filters
+     */
+    private buildCypherQuery;
+    /**
+     * Build SQL WHERE clause and parameters for filters
+     */
+    private buildSQLFilters;
+    /**
+     * Fetch episodes by IDs from database
+     */
+    private fetchEpisodesByIds;
+    /**
+     * Convert GraphDatabaseAdapter episode to EpisodeWithEmbedding
+     */
+    private convertGraphEpisode;
+    /**
+     * Convert Cypher query result to EpisodeWithEmbedding
+     */
+    private convertCypherEpisode;
+    /**
+     * Convert database row to EpisodeWithEmbedding
+     */
+    private convertDatabaseEpisode;
+    /**
+     * Get statistics for a task (cached)
      */
     getTaskStats(task: string, timeWindowDays?: number): {
         totalAttempts: number;
@@ -66,11 +129,11 @@ export declare class ReflexionMemory {
         improvementTrend: number;
     };
     /**
-     * Build critique summary from similar failed episodes
+     * Build critique summary from similar failed episodes (cached)
      */
     getCritiqueSummary(query: ReflexionQuery): Promise<string>;
     /**
-     * Get successful strategies for a task
+     * Get successful strategies for a task (cached)
      */
     getSuccessStrategies(query: ReflexionQuery): Promise<string>;
     /**
@@ -79,6 +142,7 @@ export declare class ReflexionMemory {
     getRecentEpisodes(sessionId: string, limit?: number): Promise<Episode[]>;
     /**
      * Prune low-quality episodes based on TTL and quality threshold
+     * Invalidates cache on completion
      */
     pruneEpisodes(config: {
         minReward?: number;
@@ -89,6 +153,7 @@ export declare class ReflexionMemory {
     private storeEmbedding;
     private serializeEmbedding;
     private deserializeEmbedding;
+    private cosineSimilarity;
     /**
      * Create graph node for episode with relationships
      */
@@ -119,6 +184,50 @@ export declare class ReflexionMemory {
      * Get graph backend statistics
      */
     getGraphStats(): import("../backends/GraphBackend.js").GraphStats | null;
+    /**
+     * Get query cache statistics
+     */
+    getCacheStats(): import("../core/QueryCache.js").CacheStatistics;
+    /**
+     * Clear query cache
+     */
+    clearCache(): void;
+    /**
+     * Prune expired cache entries
+     */
+    pruneCache(): number;
+    /**
+     * Warm cache with common queries
+     */
+    warmCache(sessionId?: string): Promise<void>;
+    /**
+     * 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).
+     */
+    private dualWriteEpisodeToSQL;
+    /**
+     * 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.
+     */
+    rebuildIndex(options?: {
+        fromTimestamp?: number;
+    }): Promise<number>;
 }
-export {};
 //# sourceMappingURL=ReflexionMemory.d.ts.map

package/dist/src/controllers/ReflexionMemory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ReflexionMemory.d.ts","sourceRoot":"","sources":["../../../src/controllers/ReflexionMemory.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ReflexionMemory.d.ts","sourceRoot":"","sources":["../../../src/controllers/ReflexionMemory.ts"],"names":[],"mappings":"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"}