@cmdoss/memwal-sdk 0.6.2 → 0.7.0

package/src/retrieval/MemoryRetrievalService.ts

@@ -182,10 +182,15 @@ export class MemoryRetrievalService {
   private contentCache = new Map<string, { content: string; metadata: any; timestamp: number }>();
   private analyticsCache = new Map<string, { analytics: any; timestamp: number }>();
   
-  // Cache TTL settings
-  private readonly QUERY_CACHE_TTL = 5 * 60 * 1000; // 5 minutes
-  private readonly CONTENT_CACHE_TTL = 30 * 60 * 1000; // 30 minutes
-  private readonly ANALYTICS_CACHE_TTL = 60 * 60 * 1000; // 1 hour
+  // Cache TTL settings (configurable)
+  private readonly QUERY_CACHE_TTL: number;
+  private readonly CONTENT_CACHE_TTL: number;
+  private readonly ANALYTICS_CACHE_TTL: number;
+
+  // Cache size limits to prevent memory leaks (configurable)
+  private readonly MAX_QUERY_CACHE_SIZE: number;
+  private readonly MAX_CONTENT_CACHE_SIZE: number;
+  private readonly MAX_ANALYTICS_CACHE_SIZE: number;
 
   constructor(config?: {
     embeddingService?: EmbeddingService;
@@ -196,7 +201,29 @@ export class MemoryRetrievalService {
     encryptionService?: EncryptionService;
     batchManager?: BatchManager;
     decryptionConfig?: DecryptionConfig;
+    /** Cache configuration for memory management */
+    cacheConfig?: {
+      /** Query cache TTL in ms (default: 5 minutes) */
+      queryCacheTtlMs?: number;
+      /** Content cache TTL in ms (default: 30 minutes) */
+      contentCacheTtlMs?: number;
+      /** Analytics cache TTL in ms (default: 1 hour) */
+      analyticsCacheTtlMs?: number;
+      /** Max query cache entries (default: 100) */
+      maxQueryCacheSize?: number;
+      /** Max content cache entries (default: 50) */
+      maxContentCacheSize?: number;
+      /** Max analytics cache entries (default: 100) */
+      maxAnalyticsCacheSize?: number;
+    };
   }) {
+    // Initialize cache settings with configurable defaults
+    this.QUERY_CACHE_TTL = config?.cacheConfig?.queryCacheTtlMs ?? 5 * 60 * 1000; // 5 minutes
+    this.CONTENT_CACHE_TTL = config?.cacheConfig?.contentCacheTtlMs ?? 30 * 60 * 1000; // 30 minutes
+    this.ANALYTICS_CACHE_TTL = config?.cacheConfig?.analyticsCacheTtlMs ?? 60 * 60 * 1000; // 1 hour
+    this.MAX_QUERY_CACHE_SIZE = config?.cacheConfig?.maxQueryCacheSize ?? 100;
+    this.MAX_CONTENT_CACHE_SIZE = config?.cacheConfig?.maxContentCacheSize ?? 50; // Content can be large
+    this.MAX_ANALYTICS_CACHE_SIZE = config?.cacheConfig?.maxAnalyticsCacheSize ?? 100;
     // Initialize services (can be injected or created with default configs)
     this.embeddingService = config?.embeddingService ?? new EmbeddingService();
     this.storageManager = config?.storageManager ?? new StorageManager();
@@ -684,9 +711,56 @@ export class MemoryRetrievalService {
   }
 
   private cacheQuery(key: string, result: RetrievalContext): void {
+    this.enforceCacheLimit(this.queryCache, this.MAX_QUERY_CACHE_SIZE, this.QUERY_CACHE_TTL);
     this.queryCache.set(key, { result, timestamp: Date.now() });
   }
 
+  /**
+   * Cache content with size limit enforcement
+   */
+  private cacheContent(key: string, content: string, metadata: any): void {
+    this.enforceCacheLimit(this.contentCache, this.MAX_CONTENT_CACHE_SIZE, this.CONTENT_CACHE_TTL);
+    this.contentCache.set(key, { content, metadata, timestamp: Date.now() });
+  }
+
+  /**
+   * Cache analytics with size limit enforcement
+   */
+  private cacheAnalytics(key: string, analytics: any): void {
+    this.enforceCacheLimit(this.analyticsCache, this.MAX_ANALYTICS_CACHE_SIZE, this.ANALYTICS_CACHE_TTL);
+    this.analyticsCache.set(key, { analytics, timestamp: Date.now() });
+  }
+
+  /**
+   * Enforce cache size limit using LRU eviction (oldest entries first)
+   * Also removes expired entries based on TTL
+   */
+  private enforceCacheLimit<T extends { timestamp: number }>(
+    cache: Map<string, T>,
+    maxSize: number,
+    ttl: number
+  ): void {
+    // First, clean up expired entries
+    const now = Date.now();
+
+    for (const [key, value] of cache.entries()) {
+      if (now - value.timestamp > ttl) {
+        cache.delete(key);
+      }
+    }
+
+    // If still over limit, remove oldest entries (LRU)
+    if (cache.size >= maxSize) {
+      const entries = Array.from(cache.entries())
+        .sort((a, b) => a[1].timestamp - b[1].timestamp);
+
+      const toRemove = cache.size - maxSize + 1; // +1 to make room for new entry
+      for (let i = 0; i < toRemove && i < entries.length; i++) {
+        cache.delete(entries[i][0]);
+      }
+    }
+  }
+
   // ==================== UTILITY METHODS ====================
 
   private calculateCacheHitRate(): number {

package/src/services/EmbeddingService.ts

@@ -83,7 +83,7 @@ export interface EmbeddingConfig {
 
   /**
    * Embedding dimensions (optional, provider-dependent)
-   * - Google: Up to 768
+   * - Google: Up to 3072
    * - OpenAI: 256, 512, 1024, 1536, 3072 (depending on model)
    * - OpenRouter: Depends on the underlying model
    * - Cohere: Model-specific
@@ -704,3 +704,68 @@ export class EmbeddingService {
 }
 
 export default EmbeddingService;
+
+// ==================== Singleton Pattern ====================
+
+/**
+ * Generate config key for singleton cache
+ */
+function getConfigKey(config: EmbeddingConfig): string {
+  const provider = config.provider || 'google';
+  const modelName = typeof config.model === 'string'
+    ? config.model
+    : (config.modelName || 'default');
+  const dimensions = config.dimensions || 'default';
+  return `${provider}:${modelName}:${dimensions}`;
+}
+
+/** Singleton cache */
+const sharedInstances = new Map<string, EmbeddingService>();
+
+/**
+ * Get or create a shared EmbeddingService instance (Singleton)
+ *
+ * All clients with same provider/model/dimensions share one instance.
+ * Reduces memory usage and connection overhead.
+ *
+ * @example
+ * ```typescript
+ * // Instead of: new EmbeddingService({ apiKey, modelName })
+ * const embedding = getSharedEmbeddingService({ apiKey, modelName });
+ * ```
+ */
+export function getSharedEmbeddingService(config: EmbeddingConfig): EmbeddingService {
+  const key = getConfigKey(config);
+
+  let instance = sharedInstances.get(key);
+  if (!instance) {
+    console.log(`🔧 [Singleton] Creating shared EmbeddingService: ${key}`);
+    instance = new EmbeddingService(config);
+    sharedInstances.set(key, instance);
+  }
+
+  return instance;
+}
+
+/**
+ * Clear all shared instances (for testing)
+ */
+export function clearSharedEmbeddingServices(): void {
+  sharedInstances.clear();
+}
+
+/**
+ * Get singleton stats
+ */
+export function getSharedEmbeddingStats(): {
+  instanceCount: number;
+  instances: Array<{ key: string; stats: ReturnType<EmbeddingService['getStats']> }>;
+} {
+  return {
+    instanceCount: sharedInstances.size,
+    instances: Array.from(sharedInstances.entries()).map(([key, svc]) => ({
+      key,
+      stats: svc.getStats(),
+    })),
+  };
+}

package/src/services/IndexManager.ts

@@ -108,6 +108,10 @@ export interface IndexManagerOptions {
  * 2. If failed, rebuild from blockchain + Walrus (slow but complete)
  * 3. Sync any new memories since last save
  * 4. Auto-save periodically
+ *
+ * Memory Optimization:
+ * - Removed duplicate vectorCache - now uses VectorService.getAllCachedVectors()
+ * - Vectors are only stored once in VectorService's HnswWasmService LRU cache
  */
 export class IndexManager {
   private vectorService: VectorService;
@@ -120,7 +124,7 @@ export class IndexManager {
   };
   private autoSaveTimer?: ReturnType<typeof setInterval>;
   private indexStates: Map<string, IndexState> = new Map();
-  private vectorCache: Map<string, Map<number, number[]>> = new Map();
+  // Note: vectorCache removed - now using VectorService.getAllCachedVectors() to avoid duplication
 
   // Storage adapter (can be replaced for non-browser environments)
   private storage: {
@@ -417,16 +421,11 @@ export class IndexManager {
       efConstruction: pkg.hnswConfig.efConstruction,
     });
 
-    // Initialize vector cache for this space
-    const vectorMap = new Map<number, number[]>();
-    this.vectorCache.set(spaceId, vectorMap);
-
-    // Restore vectors and metadata
+    // Restore vectors and metadata (VectorService caches vectors internally)
     const metadataMap = new Map<number, any>(pkg.metadata);
 
     for (const { vectorId, vector } of pkg.vectors) {
       await this.vectorService.addVector(spaceId, vectorId, vector, metadataMap.get(vectorId));
-      vectorMap.set(vectorId, vector);
     }
 
     // Update index state
@@ -482,11 +481,7 @@ export class IndexManager {
       efConstruction: 200,
     });
 
-    // Initialize vector cache
-    const vectorMap = new Map<number, number[]>();
-    this.vectorCache.set(spaceId, vectorMap);
-
-    // Process each memory
+    // Process each memory (VectorService caches vectors internally)
     let processed = 0;
     const batchSize = 10;
 
@@ -514,7 +509,7 @@ export class IndexManager {
 
             const vectorId = memory.vectorId ?? Date.now() % 4294967295;
 
-            // Add to index
+            // Add to index (VectorService caches vector internally)
             await this.vectorService.addVector(spaceId, vectorId, embedding, {
               blobId: memory.blobId,
               memoryId: memory.id,
@@ -524,9 +519,6 @@ export class IndexManager {
               timestamp: memory.createdAt || Date.now(),
             });
 
-            // Cache vector for serialization
-            vectorMap.set(vectorId, embedding);
-
             processed++;
           } catch (error) {
             console.warn(`Failed to rebuild memory ${memory.id}:`, error);
@@ -579,13 +571,6 @@ export class IndexManager {
 
     console.log(`🔄 Syncing ${newMemories.length} new memories...`);
 
-    // Get or create vector cache
-    let vectorMap = this.vectorCache.get(spaceId);
-    if (!vectorMap) {
-      vectorMap = new Map();
-      this.vectorCache.set(spaceId, vectorMap);
-    }
-
     let synced = 0;
 
     for (const memory of newMemories) {
@@ -601,6 +586,7 @@ export class IndexManager {
 
         const vectorId = memory.vectorId ?? Date.now() % 4294967295;
 
+        // Add to index (VectorService caches vector internally)
         await this.vectorService.addVector(spaceId, vectorId, embedding, {
           blobId: memory.blobId,
           memoryId: memory.id,
@@ -610,7 +596,6 @@ export class IndexManager {
           timestamp: memory.createdAt || Date.now(),
         });
 
-        vectorMap.set(vectorId, embedding);
         synced++;
       } catch (error) {
         console.warn(`Failed to sync memory ${memory.id}:`, error);
@@ -633,11 +618,8 @@ export class IndexManager {
     // Get all vectors and metadata
     const allVectors = this.vectorService.getAllVectors(spaceId);
 
-    // Try to get vectors from VectorService cache first, then fallback to local cache
-    let vectorMap = this.vectorService.getAllCachedVectors(spaceId);
-    if (vectorMap.size === 0) {
-      vectorMap = this.vectorCache.get(spaceId) || new Map();
-    }
+    // Get vectors from VectorService cache (single source of truth)
+    const vectorMap = this.vectorService.getAllCachedVectors(spaceId);
 
     if (vectorMap.size === 0) {
       console.warn('Vector cache is empty, cannot save index');
@@ -727,11 +709,8 @@ export class IndexManager {
 
     const allVectors = this.vectorService.getAllVectors(spaceId);
 
-    // Try to get vectors from VectorService cache first, then fallback to local cache
-    let vectorMap = this.vectorService.getAllCachedVectors(spaceId);
-    if (vectorMap.size === 0) {
-      vectorMap = this.vectorCache.get(spaceId) || new Map();
-    }
+    // Get vectors from VectorService cache (single source of truth)
+    const vectorMap = this.vectorService.getAllCachedVectors(spaceId);
 
     if (vectorMap.size === 0) {
       console.warn('Vector cache is empty, cannot save index');
@@ -855,6 +834,7 @@ export class IndexManager {
 
   /**
    * Add vector and cache it for serialization
+   * Note: VectorService now handles caching internally, this method is kept for API compatibility
    */
   async addVectorWithCache(
     spaceId: string,
@@ -862,15 +842,8 @@ export class IndexManager {
     vector: number[],
     metadata?: any
   ): Promise<void> {
+    // VectorService.addVector now caches vectors internally
     await this.vectorService.addVector(spaceId, vectorId, vector, metadata);
-
-    // Cache vector for later serialization
-    let vectorMap = this.vectorCache.get(spaceId);
-    if (!vectorMap) {
-      vectorMap = new Map();
-      this.vectorCache.set(spaceId, vectorMap);
-    }
-    vectorMap.set(vectorId, vector);
   }
 
   /**
@@ -940,7 +913,7 @@ export class IndexManager {
     const key = `${this.options.storageKeyPrefix}${spaceId}`;
     this.storage.removeItem(key);
     this.indexStates.delete(spaceId);
-    this.vectorCache.delete(spaceId);
+    // Note: VectorService cache is managed by HnswWasmService LRU cache
     console.log(`Cleared index state for ${spaceId}`);
   }
 
@@ -988,7 +961,7 @@ export class IndexManager {
   } {
     return {
       indexState: this.getIndexState(spaceId),
-      vectorCacheSize: this.vectorCache.get(spaceId)?.size || 0,
+      vectorCacheSize: this.vectorService.getAllCachedVectors(spaceId).size,
       isAutoSaveEnabled: !!this.autoSaveTimer,
     };
   }
@@ -999,6 +972,6 @@ export class IndexManager {
   async cleanup(): Promise<void> {
     this.stopAutoSave();
     this.indexStates.clear();
-    this.vectorCache.clear();
+    // Note: VectorService cleanup is handled by its own cleanup() method
   }
 }

package/src/services/QueryService.ts

@@ -136,7 +136,7 @@ export class QueryService {
       console.log(`     Model: ${stats.model}, Dimensions: ${stats.dimensions}`);
     }
     console.log(`   Storage: ${!!storageService ? 'available' : 'not available'}`);
-    console.log(`   Knowledge Graph: ${!!graphService ? 'available' : 'not available'}`);
+    console.log(`   Knowledge Graph: ${!!graphService ? 'available' : 'pending initialization...'}`);
   }
 
   /**

package/src/services/StorageService.ts

@@ -916,6 +916,21 @@ export class StorageService {
     return this.quiltBatch.listQuiltPatches(quiltId);
   }
 
+  /**
+   * Get all memory packages from a Quilt as JSON
+   * Used for indexing Quilt memories into local HNSW index
+   */
+  async getAllMemoryPackages(quiltId: string) {
+    return this.quiltBatch.getAllMemoryPackages(quiltId);
+  }
+
+  /**
+   * Get the QuiltBatchManager instance for advanced operations
+   */
+  get quiltBatchManager(): QuiltBatchManager {
+    return this.quiltBatch;
+  }
+
   // ==================== BLOB ATTRIBUTES (Delegate to BlobAttributesManager) ====================
 
   /**