@cmdoss/memwal-sdk 0.6.0

package/dist/retrieval/MemoryRetrievalService.d.ts

@@ -0,0 +1,248 @@
+/**
+ * MemoryRetrievalService - Unified Memory Retrieval & Search
+ *
+ * Consolidates all memory retrieval operations into a single, powerful service
+ * with advanced caching, decryption, analytics, and multi-dimensional search.
+ *
+ * Features:
+ * - 🔍 Vector similarity search with HNSW indexing
+ * - 📊 Semantic search with AI understanding
+ * - 🕒 Time-based and metadata filtering
+ * - 🔐 Automatic SEAL decryption pipeline
+ * - 📈 Memory analytics and relationship discovery
+ * - ⚡ Multi-tier caching for performance
+ * - 🔄 Real-time memory streaming
+ * - 📤 Export and backup capabilities
+ */
+import { EmbeddingService } from '../services/EmbeddingService';
+import { VectorManager } from '../vector/VectorManager';
+import { KnowledgeGraphManager } from '../graph/KnowledgeGraphManager';
+import { StorageManager } from '../infrastructure/walrus/StorageManager';
+import { BlockchainManager } from '../infrastructure/sui/BlockchainManager';
+import { EncryptionService } from '../services/EncryptionService';
+import { BatchManager } from '../batch/BatchManager';
+import { DecryptionConfig } from './MemoryDecryptionPipeline';
+export interface UnifiedMemoryQuery {
+    query?: string;
+    userId: string;
+    searchType?: 'vector' | 'semantic' | 'keyword' | 'hybrid' | 'graph' | 'temporal';
+    categories?: string[];
+    dateRange?: {
+        start?: Date;
+        end?: Date;
+    };
+    importanceRange?: {
+        min?: number;
+        max?: number;
+    };
+    tags?: string[];
+    contentTypes?: string[];
+    similarity?: {
+        threshold?: number;
+        k?: number;
+        efSearch?: number;
+    };
+    graphTraversal?: {
+        maxDepth?: number;
+        includeEntities?: string[];
+        excludeRelations?: string[];
+    };
+    includeContent?: boolean;
+    includeMetadata?: boolean;
+    includeEmbeddings?: boolean;
+    includeAnalytics?: boolean;
+    useCache?: boolean;
+    timeout?: number;
+    batchSize?: number;
+}
+export interface UnifiedMemoryResult {
+    id: string;
+    content?: string;
+    category: string;
+    created: Date;
+    updated?: Date;
+    similarity?: number;
+    relevanceScore: number;
+    searchRelevance: {
+        vectorSimilarity?: number;
+        semanticMatch?: number;
+        keywordMatch?: number;
+        graphRelevance?: number;
+        temporalRelevance?: number;
+    };
+    metadata: {
+        owner: string;
+        size: number;
+        importance: number;
+        tags: string[];
+        contentType: string;
+        isEncrypted: boolean;
+        accessCount?: number;
+        lastAccessed?: Date;
+    };
+    storage: {
+        blobId: string;
+        walrusHash?: string;
+        blockchainId?: string;
+        cacheStatus: 'cached' | 'retrieved' | 'not-cached';
+    };
+    relationships?: {
+        relatedMemories: string[];
+        knowledgeGraphNodes: string[];
+        semanticClusters: string[];
+    };
+    analytics?: {
+        viewCount: number;
+        shareCount: number;
+        editCount: number;
+        sentimentScore?: number;
+        topicDistribution?: Record<string, number>;
+    };
+}
+export interface RetrievalStats {
+    totalResults: number;
+    processingTime: number;
+    cacheHitRate: number;
+    searchBreakdown: {
+        vectorSearchTime: number;
+        semanticAnalysisTime: number;
+        decryptionTime: number;
+        graphTraversalTime: number;
+    };
+    dataSourcesUsed: string[];
+    qualityMetrics: {
+        averageRelevance: number;
+        diversityScore: number;
+        freshnessScore: number;
+    };
+}
+export interface RetrievalContext {
+    query: UnifiedMemoryQuery;
+    results: UnifiedMemoryResult[];
+    stats: RetrievalStats;
+    suggestions: {
+        relatedQueries: string[];
+        filterSuggestions: string[];
+        explorationPaths: string[];
+    };
+    timeline?: {
+        events: Array<{
+            date: Date;
+            type: 'created' | 'modified' | 'accessed' | 'shared';
+            memoryId: string;
+            description: string;
+        }>;
+    };
+}
+/**
+ * Unified Memory Retrieval Service
+ */
+export declare class MemoryRetrievalService {
+    private embeddingService;
+    private vectorManager;
+    private graphManager;
+    private storageManager;
+    private blockchainManager;
+    private encryptionService;
+    private batchManager;
+    private decryptionPipeline;
+    private queryCache;
+    private contentCache;
+    private analyticsCache;
+    private readonly QUERY_CACHE_TTL;
+    private readonly CONTENT_CACHE_TTL;
+    private readonly ANALYTICS_CACHE_TTL;
+    constructor(config?: {
+        embeddingService?: EmbeddingService;
+        vectorManager?: VectorManager;
+        graphManager?: KnowledgeGraphManager;
+        storageManager?: StorageManager;
+        blockchainManager?: BlockchainManager;
+        encryptionService?: EncryptionService;
+        batchManager?: BatchManager;
+        decryptionConfig?: DecryptionConfig;
+    });
+    /**
+     * Main unified search method - handles all types of memory retrieval
+     */
+    searchMemories(query: UnifiedMemoryQuery): Promise<RetrievalContext>;
+    /**
+     * Vector similarity search using HNSW index
+     */
+    private performVectorSearch;
+    /**
+     * Semantic search with AI understanding
+     */
+    private performSemanticSearch;
+    /**
+     * Knowledge graph traversal search
+     */
+    private performGraphSearch;
+    /**
+     * Temporal/time-based search
+     */
+    private performTemporalSearch;
+    /**
+     * Keyword-based search
+     */
+    private performKeywordSearch;
+    /**
+     * Hybrid search combining multiple methods
+     */
+    private performHybridSearch;
+    /**
+     * Apply filters to search results
+     */
+    private applyFilters;
+    /**
+     * Enrich results with additional data
+     */
+    private enrichResults;
+    /**
+     * Rank and sort results by relevance
+     */
+    private rankAndSortResults;
+    /**
+     * Generate comprehensive search statistics
+     */
+    private generateStats;
+    private generateCacheKey;
+    private getCachedQuery;
+    private cacheQuery;
+    private calculateCacheHitRate;
+    private getDataSourcesUsed;
+    private calculateDiversityScore;
+    private calculateFreshnessScore;
+    private convertVectorResults;
+    private analyzeQuerySemantics;
+    private calculateSemanticMatch;
+    private combineRelevanceScores;
+    private calculateTemporalRelevance;
+    private getAllUserMemories;
+    private retrieveMemoryById;
+    private loadMemoryContent;
+    private loadMemoryAnalytics;
+    private loadMemoryRelationships;
+    private generateSuggestions;
+    private generateTimeline;
+    /**
+     * Get comprehensive memory retrieval statistics
+     */
+    getRetrievalStats(): {
+        cacheStats: {
+            queries: number;
+            content: number;
+            analytics: number;
+        };
+        performanceMetrics: any;
+    };
+    /**
+     * Clear all caches
+     */
+    clearCache(): void;
+    /**
+     * Warm up caches for a user
+     */
+    warmupCache(userId: string): Promise<void>;
+}
+//# sourceMappingURL=MemoryRetrievalService.d.ts.map

package/dist/retrieval/MemoryRetrievalService.d.ts.map

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