@cmdoss/memwal-sdk 0.6.1 → 0.7.0

package/src/vector/HnswWasmService.ts

@@ -11,6 +11,7 @@
  * - ✅ Walrus storage integration
  * - ✅ Near-native performance via WASM
  * - ✅ Safe for Node.js/SSR (uses dynamic import)
+ * - ✅ LRU cache with memory limits to prevent OOM
  */
 
 // Dynamic import for hnswlib-wasm to avoid bundling issues in Node.js
@@ -35,6 +36,7 @@ import {
   BatchStats,
   VectorError
 } from '../embedding/types';
+import { LRUCache, estimateIndexCacheSize } from '../utils/LRUCache';
 
 interface IndexCacheEntry {
   index: HierarchicalNSW;
@@ -44,6 +46,8 @@ interface IndexCacheEntry {
   version: number;
   metadata: Map<number, any>; // vectorId -> metadata
   dimensions: number;
+  /** Cached vectors for serialization - only store if needed */
+  vectors: Map<number, number[]>;
 }
 
 interface IndexMetadata {
@@ -57,24 +61,45 @@ interface IndexMetadata {
   lastUpdated: Date;
 }
 
+// Memory management constants
+const DEFAULT_MAX_CACHED_INDEXES = 5; // Max number of user indexes to keep in memory
+const DEFAULT_INDEX_TTL_MS = 10 * 60 * 1000; // 10 minutes TTL for idle indexes
+const DEFAULT_MAX_MEMORY_MB = 512; // 512MB max memory for index cache
+const DEFAULT_CLEANUP_INTERVAL_MS = 60 * 1000; // Check every 1 minute
+
 /**
  * Browser-compatible HNSW vector indexing service using WebAssembly
  * Drop-in replacement for HnswIndexService with identical API
+ *
+ * Memory Management:
+ * - LRU cache limits number of indexes in memory (default: 5)
+ * - TTL-based expiration for idle indexes (default: 10 minutes)
+ * - Optional memory limit (default: 512MB)
+ * - Automatic cleanup of expired/evicted indexes
  */
 export class HnswWasmService {
   private hnswlib: HnswlibModule | null = null;
-  private readonly indexCache = new Map<string, IndexCacheEntry>();
+  private readonly indexCache: LRUCache<IndexCacheEntry>;
   private readonly batchJobs = new Map<string, BatchJob>();
   private readonly config: Required<BatchConfig>;
   private readonly indexConfig: Required<HNSWIndexConfig>;
   private batchProcessor?: ReturnType<typeof setInterval>;
-  private cacheCleanup?: ReturnType<typeof setInterval>;
   private initPromise: Promise<void> | null = null;
 
+  // Memory management settings
+  private readonly maxCachedIndexes: number;
+  private readonly indexTtlMs: number;
+  private readonly maxMemoryBytes: number;
+
   constructor(
     private storageService: StorageService,
     indexConfig: Partial<HNSWIndexConfig> = {},
-    batchConfig: Partial<BatchConfig> = {}
+    batchConfig: Partial<BatchConfig> = {},
+    memoryConfig?: {
+      maxCachedIndexes?: number;
+      indexTtlMs?: number;
+      maxMemoryMB?: number;
+    }
   ) {
     // Default HNSW configuration (matching HnswIndexService)
     this.indexConfig = {
@@ -94,6 +119,42 @@ export class HnswWasmService {
       cacheTtlMs: batchConfig.cacheTtlMs || 30 * 60 * 1000 // 30 minutes
     };
 
+    // Memory management configuration
+    this.maxCachedIndexes = memoryConfig?.maxCachedIndexes ?? DEFAULT_MAX_CACHED_INDEXES;
+    this.indexTtlMs = memoryConfig?.indexTtlMs ?? DEFAULT_INDEX_TTL_MS;
+    this.maxMemoryBytes = (memoryConfig?.maxMemoryMB ?? DEFAULT_MAX_MEMORY_MB) * 1024 * 1024;
+
+    // Initialize LRU cache with memory limits
+    this.indexCache = new LRUCache<IndexCacheEntry>({
+      maxSize: this.maxCachedIndexes,
+      ttlMs: this.indexTtlMs,
+      cleanupIntervalMs: DEFAULT_CLEANUP_INTERVAL_MS,
+      maxMemoryBytes: this.maxMemoryBytes,
+      sizeEstimator: (entry) => estimateIndexCacheSize({
+        vectors: entry.vectors || new Map(),
+        metadata: entry.metadata,
+        pendingVectors: entry.pendingVectors,
+      }),
+      onEvict: (userAddress, entry, reason) => {
+        console.log(`🧹 [HnswWasmService] Evicting index for ${userAddress} (reason: ${reason})`);
+        // Dispose WASM resources
+        if (entry.index) {
+          try {
+            if (typeof entry.index.free === 'function') {
+              entry.index.free();
+            }
+          } catch (e) {
+            // Ignore cleanup errors
+          }
+        }
+        // Remove associated batch job
+        this.batchJobs.delete(userAddress);
+      },
+    });
+
+    console.log(`✅ HnswWasmService initialized with memory limits:`);
+    console.log(`   Max indexes: ${this.maxCachedIndexes}, TTL: ${this.indexTtlMs / 1000}s, Max memory: ${this.maxMemoryBytes / 1024 / 1024}MB`);
+
     // Initialize WASM library asynchronously
     this.initPromise = this.initialize();
   }
@@ -107,9 +168,8 @@ export class HnswWasmService {
       this.hnswlib = await loadHnswlibDynamic();
       console.log('✅ hnswlib-wasm loaded successfully');
 
-      // Start background processors
+      // Start batch processor (cache cleanup is handled by LRUCache)
       this.startBatchProcessor();
-      this.startCacheCleanup();
     } catch (error) {
       console.error('❌ Failed to load hnswlib-wasm:', error);
       throw error;
@@ -142,12 +202,13 @@ export class HnswWasmService {
 
       console.log(`🔨 Creating new HNSW index for user ${userAddress}`);
       console.log(`   Dimensions: ${config.dimension}, M: ${config.m}, efConstruction: ${config.efConstruction}`);
+      console.log(`   Cache stats: ${this.indexCache.size}/${this.maxCachedIndexes} indexes, ${(this.indexCache.memoryBytes / 1024 / 1024).toFixed(1)}MB`);
 
       // Create a new index using WASM (constructor takes: spaceName, numDimensions, autoSaveFilename)
       const index = new this.hnswlib!.HierarchicalNSW(config.spaceType, config.dimension, '');
       index.initIndex(config.maxElements, config.m, config.efConstruction, config.randomSeed);
 
-      // Create cache entry
+      // Create cache entry (LRU cache handles eviction automatically)
       this.indexCache.set(userAddress, {
         index,
         lastModified: new Date(),
@@ -155,7 +216,8 @@ export class HnswWasmService {
         isDirty: false,
         version: 1,
         metadata: new Map(),
-        dimensions: config.dimension
+        dimensions: config.dimension,
+        vectors: new Map(),
       });
 
       // Serialize the empty index
@@ -189,7 +251,7 @@ export class HnswWasmService {
       // Validate input
       this.validateVector(vector);
 
-      // Get or create cache entry
+      // Get or create cache entry (LRU cache will evict old entries if needed)
       let cacheEntry = this.indexCache.get(userAddress);
       if (!cacheEntry) {
         console.warn(`No cached index found for user ${userAddress}, will create on first flush`);
@@ -201,7 +263,8 @@ export class HnswWasmService {
           isDirty: true,
           version: 1,
           metadata: new Map(),
-          dimensions: vector.length
+          dimensions: vector.length,
+          vectors: new Map(),
         };
         this.indexCache.set(userAddress, cacheEntry);
       }
@@ -216,6 +279,8 @@ export class HnswWasmService {
       if (metadata) {
         cacheEntry.metadata.set(vectorId, metadata);
       }
+      // Also cache the vector for serialization
+      cacheEntry.vectors.set(vectorId, vector);
       cacheEntry.isDirty = true;
       cacheEntry.lastModified = new Date();
 
@@ -344,7 +409,8 @@ export class HnswWasmService {
         isDirty: false,
         version: 1,
         metadata: new Map(),
-        dimensions: this.indexConfig.dimension
+        dimensions: this.indexConfig.dimension,
+        vectors: new Map(),
       });
 
       console.log(`✅ Index loaded successfully for ${userAddress}`);
@@ -384,30 +450,29 @@ export class HnswWasmService {
   /**
    * Get cache statistics
    */
-  getCacheStats(): BatchStats {
-    const cacheEntries: any[] = [];
+  getCacheStats(): BatchStats & {
+    memoryUsageMB: number;
+    maxMemoryMB: number;
+    maxCachedIndexes: number;
+  } {
     let totalPendingVectors = 0;
 
-    for (const [userAddress, entry] of this.indexCache.entries()) {
-      const pendingCount = entry.pendingVectors.size;
-      totalPendingVectors += pendingCount;
-
-      cacheEntries.push({
-        userAddress,
-        pendingVectors: pendingCount,
-        lastModified: entry.lastModified,
-        isDirty: entry.isDirty,
-        indexDimensions: entry.dimensions
-      });
+    for (const [, entry] of this.indexCache.entries()) {
+      totalPendingVectors += entry.pendingVectors.size;
     }
 
+    const lruStats = this.indexCache.getStats();
+
     return {
       totalUsers: this.indexCache.size,
       totalPendingVectors,
       activeBatchJobs: this.batchJobs.size,
       cacheHitRate: 0, // TODO: Implement hit rate tracking
       averageBatchSize: totalPendingVectors / Math.max(1, this.indexCache.size),
-      averageProcessingTime: 0 // TODO: Implement timing tracking
+      averageProcessingTime: 0, // TODO: Implement timing tracking
+      memoryUsageMB: lruStats.memoryBytes / 1024 / 1024,
+      maxMemoryMB: this.maxMemoryBytes / 1024 / 1024,
+      maxCachedIndexes: this.maxCachedIndexes,
     };
   }
 
@@ -451,10 +516,8 @@ export class HnswWasmService {
     if (this.batchProcessor) {
       clearInterval(this.batchProcessor);
     }
-    if (this.cacheCleanup) {
-      clearInterval(this.cacheCleanup);
-    }
-    this.indexCache.clear();
+    // LRU cache cleanup is handled internally, but we should destroy it
+    this.indexCache.destroy();
     this.batchJobs.clear();
     console.log('🛑 HnswWasmService destroyed');
   }
@@ -474,7 +537,8 @@ export class HnswWasmService {
       isDirty: false,
       version: 1,
       metadata: new Map(),
-      dimensions
+      dimensions,
+      vectors: new Map(),
     };
   }
 
@@ -498,11 +562,7 @@ export class HnswWasmService {
     }, this.config.batchDelayMs);
   }
 
-  private startCacheCleanup(): void {
-    this.cacheCleanup = setInterval(() => {
-      this.cleanupCache();
-    }, 5 * 60 * 1000); // Every 5 minutes
-  }
+  // Note: Cache cleanup is now handled by LRUCache internally
 
   private async processBatchJobs(): Promise<void> {
     const now = Date.now();
@@ -644,15 +704,7 @@ export class HnswWasmService {
     return { ids: filteredIds, distances: filteredDistances };
   }
 
-  private cleanupCache(): void {
-    const now = Date.now();
-    for (const [userAddress, entry] of this.indexCache.entries()) {
-      if (now - entry.lastModified.getTime() > this.config.cacheTtlMs) {
-        console.debug(`🧹 Removing stale cache entry for user ${userAddress}`);
-        this.indexCache.delete(userAddress);
-      }
-    }
-  }
+  // Note: cleanupCache is now handled by LRUCache internally
 
   private validateVector(vector: number[]): void {
     if (!Array.isArray(vector) || vector.length === 0) {

package/src/vector/IHnswService.ts

@@ -14,7 +14,7 @@
  * Configuration for HNSW index
  */
 export interface IHnswIndexConfig {
-  /** Vector dimension (e.g., 768 for text-embedding-004) */
+  /** Vector dimension (e.g., 3072 for text-embedding-004) */
   dimension: number;
   /** Maximum number of elements in the index */
   maxElements?: number;
@@ -203,6 +203,15 @@ export interface HnswServiceConfig {
   indexDirectory?: string;
   /** Walrus backup configuration (optional) */
   walrusBackup?: WalrusBackupConfig;
+  /** Memory management configuration for LRU cache */
+  memoryConfig?: {
+    /** Maximum number of cached indexes (default: 5) */
+    maxCachedIndexes?: number;
+    /** TTL for cached indexes in ms (default: 10 minutes) */
+    indexTtlMs?: number;
+    /** Maximum memory in MB (default: 512MB) */
+    maxMemoryMB?: number;
+  };
 }
 
 // ==================== Environment Detection ====================

package/src/vector/NodeHnswService.ts

@@ -22,6 +22,12 @@ import type {
   IHnswBatchStats,
   WalrusBackupConfig
 } from './IHnswService';
+import { LRUCache, estimateIndexCacheSize } from '../utils/LRUCache';
+
+// Memory management constants
+const DEFAULT_MAX_CACHED_INDEXES = 5;
+const DEFAULT_INDEX_TTL_MS = 10 * 60 * 1000; // 10 minutes
+const DEFAULT_MAX_MEMORY_MB = 512;
 
 // Dynamic import types for hnswlib-node
 type HierarchicalNSW = any;
@@ -43,7 +49,7 @@ interface IndexCacheEntry {
  */
 export class NodeHnswService implements IHnswService {
   private hnswlib: any = null;
-  private readonly indexCache = new Map<string, IndexCacheEntry>();
+  private readonly indexCache: LRUCache<IndexCacheEntry>;
   private readonly indexConfig: Required<IHnswIndexConfig>;
   private readonly indexDirectory: string;
   private readonly walrusConfig?: WalrusBackupConfig;
@@ -52,6 +58,11 @@ export class NodeHnswService implements IHnswService {
   private _isInitialized = false;
   private walrusClient: ReturnType<typeof this.createWalrusClient> | null = null;
 
+  // Memory management config
+  private readonly maxCachedIndexes: number;
+  private readonly indexTtlMs: number;
+  private readonly maxMemoryMB: number;
+
   /**
    * Create Walrus client using @mysten/walrus SDK
    */
@@ -83,12 +94,86 @@ export class NodeHnswService implements IHnswService {
     this.indexDirectory = config.indexDirectory || './.pdw-indexes';
     this.walrusConfig = config.walrusBackup;
 
+    // Memory management configuration
+    this.maxCachedIndexes = config.memoryConfig?.maxCachedIndexes || DEFAULT_MAX_CACHED_INDEXES;
+    this.indexTtlMs = config.memoryConfig?.indexTtlMs || DEFAULT_INDEX_TTL_MS;
+    this.maxMemoryMB = config.memoryConfig?.maxMemoryMB || DEFAULT_MAX_MEMORY_MB;
+
+    // Initialize LRU cache with eviction callback
+    this.indexCache = new LRUCache<IndexCacheEntry>({
+      maxSize: this.maxCachedIndexes,
+      ttlMs: this.indexTtlMs,
+      maxMemoryBytes: this.maxMemoryMB * 1024 * 1024,
+      sizeEstimator: (entry) => estimateIndexCacheSize({
+        vectors: new Map(), // Vectors are stored in the native index, not JS
+        metadata: entry.metadata,
+        pendingVectors: entry.pendingVectors
+      }),
+      onEvict: (userAddress, entry, reason) => {
+        console.log(`[NodeHnswService] Evicting index for ${userAddress.slice(0, 10)}... (reason: ${reason})`);
+        // Save dirty index before eviction
+        if (entry.isDirty) {
+          this.saveIndexSync(userAddress, entry).catch(err => {
+            console.error(`[NodeHnswService] Failed to save evicted index: ${err}`);
+          });
+        }
+      }
+    });
+
+    console.log(`[NodeHnswService] Initialized with LRU cache: maxIndexes=${this.maxCachedIndexes}, ttl=${this.indexTtlMs}ms, maxMemory=${this.maxMemoryMB}MB`);
+
     // Initialize Walrus SDK client for cloud backup
     if (this.walrusConfig?.enabled) {
       this.walrusClient = this.createWalrusClient('testnet');
     }
   }
 
+  /**
+   * Save index synchronously (for eviction callback)
+   */
+  private async saveIndexSync(userAddress: string, entry: IndexCacheEntry): Promise<void> {
+    try {
+      const indexPath = this.getIndexPath(userAddress);
+      entry.index.writeIndex(indexPath);
+
+      const fs = await import('fs/promises');
+      const metadataPath = indexPath + '.meta.json';
+      const metadataObj: Record<number, any> = {};
+      for (const [k, v] of entry.metadata) {
+        metadataObj[k] = v;
+      }
+
+      await fs.writeFile(metadataPath, JSON.stringify({
+        version: entry.version,
+        dimensions: entry.dimensions,
+        metadata: metadataObj,
+        walrusBlobId: entry.walrusBlobId,
+      }));
+
+      console.log(`[NodeHnswService] Saved evicted index for ${userAddress.slice(0, 10)}...`);
+    } catch (error) {
+      console.error(`[NodeHnswService] Error saving evicted index:`, error);
+    }
+  }
+
+  /**
+   * Get cache statistics for monitoring
+   */
+  getCacheStats(): {
+    totalUsers: number;
+    maxCachedIndexes: number;
+    memoryUsageMB: number;
+    maxMemoryMB: number;
+  } {
+    const stats = this.indexCache.getStats();
+    return {
+      totalUsers: stats.size,
+      maxCachedIndexes: this.maxCachedIndexes,
+      memoryUsageMB: stats.memoryBytes / (1024 * 1024),
+      maxMemoryMB: this.maxMemoryMB,
+    };
+  }
+
   /**
    * Initialize hnswlib-node (dynamic import)
    */
@@ -145,7 +230,7 @@ export class NodeHnswService implements IHnswService {
   }
 
   private async processPendingBatches(): Promise<void> {
-    for (const [userAddress, entry] of this.indexCache) {
+    for (const [userAddress, entry] of this.indexCache.entries()) {
       if (entry.isDirty && entry.pendingVectors.size > 0) {
         try {
           await this.flushBatch(userAddress);
@@ -248,6 +333,7 @@ export class NodeHnswService implements IHnswService {
     vector: number[],
     metadata?: Record<string, any>
   ): Promise<void> {
+    console.log(`[NodeHnswService] addVector: userAddress=${userAddress.slice(0, 10)}..., vectorId=${vectorId}, dims=${vector.length}`);
     await this.getOrCreateIndex(userAddress);
 
     const entry = this.indexCache.get(userAddress);
@@ -262,9 +348,11 @@ export class NodeHnswService implements IHnswService {
     }
     entry.isDirty = true;
     this.batchStats.pendingJobs++;
+    console.log(`[NodeHnswService] addVector: Added to pending batch. Pending: ${entry.pendingVectors.size}, isDirty: ${entry.isDirty}`);
 
     // Flush if batch is large enough
     if (entry.pendingVectors.size >= 50) {
+      console.log(`[NodeHnswService] addVector: Batch size >= 50, auto-flushing...`);
       await this.flushBatch(userAddress);
     }
   }
@@ -338,8 +426,24 @@ export class NodeHnswService implements IHnswService {
 
   async flushBatch(userAddress: string): Promise<void> {
     const entry = this.indexCache.get(userAddress);
-    if (!entry || entry.pendingVectors.size === 0) return;
+    if (!entry) {
+      console.log(`[NodeHnswService] flushBatch: No cache entry for ${userAddress.slice(0, 10)}..., skipping`);
+      return;
+    }
 
+    // Even if no pending vectors, we may need to save metadata that was added
+    if (entry.pendingVectors.size === 0) {
+      // Still save index to persist any metadata that was added
+      if (entry.isDirty || entry.metadata.size > 0) {
+        console.log(`[NodeHnswService] flushBatch: No pending vectors but isDirty=${entry.isDirty}, metadata.size=${entry.metadata.size}, saving index...`);
+        await this.saveIndex(userAddress);
+      } else {
+        console.log(`[NodeHnswService] flushBatch: No pending vectors and nothing to save for ${userAddress.slice(0, 10)}...`);
+      }
+      return;
+    }
+
+    console.log(`[NodeHnswService] flushBatch: Flushing ${entry.pendingVectors.size} vectors for ${userAddress.slice(0, 10)}...`);
     const startTime = Date.now();
     let processed = 0;
 
@@ -348,6 +452,7 @@ export class NodeHnswService implements IHnswService {
         entry.index.addPoint(vector, vectorId);
         processed++;
       }
+      console.log(`[NodeHnswService] flushBatch: Added ${processed} points to index`);
 
       entry.pendingVectors.clear();
       entry.isDirty = true;
@@ -361,21 +466,28 @@ export class NodeHnswService implements IHnswService {
         (this.batchStats.averageProcessingTime + processingTime) / 2;
 
       // Auto-save
+      console.log(`[NodeHnswService] flushBatch: Calling saveIndex()...`);
       await this.saveIndex(userAddress);
+      console.log(`[NodeHnswService] flushBatch: Complete in ${processingTime}ms`);
     } catch (error) {
       this.batchStats.failedJobs++;
-      console.error('[NodeHnswService] Flush batch error:', error);
+      console.error('[NodeHnswService] flushBatch error:', error);
       throw error;
     }
   }
 
   async saveIndex(userAddress: string): Promise<void> {
     const entry = this.indexCache.get(userAddress);
-    if (!entry) return;
+    if (!entry) {
+      console.log(`[NodeHnswService] saveIndex: No cache entry for ${userAddress}, skipping`);
+      return;
+    }
 
     try {
       const indexPath = this.getIndexPath(userAddress);
+      console.log(`[NodeHnswService] saveIndex: Writing to ${indexPath}`);
       entry.index.writeIndex(indexPath);
+      console.log(`[NodeHnswService] saveIndex: writeIndex() complete`);
 
       // Save metadata separately
       const fs = await import('fs/promises');
@@ -385,19 +497,26 @@ export class NodeHnswService implements IHnswService {
         metadataObj[k] = v;
       }
 
-      // Preserve existing walrus blob ID if present
-      const existingMeta: Record<string, any> = {};
+      // Preserve existing metadata and merge with in-memory metadata
+      // This prevents data loss when cache is cleared between requests
+      let existingMeta: Record<string, any> = {};
       try {
         const existingContent = await fs.readFile(metadataPath, 'utf-8');
-        Object.assign(existingMeta, JSON.parse(existingContent));
+        existingMeta = JSON.parse(existingContent);
       } catch {
         // No existing metadata file
       }
 
+      // Merge: existing metadata + in-memory metadata (in-memory takes priority for same keys)
+      const mergedMetadata = {
+        ...(existingMeta.metadata || {}),
+        ...metadataObj
+      };
+
       await fs.writeFile(metadataPath, JSON.stringify({
         version: entry.version,
         dimensions: entry.dimensions,
-        metadata: metadataObj,
+        metadata: mergedMetadata,
         walrusBlobId: existingMeta.walrusBlobId,
         walrusSyncTime: existingMeta.walrusSyncTime
       }));
@@ -706,7 +825,8 @@ export class NodeHnswService implements IHnswService {
       this.batchProcessor = undefined;
     }
 
-    this.indexCache.clear();
+    // Destroy LRU cache (triggers cleanup and stops internal timers)
+    this.indexCache.destroy();
     this._isInitialized = false;
     console.log('[NodeHnswService] Service destroyed');
   }

package/src/vector/createHnswService.ts

@@ -30,7 +30,7 @@ let instanceCount = 0;
  * @example
  * ```typescript
  * const hnswService = await createHnswService({
- *   indexConfig: { dimension: 768 }
+ *   indexConfig: { dimension: 3072 }
  * });
  *
  * await hnswService.addVector(userAddress, vectorId, embedding);

package/src/vector/index.ts

@@ -8,7 +8,7 @@
  * ```typescript
  * // Auto-detect environment and create appropriate service
  * import { createHnswService } from 'personal-data-wallet-sdk/vector';
- * const service = await createHnswService({ indexConfig: { dimension: 768 } });
+ * const service = await createHnswService({ indexConfig: { dimension: 3072 } });
  * ```
  */