@cmdoss/memwal-sdk 0.6.0

package/dist/vector/BrowserHnswIndexService.d.ts

@@ -0,0 +1,93 @@
+/**
+ * BrowserHnswIndexService - Client-Side HNSW Vector Indexing
+ *
+ * Browser-compatible HNSW vector indexing with IndexedDB persistence.
+ * Uses hnswlib-wasm for WASM-based vector search (10-50x faster than pure JS).
+ *
+ * Features:
+ * - WASM-powered HNSW algorithm for fast vector search
+ * - IndexedDB persistence (survives page refresh)
+ * - Intelligent batching and caching
+ * - Metadata filtering support
+ * - Zero backend dependencies
+ */
+import type { HNSWIndexConfig, HNSWSearchResult, HNSWSearchOptions, BatchConfig, BatchStats } from '../embedding/types';
+/**
+ * Browser-compatible HNSW vector indexing service with IndexedDB persistence
+ */
+export declare class BrowserHnswIndexService {
+    private readonly indexCache;
+    private readonly batchJobs;
+    private readonly config;
+    private readonly indexConfig;
+    private batchProcessor?;
+    private cacheCleanup?;
+    private db?;
+    private hnswLib?;
+    private readonly debug;
+    constructor(indexConfig?: Partial<HNSWIndexConfig>, batchConfig?: Partial<BatchConfig>);
+    /**
+     * Debug logging helper
+     */
+    private debugLog;
+    /**
+     * Initialize IndexedDB for persistence
+     */
+    private initializeIndexedDB;
+    /**
+     * Load hnswlib-wasm dynamically (only when needed)
+     * CRITICAL: Must await WASM initialization before using HierarchicalNSW constructor
+     */
+    private loadHnswLib;
+    /**
+     * Create a new HNSW index
+     */
+    createIndex(userAddress: string, options?: Partial<HNSWIndexConfig>): Promise<{
+        index: any;
+        serialized: ArrayBuffer;
+    }>;
+    /**
+     * Add vector to index with batching (main entry point)
+     */
+    addVectorToIndexBatched(userAddress: string, vectorId: number, vector: number[], metadata?: any): void;
+    /**
+     * Search vectors in the index (including pending vectors)
+     */
+    searchVectors(userAddress: string, queryVector: number[], options?: HNSWSearchOptions): Promise<HNSWSearchResult>;
+    /**
+     * Load index from IndexedDB via Emscripten FS
+     */
+    loadIndexFromDB(userAddress: string): Promise<boolean>;
+    /**
+     * Save index to IndexedDB via Emscripten FS
+     */
+    saveIndexToDB(userAddress: string): Promise<void>;
+    /**
+     * Force flush all pending vectors for a user
+     */
+    forceFlush(userAddress: string): Promise<void>;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): BatchStats;
+    /**
+     * Clear user index and cache
+     */
+    clearUserIndex(userAddress: string): void;
+    /**
+     * Cleanup resources
+     */
+    destroy(): void;
+    private scheduleBatchJob;
+    private startBatchProcessor;
+    private startCacheCleanup;
+    private processBatchJobs;
+    private flushPendingVectors;
+    private cloneIndexWithPending;
+    private applyMetadataFilter;
+    private cleanupCache;
+    private validateVector;
+    private createVectorError;
+}
+export default BrowserHnswIndexService;
+//# sourceMappingURL=BrowserHnswIndexService.d.ts.map

package/dist/vector/BrowserHnswIndexService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrowserHnswIndexService.d.ts","sourceRoot":"","sources":["../../src/vector/BrowserHnswIndexService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,EACX,UAAU,EAEX,MAAM,oBAAoB,CAAC;AAkC5B;;GAEG;AACH,qBAAa,uBAAuB;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsC;IACjE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0B;IACpD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwB;IAC/C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA4B;IACxD,OAAO,CAAC,cAAc,CAAC,CAAS;IAChC,OAAO,CAAC,YAAY,CAAC,CAAS;IAC9B,OAAO,CAAC,EAAE,CAAC,CAAc;IACzB,OAAO,CAAC,OAAO,CAAC,CAAM;IAGtB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAwE;gBAG5F,WAAW,GAAE,OAAO,CAAC,eAAe,CAAM,EAC1C,WAAW,GAAE,OAAO,CAAC,WAAW,CAAM;IAyBxC;;OAEG;IACH,OAAO,CAAC,QAAQ;IAMhB;;OAEG;YACW,mBAAmB;IAuCjC;;;OAGG;YACW,WAAW;IA0BzB;;OAEG;IACG,WAAW,CACf,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,OAAO,CAAC,eAAe,CAAM,GACrC,OAAO,CAAC;QAAE,KAAK,EAAE,GAAG,CAAC;QAAC,UAAU,EAAE,WAAW,CAAA;KAAE,CAAC;IAyCnD;;OAEG;IACH,uBAAuB,CACrB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EAAE,EAChB,QAAQ,CAAC,EAAE,GAAG,GACb,IAAI;IA4CP;;OAEG;IACG,aAAa,CACjB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EAAE,EACrB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,gBAAgB,CAAC;IA8G5B;;OAEG;IACG,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAqE5D;;OAEG;IACG,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkDvD;;OAEG;IACG,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpD;;OAEG;IACH,aAAa,IAAI,UAAU;IA2B3B;;OAEG;IACH,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAMzC;;OAEG;IACH,OAAO,IAAI,IAAI;IAiBf,OAAO,CAAC,gBAAgB;IAcxB,OAAO,CAAC,mBAAmB;IAM3B,OAAO,CAAC,iBAAiB;YAMX,gBAAgB;YAuBhB,mBAAmB;YAuCnB,qBAAqB;IA6BnC,OAAO,CAAC,mBAAmB;IAsB3B,OAAO,CAAC,YAAY;IAUpB,OAAO,CAAC,cAAc;IActB,OAAO,CAAC,iBAAiB;CAM1B;AAED,eAAe,uBAAuB,CAAC"}

package/dist/vector/BrowserHnswIndexService.js

@@ -0,0 +1,581 @@
+/**
+ * BrowserHnswIndexService - Client-Side HNSW Vector Indexing
+ *
+ * Browser-compatible HNSW vector indexing with IndexedDB persistence.
+ * Uses hnswlib-wasm for WASM-based vector search (10-50x faster than pure JS).
+ *
+ * Features:
+ * - WASM-powered HNSW algorithm for fast vector search
+ * - IndexedDB persistence (survives page refresh)
+ * - Intelligent batching and caching
+ * - Metadata filtering support
+ * - Zero backend dependencies
+ */
+/**
+ * Browser-compatible HNSW vector indexing service with IndexedDB persistence
+ */
+export class BrowserHnswIndexService {
+    constructor(indexConfig = {}, batchConfig = {}) {
+        this.indexCache = new Map();
+        this.batchJobs = new Map();
+        // Debug mode - enable with DEBUG_HNSW=true in environment
+        this.debug = typeof process !== 'undefined' && process.env?.DEBUG_HNSW === 'true';
+        // Default HNSW configuration
+        this.indexConfig = {
+            dimension: indexConfig.dimension || 3072,
+            maxElements: indexConfig.maxElements || 10000,
+            efConstruction: indexConfig.efConstruction || 200,
+            m: indexConfig.m || 16,
+            randomSeed: indexConfig.randomSeed || 42,
+            spaceType: indexConfig.spaceType || 'cosine'
+        };
+        // Default batch configuration
+        this.config = {
+            maxBatchSize: batchConfig.maxBatchSize || 50,
+            batchDelayMs: batchConfig.batchDelayMs || 5000,
+            maxCacheSize: batchConfig.maxCacheSize || 100,
+            cacheTtlMs: batchConfig.cacheTtlMs || 30 * 60 * 1000 // 30 minutes
+        };
+        this.initializeIndexedDB();
+        this.startBatchProcessor();
+        this.startCacheCleanup();
+    }
+    /**
+     * Debug logging helper
+     */
+    debugLog(message, ...args) {
+        if (this.debug) {
+            console.log(`[HNSW DEBUG] ${message}`, ...args);
+        }
+    }
+    /**
+     * Initialize IndexedDB for persistence
+     */
+    async initializeIndexedDB() {
+        this.debugLog('Initializing IndexedDB...');
+        return new Promise((resolve, reject) => {
+            const request = indexedDB.open('HnswIndexDB', 1);
+            request.onerror = () => {
+                console.error('❌ Failed to open IndexedDB');
+                reject(new Error('Failed to open IndexedDB'));
+            };
+            request.onsuccess = () => {
+                this.db = request.result;
+                console.log('✅ IndexedDB initialized for HNSW indices');
+                this.debugLog('IndexedDB instance:', this.db);
+                resolve();
+            };
+            request.onupgradeneeded = (event) => {
+                const db = event.target.result;
+                this.debugLog('IndexedDB upgrade needed, creating object stores');
+                // Indices store
+                if (!db.objectStoreNames.contains('indices')) {
+                    const indicesStore = db.createObjectStore('indices', { keyPath: 'userAddress' });
+                    indicesStore.createIndex('lastUpdated', 'lastUpdated', { unique: false });
+                    this.debugLog('Created "indices" object store');
+                }
+                // Vectors store
+                if (!db.objectStoreNames.contains('vectors')) {
+                    const vectorsStore = db.createObjectStore('vectors', { keyPath: ['userAddress', 'vectorId'] });
+                    vectorsStore.createIndex('userAddress', 'userAddress', { unique: false });
+                    vectorsStore.createIndex('timestamp', 'timestamp', { unique: false });
+                    this.debugLog('Created "vectors" object store');
+                }
+            };
+        });
+    }
+    /**
+     * Load hnswlib-wasm dynamically (only when needed)
+     * CRITICAL: Must await WASM initialization before using HierarchicalNSW constructor
+     */
+    async loadHnswLib() {
+        if (this.hnswLib) {
+            this.debugLog('hnswlib-wasm already loaded, returning cached instance');
+            return this.hnswLib;
+        }
+        try {
+            this.debugLog('Loading hnswlib-wasm...');
+            // Dynamic import for hnswlib-wasm
+            const { loadHnswlib } = await import('hnswlib-wasm');
+            this.debugLog('hnswlib-wasm module imported, initializing WASM...');
+            // CRITICAL: Wait for WASM module initialization
+            // Without this, HierarchicalNSW constructor will not be available
+            this.hnswLib = await loadHnswlib();
+            console.log('✅ hnswlib-wasm loaded and initialized successfully');
+            this.debugLog('hnswlib-wasm instance:', this.hnswLib);
+            this.debugLog('Available constructors:', Object.keys(this.hnswLib));
+            return this.hnswLib;
+        }
+        catch (error) {
+            console.error('❌ Failed to load hnswlib-wasm:', error);
+            throw new Error('hnswlib-wasm is required but not available. Install it with: npm install hnswlib-wasm');
+        }
+    }
+    /**
+     * Create a new HNSW index
+     */
+    async createIndex(userAddress, options = {}) {
+        try {
+            this.debugLog(`Creating index for user: ${userAddress}`);
+            const hnswLib = await this.loadHnswLib();
+            const config = { ...this.indexConfig, ...options };
+            console.log(`Creating new HNSW index for user ${userAddress} with dimensions ${config.dimension}`);
+            this.debugLog('Index config:', config);
+            // Create a new index (hnswlib-wasm API)
+            // Note: hnswlib-wasm requires 3 parameters: spaceName, numDimensions, autoSaveFilename
+            this.debugLog('Calling HierarchicalNSW constructor...');
+            const indexFilename = `hnsw_${userAddress.substring(0, 10)}.dat`;
+            const index = new hnswLib.HierarchicalNSW(config.spaceType, config.dimension, indexFilename);
+            this.debugLog('Index created, calling initIndex...');
+            index.initIndex(config.maxElements, config.m, config.efConstruction, config.randomSeed);
+            this.debugLog('Index initialized successfully');
+            // Create cache entry
+            this.indexCache.set(userAddress, {
+                index,
+                lastModified: new Date(),
+                pendingVectors: new Map(),
+                isDirty: false,
+                version: 1,
+                metadata: new Map()
+            });
+            this.debugLog(`Index cached for user: ${userAddress}`);
+            // Write index to Emscripten FS (hnswlib-wasm uses writeIndex, not serializeIndex)
+            await index.writeIndex(indexFilename);
+            this.debugLog(`Index written to Emscripten FS: ${indexFilename}`);
+            // Return empty buffer for compatibility (actual data is in Emscripten FS)
+            return { index, serialized: new ArrayBuffer(0) };
+        }
+        catch (error) {
+            console.error(`❌ Failed to create index for ${userAddress}:`, error);
+            throw this.createVectorError('INDEX_ERROR', `Failed to create index: ${error}`, error);
+        }
+    }
+    /**
+     * Add vector to index with batching (main entry point)
+     */
+    addVectorToIndexBatched(userAddress, vectorId, vector, metadata) {
+        try {
+            // Validate input
+            this.validateVector(vector);
+            // Get or create cache entry
+            let cacheEntry = this.indexCache.get(userAddress);
+            if (!cacheEntry) {
+                console.warn(`No cached index found for user ${userAddress}, will create on flush`);
+                // Create empty cache entry
+                cacheEntry = {
+                    index: null,
+                    lastModified: new Date(),
+                    pendingVectors: new Map(),
+                    isDirty: true,
+                    version: 1,
+                    metadata: new Map()
+                };
+                this.indexCache.set(userAddress, cacheEntry);
+            }
+            // Add to pending queue
+            cacheEntry.pendingVectors.set(vectorId, vector);
+            if (metadata) {
+                cacheEntry.metadata.set(vectorId, metadata);
+            }
+            cacheEntry.isDirty = true;
+            cacheEntry.lastModified = new Date();
+            // Schedule batch job
+            this.scheduleBatchJob(userAddress, vectorId, vector);
+            console.debug(`Vector ${vectorId} queued for batch processing for user ${userAddress}. Pending: ${cacheEntry.pendingVectors.size}`);
+            // Process immediately if batch size limit reached
+            if (cacheEntry.pendingVectors.size >= this.config.maxBatchSize) {
+                console.log(`Batch size limit reached for user ${userAddress}, processing immediately`);
+                setTimeout(() => this.flushPendingVectors(userAddress), 0);
+            }
+        }
+        catch (error) {
+            throw this.createVectorError('INDEX_ERROR', `Failed to queue vector: ${error}`, error);
+        }
+    }
+    /**
+     * Search vectors in the index (including pending vectors)
+     */
+    async searchVectors(userAddress, queryVector, options = {}) {
+        try {
+            this.debugLog(`🔍 searchVectors called for user: ${userAddress}`);
+            this.debugLog(`Query vector length: ${queryVector.length}, k: ${options.k || 10}`);
+            this.validateVector(queryVector);
+            let cacheEntry = this.indexCache.get(userAddress);
+            this.debugLog(`Cache entry exists: ${!!cacheEntry}, has index: ${!!cacheEntry?.index}`);
+            this.debugLog(`Pending vectors: ${cacheEntry?.pendingVectors?.size || 0}`);
+            // If no index exists, check if we have pending vectors that need flushing
+            if (!cacheEntry?.index && cacheEntry?.pendingVectors && cacheEntry.pendingVectors.size > 0) {
+                console.log(`🔍 No index but ${cacheEntry.pendingVectors.size} pending vectors - flushing first...`);
+                await this.flushPendingVectors(userAddress);
+                cacheEntry = this.indexCache.get(userAddress); // Refresh after flush
+                this.debugLog(`After flush - cache entry: ${!!cacheEntry}, has index: ${!!cacheEntry?.index}`);
+            }
+            if (!cacheEntry?.index) {
+                this.debugLog('No index in cache, attempting to load from IndexedDB...');
+                // Try to load from IndexedDB
+                const loaded = await this.loadIndexFromDB(userAddress);
+                this.debugLog(`loadIndexFromDB result: ${loaded}`);
+                if (!loaded) {
+                    // Check one more time for pending vectors (edge case)
+                    const entry = this.indexCache.get(userAddress);
+                    if (entry?.pendingVectors && entry.pendingVectors.size > 0) {
+                        console.log(`🔍 Found ${entry.pendingVectors.size} pending vectors - flushing before search...`);
+                        await this.flushPendingVectors(userAddress);
+                        // Reload after flush
+                        cacheEntry = this.indexCache.get(userAddress);
+                        this.debugLog(`After second flush - has index: ${!!cacheEntry?.index}`);
+                    }
+                    else {
+                        // No index exists yet - this is normal for new users with no memories
+                        console.info(`No index found for user ${userAddress} - returning empty results`);
+                        this.debugLog('Returning empty search results');
+                        return {
+                            ids: [],
+                            distances: [],
+                            similarities: []
+                        };
+                    }
+                }
+                else {
+                    cacheEntry = this.indexCache.get(userAddress);
+                    this.debugLog(`Loaded from DB - has index: ${!!cacheEntry?.index}`);
+                }
+            }
+            const { k = 10, efSearch = 50, filter } = options;
+            this.debugLog(`Search parameters - k: ${k}, efSearch: ${efSearch}`);
+            const entry = this.indexCache.get(userAddress);
+            // Get index stats before search
+            if (entry.index && entry.index.getCurrentCount) {
+                const count = entry.index.getCurrentCount();
+                console.log(`📊 Index stats - Current count: ${count}, Pending: ${entry.pendingVectors.size}`);
+                this.debugLog(`Index current count: ${count}`);
+                if (count === 0) {
+                    console.warn(`⚠️ Index exists but has 0 vectors! This may indicate an indexing problem.`);
+                }
+            }
+            // Set search parameters
+            if (entry.index.setEfSearch) {
+                entry.index.setEfSearch(efSearch);
+                this.debugLog(`Set efSearch to ${efSearch}`);
+            }
+            let searchIndex = entry.index;
+            // If there are pending vectors, create a temporary index for search
+            if (entry.pendingVectors.size > 0) {
+                this.debugLog(`Creating temporary index with ${entry.pendingVectors.size} pending vectors`);
+                searchIndex = await this.cloneIndexWithPending(entry, queryVector.length);
+            }
+            // Perform search
+            this.debugLog('Calling searchKnn...');
+            const result = searchIndex.searchKnn(queryVector, k, undefined);
+            this.debugLog(`searchKnn returned - neighbors: ${result?.neighbors?.length || 0}`);
+            // Apply metadata filter if provided
+            let filteredIds = result.neighbors || result.indices || [];
+            let filteredDistances = result.distances;
+            if (filter && entry.metadata.size > 0) {
+                const filtered = this.applyMetadataFilter(filteredIds, filteredDistances, entry.metadata, filter);
+                filteredIds = filtered.ids;
+                filteredDistances = filtered.distances;
+            }
+            // Convert distances to similarities (for cosine distance)
+            const similarities = this.indexConfig.spaceType === 'cosine'
+                ? filteredDistances.map((dist) => 1 - dist)
+                : filteredDistances.map((dist) => 1 / (1 + dist));
+            return {
+                ids: filteredIds,
+                distances: filteredDistances,
+                similarities
+            };
+        }
+        catch (error) {
+            throw this.createVectorError('SEARCH_ERROR', `Search failed: ${error}`, error);
+        }
+    }
+    /**
+     * Load index from IndexedDB via Emscripten FS
+     */
+    async loadIndexFromDB(userAddress) {
+        if (!this.db) {
+            await this.initializeIndexedDB();
+        }
+        return new Promise((resolve, reject) => {
+            const transaction = this.db.transaction(['indices'], 'readonly');
+            const store = transaction.objectStore('indices');
+            const request = store.get(userAddress);
+            request.onsuccess = async () => {
+                const result = request.result;
+                if (!result) {
+                    resolve(false);
+                    return;
+                }
+                try {
+                    const hnswLib = await this.loadHnswLib();
+                    const indexFilename = `hnsw_${userAddress.substring(0, 10)}.dat`;
+                    // Sync from IndexedDB to Emscripten FS
+                    await hnswLib.EmscriptenFileSystemManager.syncFS(true, () => {
+                        // Callback when sync completes
+                    });
+                    // Check if file exists
+                    if (!hnswLib.EmscriptenFileSystemManager.checkFileExists(indexFilename)) {
+                        console.log(`Index file ${indexFilename} not found in Emscripten FS`);
+                        resolve(false);
+                        return;
+                    }
+                    // Create index and load from file
+                    const index = new hnswLib.HierarchicalNSW(this.indexConfig.spaceType, this.indexConfig.dimension, indexFilename);
+                    // Read the index from file
+                    await index.readIndex(indexFilename, this.indexConfig.maxElements);
+                    // Convert metadata string keys back to numbers (vectorId)
+                    const metadataEntries = Object.entries(result.metadata || {})
+                        .map(([k, v]) => [Number(k), v]);
+                    // Cache the loaded index
+                    this.indexCache.set(userAddress, {
+                        index,
+                        lastModified: new Date(result.lastUpdated),
+                        pendingVectors: new Map(),
+                        isDirty: false,
+                        version: result.version,
+                        metadata: new Map(metadataEntries)
+                    });
+                    console.log(`✅ Successfully loaded index for user ${userAddress} from IndexedDB`);
+                    resolve(true);
+                }
+                catch (error) {
+                    console.error('Failed to load index:', error);
+                    reject(error);
+                }
+            };
+            request.onerror = () => reject(new Error('Failed to load index from IndexedDB'));
+        });
+    }
+    /**
+     * Save index to IndexedDB via Emscripten FS
+     */
+    async saveIndexToDB(userAddress) {
+        const cacheEntry = this.indexCache.get(userAddress);
+        if (!cacheEntry?.index) {
+            throw new Error(`No index found for user ${userAddress}`);
+        }
+        if (!this.db) {
+            await this.initializeIndexedDB();
+        }
+        try {
+            const hnswLib = await this.loadHnswLib();
+            const indexFilename = `hnsw_${userAddress.substring(0, 10)}.dat`;
+            // Write index to Emscripten FS
+            await cacheEntry.index.writeIndex(indexFilename);
+            // Sync from Emscripten FS to IndexedDB
+            await hnswLib.EmscriptenFileSystemManager.syncFS(false, () => {
+                // Callback when sync completes
+            });
+            // Store metadata in our IndexedDB (separate from Emscripten's IDBFS)
+            return new Promise((resolve, reject) => {
+                const transaction = this.db.transaction(['indices'], 'readwrite');
+                const store = transaction.objectStore('indices');
+                const data = {
+                    userAddress,
+                    indexData: new ArrayBuffer(0), // Actual data is in Emscripten FS/IDBFS
+                    metadata: Object.fromEntries(cacheEntry.metadata),
+                    version: cacheEntry.version,
+                    lastUpdated: Date.now()
+                };
+                const request = store.put(data);
+                request.onsuccess = () => {
+                    console.log(`✅ Index saved to IndexedDB for user ${userAddress}`);
+                    resolve();
+                };
+                request.onerror = () => reject(new Error('Failed to save index metadata to IndexedDB'));
+            });
+        }
+        catch (error) {
+            console.error(`Failed to save index for user ${userAddress}:`, error);
+            throw error;
+        }
+    }
+    /**
+     * Force flush all pending vectors for a user
+     */
+    async forceFlush(userAddress) {
+        await this.flushPendingVectors(userAddress);
+    }
+    /**
+     * Get cache statistics
+     */
+    getCacheStats() {
+        const cacheEntries = [];
+        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,
+                hasIndex: !!entry.index
+            });
+        }
+        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
+        };
+    }
+    /**
+     * Clear user index and cache
+     */
+    clearUserIndex(userAddress) {
+        this.indexCache.delete(userAddress);
+        this.batchJobs.delete(userAddress);
+        console.log(`Cleared index cache for user ${userAddress}`);
+    }
+    /**
+     * Cleanup resources
+     */
+    destroy() {
+        if (this.batchProcessor) {
+            clearInterval(this.batchProcessor);
+        }
+        if (this.cacheCleanup) {
+            clearInterval(this.cacheCleanup);
+        }
+        this.indexCache.clear();
+        this.batchJobs.clear();
+        if (this.db) {
+            this.db.close();
+        }
+    }
+    // ==================== PRIVATE METHODS ====================
+    scheduleBatchJob(userAddress, vectorId, vector) {
+        let batchJob = this.batchJobs.get(userAddress);
+        if (!batchJob) {
+            batchJob = {
+                userAddress,
+                vectors: new Map(),
+                scheduledAt: new Date()
+            };
+            this.batchJobs.set(userAddress, batchJob);
+        }
+        batchJob.vectors.set(vectorId, vector);
+    }
+    startBatchProcessor() {
+        this.batchProcessor = window.setInterval(async () => {
+            await this.processBatchJobs();
+        }, this.config.batchDelayMs);
+    }
+    startCacheCleanup() {
+        this.cacheCleanup = window.setInterval(() => {
+            this.cleanupCache();
+        }, 5 * 60 * 1000); // Every 5 minutes
+    }
+    async processBatchJobs() {
+        const now = Date.now();
+        const jobsToProcess = [];
+        for (const [userAddress, job] of this.batchJobs.entries()) {
+            const timeSinceScheduled = now - job.scheduledAt.getTime();
+            const cacheEntry = this.indexCache.get(userAddress);
+            if (timeSinceScheduled >= this.config.batchDelayMs ||
+                (cacheEntry && cacheEntry.pendingVectors.size >= this.config.maxBatchSize)) {
+                jobsToProcess.push(userAddress);
+            }
+        }
+        for (const userAddress of jobsToProcess) {
+            try {
+                await this.flushPendingVectors(userAddress);
+            }
+            catch (error) {
+                console.error(`Error processing batch job for user ${userAddress}:`, error);
+            }
+        }
+    }
+    async flushPendingVectors(userAddress) {
+        const cacheEntry = this.indexCache.get(userAddress);
+        if (!cacheEntry || cacheEntry.pendingVectors.size === 0) {
+            return;
+        }
+        console.log(`Flushing ${cacheEntry.pendingVectors.size} pending vectors for user ${userAddress}`);
+        try {
+            // Create index if it doesn't exist
+            if (!cacheEntry.index) {
+                const { index } = await this.createIndex(userAddress);
+                cacheEntry.index = index;
+            }
+            // Add all pending vectors to the index
+            for (const [vectorId, vector] of cacheEntry.pendingVectors.entries()) {
+                cacheEntry.index.addPoint(vector, vectorId, false);
+            }
+            // Save to IndexedDB
+            await this.saveIndexToDB(userAddress);
+            // Clear pending vectors
+            cacheEntry.pendingVectors.clear();
+            cacheEntry.isDirty = false;
+            cacheEntry.lastModified = new Date();
+            cacheEntry.version++;
+            // Remove batch job
+            this.batchJobs.delete(userAddress);
+            console.log(`Successfully flushed vectors for user ${userAddress}`);
+        }
+        catch (error) {
+            console.error(`Error flushing vectors for user ${userAddress}:`, error);
+            throw error;
+        }
+    }
+    async cloneIndexWithPending(cacheEntry, dimensions) {
+        const hnswLib = await this.loadHnswLib();
+        const tempFilename = `temp_clone_${Date.now()}.dat`;
+        // Save original index to temp file
+        await cacheEntry.index.writeIndex(tempFilename);
+        // Create clone and load from temp file
+        const clonedIndex = new hnswLib.HierarchicalNSW(this.indexConfig.spaceType, dimensions, tempFilename);
+        clonedIndex.initIndex(this.indexConfig.maxElements, this.indexConfig.m, this.indexConfig.efConstruction, this.indexConfig.randomSeed);
+        await clonedIndex.readIndex(tempFilename, this.indexConfig.maxElements);
+        // Add pending vectors
+        for (const [vectorId, vector] of cacheEntry.pendingVectors.entries()) {
+            clonedIndex.addPoint(vector, vectorId, false);
+        }
+        return clonedIndex;
+    }
+    applyMetadataFilter(ids, distances, metadata, filter) {
+        const filteredIds = [];
+        const filteredDistances = [];
+        for (let i = 0; i < ids.length; i++) {
+            const vectorId = ids[i];
+            const vectorMetadata = metadata.get(vectorId);
+            if (!vectorMetadata || filter(vectorMetadata)) {
+                filteredIds.push(vectorId);
+                filteredDistances.push(distances[i]);
+            }
+        }
+        return { ids: filteredIds, distances: filteredDistances };
+    }
+    cleanupCache() {
+        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);
+            }
+        }
+    }
+    validateVector(vector) {
+        if (!Array.isArray(vector) || vector.length === 0) {
+            throw new Error('Vector must be a non-empty array');
+        }
+        if (vector.some(v => typeof v !== 'number' || !isFinite(v))) {
+            throw new Error('Vector must contain only finite numbers');
+        }
+        if (vector.length !== this.indexConfig.dimension) {
+            throw new Error(`Vector dimension mismatch: expected ${this.indexConfig.dimension}, got ${vector.length}`);
+        }
+    }
+    createVectorError(code, message, details) {
+        const error = new Error(message);
+        error.code = code;
+        error.details = details;
+        return error;
+    }
+}
+export default BrowserHnswIndexService;
+//# sourceMappingURL=BrowserHnswIndexService.js.map