@cmdoss/memwal-sdk 0.6.0

package/dist/client/ClientMemoryManager.d.ts

@@ -0,0 +1,202 @@
+/**
+ * ClientMemoryManager - Client-side Memory Operations for React dApps
+ *
+ * Provides a simplified API for creating and retrieving memories in React dApps
+ * using @mysten/dapp-kit. Handles the complete flow:
+ * - Memory creation: embedding → encryption → Walrus upload → on-chain registration
+ * - Memory retrieval: Walrus fetch → SEAL decryption → content extraction
+ *
+ * Usage:
+ * ```typescript
+ * const manager = new ClientMemoryManager({
+ *   packageId: '0x...',
+ *   accessRegistryId: '0x...',
+ *   walrusAggregator: 'https://...',
+ *   geminiApiKey: 'your-key'
+ * });
+ *
+ * // Create memory
+ * const blobId = await manager.createMemory({
+ *   content: 'My memory',
+ *   account,
+ *   signAndExecute,
+ *   client,
+ *   onProgress: (status) => console.log(status)
+ * });
+ *
+ * // Retrieve memory
+ * const content = await manager.retrieveMemory({
+ *   blobId: '...',
+ *   account,
+ *   signPersonalMessage,
+ *   client
+ * });
+ * ```
+ */
+import { Transaction } from '@mysten/sui/transactions';
+import type { SuiClient } from '@mysten/sui/client';
+import type { IHnswService } from '../vector/IHnswService';
+export interface ClientMemoryManagerConfig {
+    packageId: string;
+    accessRegistryId: string;
+    walrusAggregator: string;
+    geminiApiKey: string;
+    sealServerObjectIds?: string[];
+    walrusNetwork?: 'testnet' | 'mainnet';
+    categories?: string[];
+    /** Enable local browser indexing for vector search (default: true) */
+    enableLocalIndexing?: boolean;
+    /** Pre-initialized HNSW service instance (shared singleton) */
+    hnswService?: IHnswService;
+    /** Enable SEAL encryption for memory content (default: true) */
+    enableEncryption?: boolean;
+}
+export interface CreateMemoryOptions {
+    content: string;
+    category?: string;
+    account: {
+        address: string;
+    };
+    signAndExecute: (params: {
+        transaction: Transaction;
+    }, callbacks: {
+        onSuccess: (result: any) => void;
+        onError: (error: Error) => void;
+    }) => void;
+    client: SuiClient;
+    onProgress?: (status: string) => void;
+}
+export interface RetrieveMemoryOptions {
+    blobId: string;
+    account: {
+        address: string;
+    };
+    signPersonalMessage: (params: {
+        message: Uint8Array;
+    }) => Promise<{
+        signature: string;
+    }>;
+    client: SuiClient;
+    onProgress?: (status: string) => void;
+}
+export interface BatchRetrieveMemoriesOptions {
+    blobIds: string[];
+    account: {
+        address: string;
+    };
+    signPersonalMessage: (params: {
+        message: Uint8Array;
+    }) => Promise<{
+        signature: string;
+    }>;
+    client: SuiClient;
+    onProgress?: (status: string, current: number, total: number) => void;
+}
+export interface BatchRetrieveResult {
+    blobId: string;
+    content?: string;
+    error?: string;
+}
+export interface ClientMemoryMetadata {
+    content: string;
+    embedding: number[];
+    timestamp: number;
+}
+/**
+ * Rich metadata structure aligned with on-chain MemoryMetadata
+ * This is extracted during AI analysis and used for:
+ * 1. Metadata-based vector embeddings
+ * 2. On-chain registration
+ * 3. Display in UI
+ */
+export interface RichMetadataAnalysis {
+    category: string;
+    topic: string;
+    importance: number;
+    summary: string;
+}
+/**
+ * Client-side memory manager for React dApps
+ */
+export declare class ClientMemoryManager {
+    private readonly config;
+    private readonly defaultCategories;
+    private embeddingService?;
+    private geminiAIService?;
+    private hnswService;
+    private hnswServicePromise;
+    constructor(config: ClientMemoryManagerConfig);
+    /**
+     * Initialize HNSW service using factory (async)
+     */
+    private initializeHnswService;
+    /**
+     * Get HNSW service (waits for initialization if needed)
+     */
+    private getHnswService;
+    private vectorIdCounters;
+    /**
+     * Get next sequential vector ID for a user (fits in 32-bit unsigned int)
+     * Uses IndexedDB in browser, in-memory counter in Node.js
+     */
+    private getNextVectorId;
+    /**
+     * Create a new memory (3 signatures: Walrus register, certify, on-chain)
+     */
+    createMemory(options: CreateMemoryOptions): Promise<string>;
+    /**
+     * Retrieve and decrypt a memory
+     */
+    retrieveMemory(options: RetrieveMemoryOptions): Promise<ClientMemoryMetadata>;
+    /**
+     * Batch retrieve and decrypt multiple memories with a single signature
+     * This is much more efficient than calling retrieveMemory multiple times
+     */
+    batchRetrieveMemories(options: BatchRetrieveMemoriesOptions): Promise<BatchRetrieveResult[]>;
+    private analyzeContent;
+    private getFallbackAnalysis;
+    /**
+     * Extract topic from content as fallback (when AI fails)
+     * Tries to get first sentence, or first 50 characters
+     *
+     * @param text - Content text to extract topic from
+     * @returns Topic string (max 100 characters)
+     */
+    private extractTopicFromContent;
+    /**
+     * Build embeddable metadata text from rich metadata
+     * Format optimized for semantic embedding and alignment with on-chain metadata
+     *
+     * @param metadata - Rich metadata extracted from AI analysis
+     * @returns Formatted text string ready for embedding
+     *
+     * @example
+     * ```typescript
+     * const metadataText = buildMetadataText({
+     *   category: 'work',
+     *   topic: 'Q4 project deadline meeting',
+     *   importance: 7,
+     *   summary: 'Team discussion about Q4 deadlines'
+     * });
+     * // Returns:
+     * // "category: work
+     * //  topic: Q4 project deadline meeting
+     * //  importance: 7
+     * //  summary: Team discussion about Q4 deadlines"
+     * ```
+     */
+    private buildMetadataText;
+    private generateEmbedding;
+    private encryptWithSEAL;
+    private uploadToWalrus;
+    private registerOnChain;
+    private fetchFromWalrus;
+    /**
+     * Create a reusable decryption session (requires one signature)
+     * This session can be used to decrypt multiple memories without additional signatures
+     */
+    private createDecryptionSession;
+    private decryptWithSEAL;
+}
+export default ClientMemoryManager;
+//# sourceMappingURL=ClientMemoryManager.d.ts.map

package/dist/client/ClientMemoryManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClientMemoryManager.d.ts","sourceRoot":"","sources":["../../src/client/ClientMemoryManager.ts"],"names":[],"mappings":"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"}