moflo 4.0.1 → 4.0.3

package/v3/@claude-flow/memory/dist/domain/repositories/memory-repository.interface.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Memory Repository Interface - Domain Layer
+ *
+ * Defines the contract for memory persistence.
+ * Following DDD, the interface belongs to the domain layer
+ * while implementations belong to infrastructure.
+ *
+ * @module v3/memory/domain/repositories
+ */
+import { MemoryEntry, MemoryType, MemoryStatus } from '../entities/memory-entry.js';
+/**
+ * Query options for memory retrieval
+ */
+export interface MemoryQueryOptions {
+    namespace?: string;
+    type?: MemoryType;
+    status?: MemoryStatus;
+    limit?: number;
+    offset?: number;
+    orderBy?: 'createdAt' | 'updatedAt' | 'accessCount' | 'lastAccessedAt';
+    orderDirection?: 'asc' | 'desc';
+}
+/**
+ * Vector search options
+ */
+export interface VectorSearchOptions {
+    vector: Float32Array;
+    namespace?: string;
+    limit?: number;
+    threshold?: number;
+    type?: MemoryType;
+}
+/**
+ * Vector search result
+ */
+export interface VectorSearchResult {
+    entry: MemoryEntry;
+    similarity: number;
+    distance: number;
+}
+/**
+ * Bulk operation result
+ */
+export interface BulkOperationResult {
+    success: number;
+    failed: number;
+    errors: Array<{
+        id: string;
+        error: string;
+    }>;
+}
+/**
+ * Memory statistics
+ */
+export interface MemoryStatistics {
+    totalEntries: number;
+    activeEntries: number;
+    archivedEntries: number;
+    deletedEntries: number;
+    totalSize: number;
+    entriesByNamespace: Record<string, number>;
+    entriesByType: Record<MemoryType, number>;
+    averageAccessCount: number;
+    hottestEntries: string[];
+    coldestEntries: string[];
+}
+/**
+ * Memory Repository Interface
+ *
+ * Defines all operations for memory persistence.
+ * Implementations can use SQLite, AgentDB, or hybrid backends.
+ */
+export interface IMemoryRepository {
+    save(entry: MemoryEntry): Promise<void>;
+    findById(id: string): Promise<MemoryEntry | null>;
+    findByKey(namespace: string, key: string): Promise<MemoryEntry | null>;
+    findByCompositeKey(compositeKey: string): Promise<MemoryEntry | null>;
+    delete(id: string): Promise<boolean>;
+    exists(id: string): Promise<boolean>;
+    saveMany(entries: MemoryEntry[]): Promise<BulkOperationResult>;
+    findByIds(ids: string[]): Promise<MemoryEntry[]>;
+    deleteMany(ids: string[]): Promise<BulkOperationResult>;
+    findAll(options?: MemoryQueryOptions): Promise<MemoryEntry[]>;
+    findByNamespace(namespace: string, options?: Omit<MemoryQueryOptions, 'namespace'>): Promise<MemoryEntry[]>;
+    findByType(type: MemoryType, options?: Omit<MemoryQueryOptions, 'type'>): Promise<MemoryEntry[]>;
+    findByStatus(status: MemoryStatus, options?: Omit<MemoryQueryOptions, 'status'>): Promise<MemoryEntry[]>;
+    searchByVector(options: VectorSearchOptions): Promise<VectorSearchResult[]>;
+    findSimilar(entryId: string, limit?: number): Promise<VectorSearchResult[]>;
+    findExpired(): Promise<MemoryEntry[]>;
+    deleteExpired(): Promise<number>;
+    findCold(milliseconds: number): Promise<MemoryEntry[]>;
+    archiveCold(milliseconds: number): Promise<number>;
+    getStatistics(): Promise<MemoryStatistics>;
+    count(options?: MemoryQueryOptions): Promise<number>;
+    listNamespaces(): Promise<string[]>;
+    deleteNamespace(namespace: string): Promise<number>;
+    getNamespaceSize(namespace: string): Promise<number>;
+    initialize(): Promise<void>;
+    shutdown(): Promise<void>;
+    clear(): Promise<void>;
+}
+//# sourceMappingURL=memory-repository.interface.d.ts.map

package/v3/@claude-flow/memory/dist/domain/repositories/memory-repository.interface.js

@@ -0,0 +1,11 @@
+/**
+ * Memory Repository Interface - Domain Layer
+ *
+ * Defines the contract for memory persistence.
+ * Following DDD, the interface belongs to the domain layer
+ * while implementations belong to infrastructure.
+ *
+ * @module v3/memory/domain/repositories
+ */
+export {};
+//# sourceMappingURL=memory-repository.interface.js.map

package/v3/@claude-flow/memory/dist/domain/services/memory-domain-service.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Memory Domain Service - Domain Layer
+ *
+ * Contains domain logic that doesn't naturally fit within a single entity.
+ * Coordinates between multiple memory entries and enforces domain rules.
+ *
+ * @module v3/memory/domain/services
+ */
+import { MemoryEntry, MemoryType } from '../entities/memory-entry.js';
+import { IMemoryRepository, VectorSearchResult } from '../repositories/memory-repository.interface.js';
+/**
+ * Memory consolidation strategy
+ */
+export type ConsolidationStrategy = 'merge' | 'dedupe' | 'prune' | 'summarize';
+/**
+ * Memory consolidation options
+ */
+export interface ConsolidationOptions {
+    strategy: ConsolidationStrategy;
+    namespace?: string;
+    threshold?: number;
+    maxAge?: number;
+    keepHot?: boolean;
+}
+/**
+ * Consolidation result
+ */
+export interface ConsolidationResult {
+    processed: number;
+    consolidated: number;
+    removed: number;
+    newEntries: MemoryEntry[];
+}
+/**
+ * Memory deduplication result
+ */
+export interface DeduplicationResult {
+    duplicatesFound: number;
+    duplicatesRemoved: number;
+    groupsProcessed: number;
+}
+/**
+ * Memory namespace statistics
+ */
+export interface NamespaceAnalysis {
+    namespace: string;
+    totalEntries: number;
+    activeEntries: number;
+    totalSize: number;
+    averageAccessCount: number;
+    oldestEntry: Date;
+    newestEntry: Date;
+    typeDistribution: Record<MemoryType, number>;
+}
+/**
+ * Memory Domain Service
+ *
+ * Provides domain-level operations that span multiple entities.
+ * Implements business rules for memory management.
+ */
+export declare class MemoryDomainService {
+    private readonly repository;
+    constructor(repository: IMemoryRepository);
+    /**
+     * Store a new memory with automatic type detection
+     */
+    storeWithTypeDetection(namespace: string, key: string, value: unknown, vector?: Float32Array): Promise<MemoryEntry>;
+    /**
+     * Retrieve and record access
+     */
+    retrieveWithAccessTracking(namespace: string, key: string): Promise<MemoryEntry | null>;
+    /**
+     * Search for similar memories and record access
+     */
+    searchSimilarWithTracking(vector: Float32Array, namespace?: string, limit?: number): Promise<VectorSearchResult[]>;
+    /**
+     * Consolidate memories based on strategy
+     */
+    consolidate(options: ConsolidationOptions): Promise<ConsolidationResult>;
+    /**
+     * Detect memory type based on value structure
+     */
+    private detectMemoryType;
+    /**
+     * Prune old, rarely accessed memories
+     */
+    private pruneOldMemories;
+    /**
+     * Find and remove duplicate memories
+     */
+    private deduplicateMemories;
+    /**
+     * Merge related memories into consolidated entries
+     */
+    private mergeRelatedMemories;
+    /**
+     * Merge multiple entries into one
+     */
+    private mergeEntries;
+    /**
+     * Analyze a namespace
+     */
+    analyzeNamespace(namespace: string): Promise<NamespaceAnalysis>;
+}
+//# sourceMappingURL=memory-domain-service.d.ts.map

package/v3/@claude-flow/memory/dist/domain/services/memory-domain-service.js

@@ -0,0 +1,297 @@
+/**
+ * Memory Domain Service - Domain Layer
+ *
+ * Contains domain logic that doesn't naturally fit within a single entity.
+ * Coordinates between multiple memory entries and enforces domain rules.
+ *
+ * @module v3/memory/domain/services
+ */
+import { MemoryEntry } from '../entities/memory-entry.js';
+/**
+ * Memory Domain Service
+ *
+ * Provides domain-level operations that span multiple entities.
+ * Implements business rules for memory management.
+ */
+export class MemoryDomainService {
+    repository;
+    constructor(repository) {
+        this.repository = repository;
+    }
+    /**
+     * Store a new memory with automatic type detection
+     */
+    async storeWithTypeDetection(namespace, key, value, vector) {
+        const type = this.detectMemoryType(value);
+        const entry = MemoryEntry.create({
+            namespace,
+            key,
+            value,
+            type,
+            vector,
+        });
+        await this.repository.save(entry);
+        return entry;
+    }
+    /**
+     * Retrieve and record access
+     */
+    async retrieveWithAccessTracking(namespace, key) {
+        const entry = await this.repository.findByKey(namespace, key);
+        if (entry && entry.isAccessible()) {
+            entry.recordAccess();
+            await this.repository.save(entry);
+        }
+        return entry;
+    }
+    /**
+     * Search for similar memories and record access
+     */
+    async searchSimilarWithTracking(vector, namespace, limit = 10) {
+        const results = await this.repository.searchByVector({
+            vector,
+            namespace,
+            limit,
+        });
+        // Record access for all returned entries
+        await Promise.all(results.map(async (result) => {
+            result.entry.recordAccess();
+            await this.repository.save(result.entry);
+        }));
+        return results;
+    }
+    /**
+     * Consolidate memories based on strategy
+     */
+    async consolidate(options) {
+        const entries = await this.repository.findByNamespace(options.namespace ?? 'default', { status: 'active' });
+        let result = {
+            processed: entries.length,
+            consolidated: 0,
+            removed: 0,
+            newEntries: [],
+        };
+        switch (options.strategy) {
+            case 'prune':
+                result = await this.pruneOldMemories(entries, options);
+                break;
+            case 'dedupe':
+                const dedupeResult = await this.deduplicateMemories(entries, options);
+                result.removed = dedupeResult.duplicatesRemoved;
+                break;
+            case 'merge':
+                result = await this.mergeRelatedMemories(entries, options);
+                break;
+            default:
+            // No-op for unknown strategies
+        }
+        return result;
+    }
+    /**
+     * Detect memory type based on value structure
+     */
+    detectMemoryType(value) {
+        if (typeof value === 'string') {
+            // Long text is likely semantic
+            if (value.length > 500)
+                return 'semantic';
+            // Short instructions are procedural
+            if (value.includes('->') || value.includes('then'))
+                return 'procedural';
+        }
+        if (typeof value === 'object' && value !== null) {
+            const obj = value;
+            // Objects with timestamps are episodic
+            if ('timestamp' in obj || 'when' in obj || 'date' in obj)
+                return 'episodic';
+            // Objects with steps are procedural
+            if ('steps' in obj || 'actions' in obj)
+                return 'procedural';
+        }
+        // Default to working memory for short-term storage
+        return 'working';
+    }
+    /**
+     * Prune old, rarely accessed memories
+     */
+    async pruneOldMemories(entries, options) {
+        const maxAge = options.maxAge ?? 7 * 24 * 60 * 60 * 1000; // 7 days default
+        const threshold = options.threshold ?? 5; // Minimum access count to keep
+        const now = Date.now();
+        const toRemove = [];
+        for (const entry of entries) {
+            const age = now - entry.createdAt.getTime();
+            const isOld = age > maxAge;
+            const isRarelyAccessed = entry.accessCount < threshold;
+            // Keep hot memories if requested
+            if (options.keepHot && entry.isHot())
+                continue;
+            if (isOld && isRarelyAccessed) {
+                entry.archive();
+                toRemove.push(entry.id);
+            }
+        }
+        if (toRemove.length > 0) {
+            await this.repository.deleteMany(toRemove);
+        }
+        return {
+            processed: entries.length,
+            consolidated: 0,
+            removed: toRemove.length,
+            newEntries: [],
+        };
+    }
+    /**
+     * Find and remove duplicate memories
+     */
+    async deduplicateMemories(entries, options) {
+        const threshold = options.threshold ?? 0.95; // Similarity threshold
+        const duplicates = [];
+        const processed = new Set();
+        for (let i = 0; i < entries.length; i++) {
+            if (processed.has(entries[i].id))
+                continue;
+            const entry = entries[i];
+            if (!entry.vector)
+                continue;
+            // Find similar entries
+            const similar = await this.repository.searchByVector({
+                vector: entry.vector,
+                namespace: entry.namespace,
+                limit: 10,
+                threshold,
+            });
+            // Mark duplicates (keep the one with highest access count)
+            const group = similar
+                .filter((s) => s.entry.id !== entry.id && s.similarity >= threshold)
+                .sort((a, b) => b.entry.accessCount - a.entry.accessCount);
+            for (const dup of group.slice(1)) {
+                duplicates.push(dup.entry.id);
+                processed.add(dup.entry.id);
+            }
+            processed.add(entry.id);
+        }
+        if (duplicates.length > 0) {
+            await this.repository.deleteMany(duplicates);
+        }
+        return {
+            duplicatesFound: duplicates.length,
+            duplicatesRemoved: duplicates.length,
+            groupsProcessed: processed.size,
+        };
+    }
+    /**
+     * Merge related memories into consolidated entries
+     */
+    async mergeRelatedMemories(entries, options) {
+        const threshold = options.threshold ?? 0.8;
+        const newEntries = [];
+        const toRemove = [];
+        const processed = new Set();
+        for (const entry of entries) {
+            if (processed.has(entry.id))
+                continue;
+            if (!entry.vector) {
+                processed.add(entry.id);
+                continue;
+            }
+            // Find related entries
+            const related = await this.repository.searchByVector({
+                vector: entry.vector,
+                namespace: entry.namespace,
+                limit: 5,
+                threshold,
+            });
+            if (related.length > 1) {
+                // Merge related entries
+                const merged = this.mergeEntries(related.map((r) => r.entry));
+                newEntries.push(merged);
+                for (const r of related) {
+                    toRemove.push(r.entry.id);
+                    processed.add(r.entry.id);
+                }
+            }
+            else {
+                processed.add(entry.id);
+            }
+        }
+        // Remove old entries and save merged ones
+        if (toRemove.length > 0) {
+            await this.repository.deleteMany(toRemove);
+        }
+        if (newEntries.length > 0) {
+            await this.repository.saveMany(newEntries);
+        }
+        return {
+            processed: entries.length,
+            consolidated: newEntries.length,
+            removed: toRemove.length,
+            newEntries,
+        };
+    }
+    /**
+     * Merge multiple entries into one
+     */
+    mergeEntries(entries) {
+        // Sort by access count to prioritize most accessed
+        const sorted = [...entries].sort((a, b) => b.accessCount - a.accessCount);
+        const primary = sorted[0];
+        // Combine metadata
+        const combinedMetadata = {};
+        for (const entry of entries) {
+            Object.assign(combinedMetadata, entry.metadata);
+        }
+        combinedMetadata.mergedFrom = entries.map((e) => e.id);
+        combinedMetadata.mergedAt = new Date().toISOString();
+        // Create merged entry
+        return MemoryEntry.create({
+            namespace: primary.namespace,
+            key: `merged_${Date.now()}`,
+            value: {
+                primary: primary.value,
+                related: sorted.slice(1).map((e) => e.value),
+            },
+            type: primary.type,
+            vector: primary.vector,
+            metadata: combinedMetadata,
+            accessCount: entries.reduce((sum, e) => sum + e.accessCount, 0),
+        });
+    }
+    /**
+     * Analyze a namespace
+     */
+    async analyzeNamespace(namespace) {
+        const entries = await this.repository.findByNamespace(namespace);
+        const active = entries.filter((e) => e.status === 'active');
+        const typeDistribution = {
+            semantic: 0,
+            episodic: 0,
+            procedural: 0,
+            working: 0,
+        };
+        let totalAccessCount = 0;
+        let totalSize = 0;
+        let oldestDate = new Date();
+        let newestDate = new Date(0);
+        for (const entry of entries) {
+            typeDistribution[entry.type]++;
+            totalAccessCount += entry.accessCount;
+            totalSize += JSON.stringify(entry.value).length;
+            if (entry.createdAt < oldestDate)
+                oldestDate = entry.createdAt;
+            if (entry.createdAt > newestDate)
+                newestDate = entry.createdAt;
+        }
+        return {
+            namespace,
+            totalEntries: entries.length,
+            activeEntries: active.length,
+            totalSize,
+            averageAccessCount: entries.length > 0 ? totalAccessCount / entries.length : 0,
+            oldestEntry: oldestDate,
+            newestEntry: newestDate,
+            typeDistribution,
+        };
+    }
+}
+//# sourceMappingURL=memory-domain-service.js.map

package/v3/@claude-flow/memory/dist/hnsw-index.d.ts

@@ -0,0 +1,111 @@
+/**
+ * V3 HNSW Vector Index
+ *
+ * High-performance Hierarchical Navigable Small World (HNSW) index for
+ * 150x-12,500x faster vector similarity search compared to brute force.
+ *
+ * OPTIMIZATIONS:
+ * - BinaryMinHeap/BinaryMaxHeap for O(log n) operations (vs O(n log n) Array.sort)
+ * - Pre-normalized vectors for O(1) cosine similarity (no sqrt needed)
+ * - Bounded max-heap for efficient top-k tracking
+ *
+ * @module v3/memory/hnsw-index
+ */
+import { EventEmitter } from 'node:events';
+import { HNSWConfig, HNSWStats } from './types.js';
+/**
+ * HNSW Index implementation for ultra-fast vector similarity search
+ *
+ * Performance characteristics:
+ * - Search: O(log n) approximate nearest neighbor
+ * - Insert: O(log n) amortized
+ * - Memory: O(n * M * L) where M is max connections, L is layers
+ */
+export declare class HNSWIndex extends EventEmitter {
+    private config;
+    private nodes;
+    private entryPoint;
+    private maxLevel;
+    private levelMult;
+    private stats;
+    private quantizer;
+    constructor(config?: Partial<HNSWConfig>);
+    /**
+     * Add a vector to the index
+     */
+    addPoint(id: string, vector: Float32Array): Promise<void>;
+    /**
+     * Search for k nearest neighbors
+     */
+    search(query: Float32Array, k: number, ef?: number): Promise<Array<{
+        id: string;
+        distance: number;
+    }>>;
+    /**
+     * Search with filters applied post-retrieval
+     */
+    searchWithFilters(query: Float32Array, k: number, filter: (id: string) => boolean, ef?: number): Promise<Array<{
+        id: string;
+        distance: number;
+    }>>;
+    /**
+     * Remove a point from the index
+     */
+    removePoint(id: string): Promise<boolean>;
+    /**
+     * Rebuild the index from scratch
+     */
+    rebuild(entries: Array<{
+        id: string;
+        vector: Float32Array;
+    }>): Promise<void>;
+    /**
+     * Get index statistics
+     */
+    getStats(): HNSWStats;
+    /**
+     * Clear the index
+     */
+    clear(): void;
+    /**
+     * Check if an ID exists in the index
+     */
+    has(id: string): boolean;
+    /**
+     * Get the number of vectors in the index
+     */
+    get size(): number;
+    private mergeConfig;
+    private getRandomLevel;
+    private insertNode;
+    private searchLayer;
+    /**
+     * OPTIMIZED searchLayer using heap-based priority queues
+     * Performance: O(log n) per operation vs O(n log n) for Array.sort()
+     * Expected speedup: 3-5x for large result sets
+     */
+    private searchLayerOptimized;
+    private selectNeighbors;
+    private pruneConnections;
+    private distance;
+    private cosineDistance;
+    /**
+     * OPTIMIZED: Cosine distance using pre-normalized vectors
+     * Only requires dot product (no sqrt operations)
+     * Performance: O(n) with ~2x speedup over standard cosine
+     */
+    private cosineDistanceNormalized;
+    /**
+     * Normalize a vector to unit length for O(1) cosine similarity
+     */
+    private normalizeVector;
+    /**
+     * OPTIMIZED distance calculation that uses pre-normalized vectors when available
+     */
+    private distanceOptimized;
+    private euclideanDistance;
+    private dotProductDistance;
+    private manhattanDistance;
+}
+export default HNSWIndex;
+//# sourceMappingURL=hnsw-index.d.ts.map