@cmdoss/memwal-sdk 0.6.1 → 0.7.0

package/src/client/SimplePDWClient.ts

@@ -31,7 +31,7 @@ import type { Keypair } from '@mysten/sui/cryptography';
 import type { UnifiedSigner, WalletAdapter } from './signers';
 import { KeypairSigner, WalletAdapterSigner } from './signers';
 import { StorageService } from '../services/StorageService';
-import { EmbeddingService } from '../services/EmbeddingService';
+import { EmbeddingService, getSharedEmbeddingService } from '../services/EmbeddingService';
 import { MemoryService } from '../services/MemoryService';
 import { QueryService } from '../services/QueryService';
 import { ClassifierService } from '../services/ClassifierService';
@@ -130,7 +130,7 @@ export interface SimplePDWConfig {
     modelName?: string;
     /**
      * Embedding dimensions
-     * @default 768 (for google/openrouter), 1536 (for openai)
+     * @default 3072 (for google/openrouter), 1536 (for openai)
      */
     dimensions?: number;
   };
@@ -190,6 +190,23 @@ export interface SimplePDWConfig {
     /** Progress callback for index operations */
     onProgress?: IndexProgressCallback;
   };
+
+  /**
+   * Optional: Index backup to Walrus cloud storage
+   * Enables syncing local HNSW index to Walrus for cross-device restoration
+   */
+  indexBackup?: {
+    /** Enable Walrus backup for local index */
+    enabled: boolean;
+    /** Walrus aggregator URL for downloading */
+    aggregatorUrl?: string;
+    /** Walrus publisher URL for uploading */
+    publisherUrl?: string;
+    /** Auto-sync index to Walrus on every save (default: false) */
+    autoSync?: boolean;
+    /** Storage duration in epochs (default: 3) */
+    epochs?: number;
+  };
 }
 
 /**
@@ -239,6 +256,13 @@ interface ResolvedConfig {
     enableAutoSave?: boolean;
     onProgress?: IndexProgressCallback;
   };
+  indexBackup?: {
+    enabled: boolean;
+    aggregatorUrl?: string;
+    publisherUrl?: string;
+    autoSync?: boolean;
+    epochs?: number;
+  };
 }
 
 /**
@@ -360,7 +384,8 @@ export class SimplePDWClient {
         enableLocalIndexing: config.features?.enableLocalIndexing ?? true,
         enableKnowledgeGraph: config.features?.enableKnowledgeGraph ?? true
       },
-      indexManager: config.indexManager
+      indexManager: config.indexManager,
+      indexBackup: config.indexBackup
     };
   }
 
@@ -433,17 +458,19 @@ export class SimplePDWClient {
       useUploadRelay: true
     });
 
-    // 2. Embedding Service (if API key provided)
+    // 2. Embedding Service (if API key provided) - uses singleton pattern
     let embedding: EmbeddingService | undefined;
     if (embeddingConfig.apiKey) {
-      embedding = new EmbeddingService({
+      // Use singleton to share EmbeddingService across all clients
+      // Reduces memory usage and connection overhead for multi-user scenarios
+      embedding = getSharedEmbeddingService({
         provider: embeddingConfig.provider,
         apiKey: embeddingConfig.apiKey,
         modelName: embeddingConfig.modelName,
         dimensions: embeddingConfig.dimensions
       });
 
-      console.log(`✅ Embedding Service initialized: ${embeddingConfig.provider}/${embeddingConfig.modelName} (${embeddingConfig.dimensions}d)`);
+      console.log(`✅ Embedding Service (singleton): ${embeddingConfig.provider}/${embeddingConfig.modelName} (${embeddingConfig.dimensions}d)`);
 
       // Connect to storage for search
       storage.initializeSearch(embedding);
@@ -473,6 +500,15 @@ export class SimplePDWClient {
     // Note: This starts async initialization - services will wait for it when needed
     let sharedHnswService: IHnswService | undefined;
     if (config.features.enableLocalIndexing) {
+      // Prepare Walrus backup config if enabled
+      const walrusBackupConfig = config.indexBackup?.enabled ? {
+        enabled: true,
+        aggregatorUrl: config.indexBackup.aggregatorUrl || config.walrus.aggregator,
+        publisherUrl: config.indexBackup.publisherUrl || config.walrus.publisher,
+        autoSync: config.indexBackup.autoSync ?? false,
+        epochs: config.indexBackup.epochs ?? 3
+      } : undefined;
+
       // Dynamic import to avoid bundling Node.js dependencies (hnswlib-node) in browser builds
       // When enableLocalIndexing is false, this code never runs and webpack won't bundle it
       this.sharedHnswServicePromise = import('../vector/createHnswService').then(
@@ -486,10 +522,14 @@ export class SimplePDWClient {
           batchConfig: {
             maxBatchSize: 100,
             batchDelayMs: 5000
-          }
+          },
+          walrusBackup: walrusBackupConfig
         })
       );
       console.log('✅ Shared HNSW service initialization started (singleton for all vector services)');
+      if (walrusBackupConfig?.enabled) {
+        console.log('   ☁️ Walrus backup enabled for local index');
+      }
     }
 
     // 9a. Vector Service (if local indexing enabled)
@@ -722,11 +762,24 @@ export class SimplePDWClient {
       }
 
       // Initialize knowledge graph if enabled
-      if (this.config.features.enableKnowledgeGraph && this.services.embedding) {
-        await this.services.storage.initializeKnowledgeGraph({
+      // Use apiKey (OpenRouter) as primary, fallback to geminiApiKey for backward compatibility
+      const graphApiKey = this.config.ai.apiKey || this.config.ai.geminiApiKey;
+      if (this.config.features.enableKnowledgeGraph && this.services.embedding && graphApiKey) {
+        const graphService = await this.services.storage.initializeKnowledgeGraph({
           embeddingService: this.services.embedding,
-          geminiApiKey: this.config.ai.geminiApiKey
+          geminiApiKey: graphApiKey
         });
+
+        // Update QueryService with the initialized GraphService
+        if (graphService && this.services.query && this.services.memoryIndex && this.services.embedding) {
+          this.services.query.initialize(
+            this.services.memoryIndex,
+            this.services.embedding,
+            this.services.storage,
+            graphService
+          );
+          console.log('✅ QueryService updated with Knowledge Graph');
+        }
       }
 
       this.initialized = true;

package/src/client/namespaces/EmbeddingsNamespace.ts

@@ -24,7 +24,7 @@ export class EmbeddingsNamespace {
    *
    * @param text - Text to embed
    * @param options - Embedding options
-   * @returns Embedding vector (768 dimensions for Gemini)
+   * @returns Embedding vector (3072 dimensions for Gemini)
    */
   async generate(text: string, options?: { type?: 'query' | 'document' }): Promise<number[]> {
     if (!this.services.embedding) {

package/src/client/namespaces/IndexNamespace.ts

@@ -189,13 +189,11 @@ export class IndexNamespace {
   }
 
   /**
-   * Save index to Walrus storage
+   * Save index to local storage
    *
-   * Persists the HNSW index binary to Walrus for durability.
-   * Uses HnswWasmService.saveIndex() which properly serializes the index.
+   * Persists the HNSW index binary to local filesystem.
    *
    * @param spaceId - Index space identifier (userAddress)
-   * @returns Blob ID of saved index on Walrus, or null if no index exists
    */
   async save(spaceId: string): Promise<void> {
     const { type, service } = this.getService();
@@ -211,26 +209,106 @@ export class IndexNamespace {
   }
 
   /**
-   * Load index from Walrus storage
+   * Load index from storage (local or Walrus)
    *
-   * Loads a previously saved HNSW index from Walrus.
-   * Uses HnswWasmService.loadIndex() which properly deserializes the binary.
+   * If blobId is provided, attempts to load from Walrus first.
+   * Falls back to local storage if Walrus load fails.
    *
    * @param spaceId - Index space identifier (userAddress)
-   * @param blobId - Blob ID of the saved index on Walrus
+   * @param blobId - Optional Walrus blob ID to load from cloud
    */
-  async load(spaceId: string, blobId: string): Promise<void> {
+  async load(spaceId: string, blobId?: string): Promise<void> {
     const { type, service } = this.getService();
 
     if (type === 'memoryIndex') {
-      // MemoryIndexService.loadIndex(userAddress, indexBlobId?)
       await service.loadIndex(spaceId, blobId);
-      console.log(`Index loaded from Walrus: ${blobId}`);
+      if (blobId) {
+        console.log(`Index loaded from Walrus: ${blobId}`);
+      } else {
+        console.log(`Index loaded from local storage: ${spaceId}`);
+      }
     } else {
       await service.loadIndex(spaceId, blobId);
     }
   }
 
+  /**
+   * Sync index to Walrus cloud storage
+   *
+   * Uploads the HNSW index binary + metadata to Walrus for durability.
+   * This enables cross-device index restoration.
+   *
+   * @param spaceId - Index space identifier (userAddress)
+   * @returns Walrus blob ID if successful, null if Walrus is disabled
+   */
+  async syncToWalrus(spaceId: string): Promise<string | null> {
+    const { type, service } = this.getService();
+
+    if (type === 'memoryIndex' && 'syncToWalrus' in service) {
+      const blobId = await service.syncToWalrus(spaceId);
+      if (blobId) {
+        console.log(`Index synced to Walrus: ${blobId}`);
+      }
+      return blobId;
+    }
+
+    console.warn('Walrus sync not available for this service type');
+    return null;
+  }
+
+  /**
+   * Load index from Walrus cloud storage
+   *
+   * Downloads and restores a previously synced index from Walrus.
+   *
+   * @param spaceId - Index space identifier (userAddress)
+   * @param blobId - Walrus blob ID of the saved index
+   * @returns true if successfully loaded
+   */
+  async loadFromWalrus(spaceId: string, blobId: string): Promise<boolean> {
+    const { type, service } = this.getService();
+
+    if (type === 'memoryIndex' && 'loadFromWalrus' in service) {
+      const loaded = await service.loadFromWalrus(spaceId, blobId);
+      if (loaded) {
+        console.log(`Index loaded from Walrus: ${blobId}`);
+      }
+      return loaded;
+    }
+
+    console.warn('Walrus load not available for this service type');
+    return false;
+  }
+
+  /**
+   * Get the Walrus blob ID for a user's index (if backed up)
+   *
+   * @param spaceId - Index space identifier (userAddress)
+   * @returns Blob ID or null if not backed up
+   */
+  getWalrusBlobId(spaceId: string): string | null {
+    const { type, service } = this.getService();
+
+    if (type === 'memoryIndex' && 'getWalrusBlobId' in service) {
+      return service.getWalrusBlobId(spaceId);
+    }
+
+    return null;
+  }
+
+  /**
+   * Check if Walrus backup is enabled
+   */
+  isWalrusEnabled(): boolean {
+    const { type, service } = this.getService();
+
+    if (type === 'memoryIndex' && 'isWalrusEnabled' in service) {
+      return service.isWalrusEnabled();
+    }
+
+    return false;
+  }
+
   /**
    * Clear index and remove all vectors
    *

package/src/client/namespaces/MemoryNamespace.ts

@@ -1132,4 +1132,141 @@ export class MemoryNamespace {
       throw new Error(`Failed to export memories: ${error instanceof Error ? error.message : String(error)}`);
     }
   }
+
+  /**
+   * Index memories from a Quilt into the local HNSW index
+   *
+   * This allows Quilt batch-uploaded memories to be searchable via vector search.
+   * The method fetches memory packages from the Quilt and indexes each one.
+   *
+   * @param quiltId - The Quilt blob ID containing memory packages
+   * @param options - Indexing options
+   * @returns Result with number of memories indexed
+   *
+   * @example
+   * ```typescript
+   * // After uploading a batch via Quilt
+   * const result = await pdw.memory.indexFromQuilt('GTNhNTdWecbUVg3cZuC_VKlRSzJE3iQfBkojWUuwoh0');
+   * console.log(`Indexed ${result.indexed} memories from Quilt`);
+   * ```
+   */
+  async indexFromQuilt(
+    quiltId: string,
+    options?: { forceReindex?: boolean }
+  ): Promise<{
+    success: boolean;
+    total: number;
+    indexed: number;
+    skipped: number;
+    failed: number;
+    errors: string[];
+  }> {
+    const errors: string[] = [];
+    let indexed = 0;
+    let skipped = 0;
+    let failed = 0;
+
+    try {
+      console.log(`📦 Indexing memories from Quilt ${quiltId}...`);
+
+      // Check if index service is available
+      if (!this.services.memoryIndex) {
+        throw new Error('Memory index service not available');
+      }
+
+      // Check if quilt manager is available
+      if (!this.services.storage?.quiltBatchManager) {
+        throw new Error('Quilt batch manager not available');
+      }
+
+      // Fetch all memory packages from the Quilt
+      const packages = await this.services.storage.quiltBatchManager.getAllMemoryPackages(quiltId);
+      console.log(`   Found ${packages.length} memory packages in Quilt`);
+
+      // Index each memory
+      for (const pkg of packages) {
+        try {
+          const { identifier, memoryPackage, tags } = pkg;
+
+          // Skip if no embedding
+          if (!memoryPackage.embedding || memoryPackage.embedding.length === 0) {
+            console.warn(`   ⚠️ Skipping ${identifier}: no embedding`);
+            skipped++;
+            continue;
+          }
+
+          // Create a unique memory ID from identifier or use memoryId from metadata
+          const memoryId = memoryPackage.metadata?.memoryId as string ||
+            identifier.replace('.json', '').replace('memory-', '');
+
+          // Build metadata for indexing (satisfy MemoryMetadata interface)
+          const metadata = {
+            category: memoryPackage.metadata?.category || 'general',
+            importance: memoryPackage.metadata?.importance || 3,
+            topic: memoryPackage.metadata?.topic || '',
+            contentType: 'text',
+            contentSize: memoryPackage.content?.length || 0,
+            contentHash: '', // Not available from Quilt package
+            embeddingDimension: memoryPackage.embedding?.length || 0,
+            createdTimestamp: memoryPackage.timestamp,
+            customMetadata: {
+              quiltId,
+              identifier,
+              ...Object.fromEntries(
+                Object.entries(memoryPackage.metadata || {}).map(([k, v]) => [k, String(v)])
+              )
+            }
+          };
+
+          // Content is empty if encrypted, use placeholder
+          const content = memoryPackage.content || '[encrypted]';
+          const isEncrypted = memoryPackage.encrypted === true;
+
+          // Index the memory
+          await this.services.memoryIndex.indexMemory(
+            this.services.config.userAddress,
+            memoryId,
+            quiltId, // Use quiltId as blobId for retrieval reference
+            content,
+            metadata,
+            memoryPackage.embedding,
+            { isEncrypted }
+          );
+
+          indexed++;
+          console.log(`   ✅ Indexed ${identifier} (${indexed}/${packages.length})`);
+
+        } catch (pkgError) {
+          const errMsg = pkgError instanceof Error ? pkgError.message : String(pkgError);
+          errors.push(`${pkg.identifier}: ${errMsg}`);
+          failed++;
+          console.error(`   ❌ Failed to index ${pkg.identifier}:`, errMsg);
+        }
+      }
+
+      console.log(`\n📊 Quilt indexing complete:`);
+      console.log(`   Total: ${packages.length}, Indexed: ${indexed}, Skipped: ${skipped}, Failed: ${failed}`);
+
+      return {
+        success: failed === 0,
+        total: packages.length,
+        indexed,
+        skipped,
+        failed,
+        errors
+      };
+
+    } catch (error) {
+      const errMsg = error instanceof Error ? error.message : String(error);
+      console.error(`❌ Failed to index from Quilt: ${errMsg}`);
+      return {
+        success: false,
+        total: 0,
+        indexed,
+        skipped,
+        failed,
+        errors: [errMsg, ...errors]
+      };
+    }
+  }
 }

package/src/client/namespaces/SearchNamespace.ts

@@ -154,18 +154,26 @@ export class SearchNamespace {
 
       // Convert to SearchResult format
       // Option A+: Content may be available from local index when encryption is OFF
-      const searchResults: SearchResult[] = results.map((r: any) => ({
-        id: r.memoryId || r.vectorId.toString(),
-        content: r.metadata?.content || r.content || '', // ✅ Get content from index metadata if available
-        score: r.similarity,
-        similarity: r.similarity,
-        category: r.metadata?.category,
-        importance: r.metadata?.importance || 5,
-        topic: r.metadata?.topic,
-        blobId: r.metadata?.blobId || r.memoryId || r.vectorId.toString(),
-        metadata: r.metadata || {},
-        timestamp: r.metadata?.timestamp || Date.now()
-      }));
+      const searchResults: SearchResult[] = results.map((r: any) => {
+        // blobId must be a valid Walrus blob ID, not a vectorId
+        // Only use metadata.blobId if it's a non-empty string that looks like a Walrus blobId
+        const rawBlobId = r.metadata?.blobId;
+        const isValidBlobId = rawBlobId && typeof rawBlobId === 'string' && rawBlobId.length > 10 && !/^\d+$/.test(rawBlobId);
+        const blobId = isValidBlobId ? rawBlobId : (r.metadata?.memoryObjectId || '');
+
+        return {
+          id: r.memoryId || r.vectorId.toString(),
+          content: r.metadata?.content || r.content || '', // ✅ Get content from index metadata if available
+          score: r.similarity,
+          similarity: r.similarity,
+          category: r.metadata?.category,
+          importance: r.metadata?.importance || 5,
+          topic: r.metadata?.topic,
+          blobId,
+          metadata: r.metadata || {},
+          timestamp: r.metadata?.timestamp || Date.now()
+        };
+      });
 
       // Optionally fetch content from Walrus
       if (fetchContent) {
@@ -329,7 +337,12 @@ export class SearchNamespace {
           const localResults = this.services.vector.getVectorsByCategory(spaceId, category);
 
           for (const { vectorId, metadata } of localResults) {
-            const id = metadata?.blobId || metadata?.memoryId || vectorId?.toString();
+            // blobId must be a valid Walrus blob ID, not a vectorId
+            const rawBlobId = metadata?.blobId;
+            const isValidBlobId = rawBlobId && typeof rawBlobId === 'string' && rawBlobId.length > 10 && !/^\d+$/.test(rawBlobId);
+            const blobId = isValidBlobId ? rawBlobId : (metadata?.memoryObjectId || '');
+            const id = blobId || metadata?.memoryId || vectorId?.toString();
+
             if (id && !seenIds.has(id)) {
               seenIds.add(id);
               results.push({
@@ -340,7 +353,7 @@ export class SearchNamespace {
                 category: metadata?.category,
                 importance: metadata?.importance || 5,
                 topic: metadata?.topic,
-                blobId: id,
+                blobId,
                 metadata: metadata || {},
                 timestamp: metadata?.timestamp || Date.now()
               });

package/src/client/namespaces/consolidated/AINamespace.ts

@@ -76,12 +76,12 @@ export class AINamespace {
    *
    * @param text - Text to embed
    * @param options - Embedding options
-   * @returns Embedding vector (768 dimensions for Gemini)
+   * @returns Embedding vector (3072 dimensions for Gemini)
    *
    * @example
    * ```typescript
    * const vector = await pdw.ai.embed('My favorite color is blue');
-   * console.log(vector.length); // 768
+   * console.log(vector.length); // 3072
    * ```
    */
   async embed(text: string, options?: EmbedOptions): Promise<number[]> {

package/src/client/namespaces/consolidated/BlockchainNamespace.ts

@@ -135,12 +135,84 @@ class TxSubNamespace {
    * ```
    */
   async execute(tx: Transaction): Promise<TransactionResult> {
+    const signer = this.services.config.signer;
+
+    // Check if signer supports signAndExecuteTransaction (browser wallets like DappKitSigner)
+    // Browser wallets cannot expose raw Signer for security reasons
+    if ('signAndExecuteTransaction' in signer && typeof signer.signAndExecuteTransaction === 'function') {
+      try {
+        // Use the signer's signAndExecuteTransaction directly
+        const result = await signer.signAndExecuteTransaction(tx);
+
+        // Get full transaction details to extract created objects
+        let createdObjects: Array<{ objectId: string; objectType: string }> | undefined;
+        let mutatedObjects: Array<{ objectId: string; objectType: string }> | undefined;
+
+        if (result.objectChanges && Array.isArray(result.objectChanges)) {
+          createdObjects = result.objectChanges
+            .filter((change: any) => change.type === 'created')
+            .map((change: any) => ({
+              objectId: change.objectId,
+              objectType: change.objectType || 'unknown',
+            }));
+
+          mutatedObjects = result.objectChanges
+            .filter((change: any) => change.type === 'mutated')
+            .map((change: any) => ({
+              objectId: change.objectId,
+              objectType: change.objectType || 'unknown',
+            }));
+        }
+
+        // Determine status from effects
+        // dapp-kit may not return full effects structure unless custom execute is configured
+        // We check multiple indicators:
+        // 1. If effects.status.status explicitly says 'failure', it failed
+        // 2. If effects.status.status says 'success', it succeeded
+        // 3. If we have a digest but no effects status, assume success (tx was submitted and confirmed)
+        let status: 'success' | 'failure';
+        const effectsStatus = result.effects?.status?.status;
+
+        if (effectsStatus === 'failure') {
+          status = 'failure';
+        } else if (effectsStatus === 'success') {
+          status = 'success';
+        } else if (result.digest) {
+          // Has digest but no explicit status - DappKitSigner waits for confirmation
+          // If we reach here without error, the transaction was successful
+          status = 'success';
+        } else {
+          status = 'failure';
+        }
+
+        return {
+          digest: result.digest,
+          status,
+          effects: result.effects,
+          createdObjects,
+          mutatedObjects,
+          gasUsed: result.effects?.gasUsed?.computationCost
+            ? Number(result.effects.gasUsed.computationCost)
+            : undefined,
+          error: status === 'failure' ? (result.effects?.status?.error || 'Transaction failed without digest') : undefined,
+        };
+      } catch (error) {
+        console.error('Transaction execution failed:', error);
+        return {
+          digest: '',
+          status: 'failure',
+          error: error instanceof Error ? error.message : String(error),
+        };
+      }
+    }
+
+    // Fallback: Use TransactionService with raw Signer (Node.js/backend)
     if (!this.services.tx) {
       throw new Error('Transaction service not configured.');
     }
     return await this.services.tx.executeTransaction(
       tx,
-      this.services.config.signer.getSigner()
+      signer.getSigner()
     );
   }
 

package/src/client/namespaces/consolidated/StorageNamespace.ts

@@ -437,4 +437,61 @@ export class StorageNamespace {
       };
     }
   }
+
+  // ==========================================================================
+  // Batch Operations (Quilt)
+  // ==========================================================================
+
+  /**
+   * Upload multiple memories as a Quilt (batch upload)
+   *
+   * Uses Walrus Quilt for ~90% gas savings compared to individual uploads.
+   * Requires 2 user signatures:
+   * - Transaction 1: Register blob on-chain
+   * - Transaction 2: Certify upload on-chain
+   *
+   * @param memories - Array of memories to upload
+   * @param options - Upload options including signer
+   * @returns Quilt result with file mappings
+   *
+   * @example
+   * ```typescript
+   * const result = await pdw.storage.uploadMemoryBatch(
+   *   memories,
+   *   {
+   *     signer: pdw.getConfig().signer,
+   *     epochs: 3,
+   *     userAddress: pdw.getConfig().userAddress
+   *   }
+   * );
+   * console.log(`Uploaded ${result.files.length} files`);
+   * ```
+   */
+  async uploadMemoryBatch(
+    memories: Array<{
+      content: string;
+      category: string;
+      importance: number;
+      topic: string;
+      embedding: number[];
+      encryptedContent: Uint8Array;
+      summary?: string;
+      id?: string;
+    }>,
+    options: {
+      signer: any; // UnifiedSigner
+      epochs?: number;
+      userAddress: string;
+    }
+  ): Promise<{
+    quiltId: string;
+    files: Array<{ identifier: string; blobId: string }>;
+    uploadTimeMs: number;
+  }> {
+    if (!this.services.storage) {
+      throw new Error('Storage service not configured.');
+    }
+
+    return this.services.storage.uploadMemoryBatch(memories, options);
+  }
 }

package/src/core/types/index.ts

@@ -232,7 +232,7 @@ export interface VectorEmbedding {
 
 export interface EmbeddingOptions {
   model?: string;
-  dimension?: number; // Default 768 for Gemini
+  dimension?: number; // Default 3072 for Gemini
   normalize?: boolean;
   batchSize?: number; // For batch processing
 }