@cmdoss/memwal-sdk 0.6.0

package/dist/services/IndexManager.d.ts

@@ -0,0 +1,238 @@
+/**
+ * IndexManager - Hybrid Index Persistence Manager
+ *
+ * Provides intelligent index management with:
+ * - Option 1: Full rebuild from Blockchain + Walrus (fallback)
+ * - Option 2: Binary serialization to/from Walrus (fast)
+ * - Hybrid: Combines both with incremental sync
+ * - On-chain MemoryIndex object for versioned index tracking
+ *
+ * Flow:
+ * 1. Initialize: Check for MemoryIndex on-chain → Load blob from Walrus
+ * 2. Save: Upload to Walrus → Create/Update MemoryIndex on-chain
+ *
+ * @module services/IndexManager
+ */
+import type { VectorService } from './VectorService';
+import type { StorageService } from './StorageService';
+import type { EmbeddingService } from './EmbeddingService';
+import type { TransactionService } from './TransactionService';
+import type { MemoryIndex } from './ViewService';
+/**
+ * Index state stored in localStorage/persistent storage
+ */
+export interface IndexState {
+    /** Blob ID of the saved index on Walrus */
+    blobId: string;
+    /** Graph blob ID on Walrus (for knowledge graph) */
+    graphBlobId?: string;
+    /** Timestamp when index was last saved */
+    lastSyncTimestamp: number;
+    /** Number of vectors in the index at save time */
+    vectorCount: number;
+    /** Index version for optimistic locking (matches on-chain version) */
+    version: number;
+    /** Dimension of vectors in the index */
+    dimension: number;
+    /** On-chain MemoryIndex object ID (if created) */
+    onChainIndexId?: string;
+}
+/**
+ * Serialized index package stored on Walrus
+ */
+export interface SerializedIndexPackage {
+    /** Package format version */
+    formatVersion: '1.0';
+    /** Space ID (user address) */
+    spaceId: string;
+    /** Index version */
+    version: number;
+    /** Vector dimension */
+    dimension: number;
+    /** Timestamp of serialization */
+    timestamp: number;
+    /** Serialized HNSW index as base64 (if supported) */
+    indexBinary?: string;
+    /** All vectors with their IDs for reconstruction */
+    vectors: Array<{
+        vectorId: number;
+        vector: number[];
+    }>;
+    /** Metadata for each vector */
+    metadata: Array<[number, any]>;
+    /** HNSW config used */
+    hnswConfig: {
+        maxElements: number;
+        m: number;
+        efConstruction: number;
+    };
+}
+/**
+ * Progress callback for long operations
+ */
+export type IndexProgressCallback = (stage: 'loading' | 'rebuilding' | 'syncing' | 'saving' | 'complete', progress: number, message: string) => void;
+/**
+ * Options for IndexManager initialization
+ */
+export interface IndexManagerOptions {
+    /** Auto-save interval in ms (default: 5 minutes) */
+    autoSaveInterval?: number;
+    /** Enable auto-save (default: true) */
+    enableAutoSave?: boolean;
+    /** Storage key prefix for localStorage */
+    storageKeyPrefix?: string;
+    /** Progress callback */
+    onProgress?: IndexProgressCallback;
+    /** TransactionService for on-chain operations (optional) */
+    transactionService?: TransactionService;
+    /** Callback to get MemoryIndex from blockchain */
+    getMemoryIndexFromChain?: (userAddress: string) => Promise<MemoryIndex | null>;
+    /** Callback to execute transaction (for create/update MemoryIndex) */
+    executeTransaction?: (tx: any, signer: any) => Promise<{
+        digest: string;
+        effects?: any;
+        error?: string;
+    }>;
+}
+/**
+ * IndexManager - Manages HNSW index persistence with hybrid restore strategy
+ *
+ * Strategy:
+ * 1. Try to load from Walrus cache (fast, ~500ms)
+ * 2. If failed, rebuild from blockchain + Walrus (slow but complete)
+ * 3. Sync any new memories since last save
+ * 4. Auto-save periodically
+ */
+export declare class IndexManager {
+    private vectorService;
+    private storageService;
+    private embeddingService;
+    private options;
+    private autoSaveTimer?;
+    private indexStates;
+    private vectorCache;
+    private storage;
+    constructor(vectorService: VectorService, storageService: StorageService, embeddingService: EmbeddingService, options?: IndexManagerOptions);
+    /**
+     * Set custom storage adapter (for React Native, Node.js, etc.)
+     */
+    setStorageAdapter(adapter: {
+        getItem: (key: string) => string | null;
+        setItem: (key: string, value: string) => void;
+        removeItem: (key: string) => void;
+    }): void;
+    /**
+     * Initialize index for a user with hybrid restore strategy
+     *
+     * @param spaceId - User address / space identifier
+     * @param getMemoriesFromChain - Function to fetch memories from blockchain
+     * @param getMemoryContent - Function to fetch memory content from Walrus
+     */
+    initialize(spaceId: string, getMemoriesFromChain: () => Promise<Array<{
+        id: string;
+        blobId: string;
+        vectorId?: number;
+        category?: string;
+        importance?: number;
+        topic?: string;
+        createdAt?: number;
+    }>>, getMemoryContent: (blobId: string) => Promise<{
+        content: string;
+        embedding?: number[];
+        metadata?: any;
+    }>): Promise<{
+        restored: boolean;
+        method: 'cache' | 'rebuild' | 'empty';
+        vectorCount: number;
+        syncedCount: number;
+        timeMs: number;
+    }>;
+    /**
+     * Load index from Walrus (Option 2)
+     */
+    private loadFromWalrus;
+    /**
+     * Full rebuild from blockchain + Walrus (Option 1)
+     */
+    private fullRebuild;
+    /**
+     * Sync new memories since last save (incremental update)
+     */
+    private syncNewMemories;
+    /**
+     * Save index to Walrus
+     */
+    saveIndex(spaceId: string): Promise<string | null>;
+    /**
+     * Save index with signer (public API)
+     *
+     * This method:
+     * 1. Uploads index to Walrus
+     * 2. Creates or updates MemoryIndex on-chain (if transactionService is available)
+     * 3. Updates local state
+     *
+     * @param spaceId - User address
+     * @param signer - Wallet signer for transactions
+     * @returns Blob ID of saved index
+     */
+    saveIndexWithSigner(spaceId: string, signer: any): Promise<string | null>;
+    /**
+     * Add vector and cache it for serialization
+     */
+    addVectorWithCache(spaceId: string, vectorId: number, vector: number[], metadata?: any): Promise<void>;
+    /**
+     * Start auto-save interval
+     */
+    private startAutoSave;
+    /**
+     * Stop auto-save
+     */
+    stopAutoSave(): void;
+    /**
+     * Load index state from localStorage
+     */
+    private loadIndexState;
+    /**
+     * Save index state to localStorage
+     */
+    private saveIndexState;
+    /**
+     * Clear cached index state
+     */
+    clearIndexState(spaceId: string): void;
+    /**
+     * Get current index state
+     */
+    getIndexState(spaceId: string): IndexState | null;
+    /**
+     * Force a full rebuild (useful for troubleshooting)
+     */
+    forceRebuild(spaceId: string, getMemoriesFromChain: () => Promise<Array<{
+        id: string;
+        blobId: string;
+        vectorId?: number;
+        category?: string;
+        importance?: number;
+        topic?: string;
+        createdAt?: number;
+    }>>, getMemoryContent: (blobId: string) => Promise<{
+        content: string;
+        embedding?: number[];
+        metadata?: any;
+    }>): Promise<{
+        memoriesCount: number;
+    }>;
+    /**
+     * Get statistics
+     */
+    getStats(spaceId: string): {
+        indexState: IndexState | null;
+        vectorCacheSize: number;
+        isAutoSaveEnabled: boolean;
+    };
+    /**
+     * Cleanup resources
+     */
+    cleanup(): Promise<void>;
+}
+//# sourceMappingURL=IndexManager.d.ts.map

package/dist/services/IndexManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IndexManager.d.ts","sourceRoot":"","sources":["../../src/services/IndexManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,6BAA6B;IAC7B,aAAa,EAAE,KAAK,CAAC;IACrB,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,oBAAoB;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,uBAAuB;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,OAAO,EAAE,KAAK,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,EAAE,CAAC;KAClB,CAAC,CAAC;IACH,+BAA+B;IAC/B,QAAQ,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;IAC/B,uBAAuB;IACvB,UAAU,EAAE;QACV,WAAW,EAAE,MAAM,CAAC;QACpB,CAAC,EAAE,MAAM,CAAC;QACV,cAAc,EAAE,MAAM,CAAC;KACxB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAClC,KAAK,EAAE,SAAS,GAAG,YAAY,GAAG,SAAS,GAAG,QAAQ,GAAG,UAAU,EACnE,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,KACZ,IAAI,CAAC;AAEV;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,oDAAoD;IACpD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,uCAAuC;IACvC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,0CAA0C;IAC1C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,wBAAwB;IACxB,UAAU,CAAC,EAAE,qBAAqB,CAAC;IACnC,4DAA4D;IAC5D,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,kDAAkD;IAClD,uBAAuB,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC/E,sEAAsE;IACtE,kBAAkB,CAAC,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,KAAK,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,GAAG,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC3G;AAED;;;;;;;;GAQG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,gBAAgB,CAAmB;IAC3C,OAAO,CAAC,OAAO,CAIb;IACF,OAAO,CAAC,aAAa,CAAC,CAAiC;IACvD,OAAO,CAAC,WAAW,CAAsC;IACzD,OAAO,CAAC,WAAW,CAAiD;IAGpE,OAAO,CAAC,OAAO,CAIb;gBAGA,aAAa,EAAE,aAAa,EAC5B,cAAc,EAAE,cAAc,EAC9B,gBAAgB,EAAE,gBAAgB,EAClC,OAAO,GAAE,mBAAwB;IA0BnC;;OAEG;IACH,iBAAiB,CAAC,OAAO,EAAE;QACzB,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;QACxC,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;QAC9C,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;KACnC,GAAG,IAAI;IAIR;;;;;;OAMG;IACG,UAAU,CACd,OAAO,EAAE,MAAM,EACf,oBAAoB,EAAE,MAAM,OAAO,CAAC,KAAK,CAAC;QACxC,EAAE,EAAE,MAAM,CAAC;QACX,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC,CAAC,EACH,gBAAgB,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;QAC5C,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;QACrB,QAAQ,CAAC,EAAE,GAAG,CAAC;KAChB,CAAC,GACD,OAAO,CAAC;QACT,QAAQ,EAAE,OAAO,CAAC;QAClB,MAAM,EAAE,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC;QACtC,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IAgJF;;OAEG;YACW,cAAc;IA+F5B;;OAEG;YACW,WAAW;IAmGzB;;OAEG;YACW,eAAe;IA0E7B;;OAEG;IACG,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAgFxD;;;;;;;;;;;OAWG;IACG,mBAAmB,CACvB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,GAAG,GACV,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAuIzB;;OAEG;IACG,kBAAkB,CACtB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EAAE,EAChB,QAAQ,CAAC,EAAE,GAAG,GACb,OAAO,CAAC,IAAI,CAAC;IAYhB;;OAEG;IACH,OAAO,CAAC,aAAa;IAoBrB;;OAEG;IACH,YAAY,IAAI,IAAI;IAQpB;;OAEG;IACH,OAAO,CAAC,cAAc;IAetB;;OAEG;IACH,OAAO,CAAC,cAAc;IAKtB;;OAEG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAQtC;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAIjD;;OAEG;IACG,YAAY,CAChB,OAAO,EAAE,MAAM,EACf,oBAAoB,EAAE,MAAM,OAAO,CAAC,KAAK,CAAC;QACxC,EAAE,EAAE,MAAM,CAAC;QACX,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC,CAAC,EACH,gBAAgB,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;QAC5C,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;QACrB,QAAQ,CAAC,EAAE,GAAG,CAAC;KAChB,CAAC,GACD,OAAO,CAAC;QAAE,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;IAQrC;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG;QACzB,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;QAC9B,eAAe,EAAE,MAAM,CAAC;QACxB,iBAAiB,EAAE,OAAO,CAAC;KAC5B;IAQD;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAK/B"}