moflo 4.0.2 → 4.0.4

package/v3/@claude-flow/memory/dist/hybrid-backend.test.js

@@ -0,0 +1,320 @@
+/**
+ * Tests for HybridBackend (ADR-009)
+ *
+ * Verifies that the hybrid backend correctly routes queries between
+ * SQLite (structured) and AgentDB (semantic) backends.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { HybridBackend } from './hybrid-backend.js';
+import { createDefaultEntry } from './types.js';
+describe('HybridBackend - ADR-009', () => {
+    let backend;
+    // Mock embedding generator for testing
+    const mockEmbedding = async (text) => {
+        // Simple mock: convert text to numbers
+        const arr = new Float32Array(128);
+        for (let i = 0; i < Math.min(text.length, 128); i++) {
+            arr[i] = text.charCodeAt(i) / 255;
+        }
+        return arr;
+    };
+    beforeEach(async () => {
+        backend = new HybridBackend({
+            sqlite: {
+                databasePath: ':memory:', // In-memory for testing
+                verbose: false,
+            },
+            agentdb: {
+                vectorDimension: 128,
+            },
+            embeddingGenerator: mockEmbedding,
+            dualWrite: true,
+        });
+        await backend.initialize();
+    });
+    afterEach(async () => {
+        await backend.shutdown();
+    });
+    describe('Initialization', () => {
+        it('should initialize both backends', async () => {
+            const health = await backend.healthCheck();
+            expect(health.status).toBe('healthy');
+            expect(health.components.storage).toBeDefined();
+            expect(health.components.index).toBeDefined();
+            expect(health.components.cache).toBeDefined();
+        });
+    });
+    describe('Store Operations', () => {
+        it('should store entries in both backends (dual-write)', async () => {
+            const entry = createDefaultEntry({
+                key: 'test-key',
+                content: 'Test content for dual write',
+                namespace: 'test',
+            });
+            await backend.store(entry);
+            // Verify in SQLite
+            const fromSQLite = await backend.getSQLiteBackend().get(entry.id);
+            expect(fromSQLite).toBeDefined();
+            expect(fromSQLite?.key).toBe('test-key');
+            // Verify in AgentDB
+            const fromAgentDB = await backend.getAgentDBBackend().get(entry.id);
+            expect(fromAgentDB).toBeDefined();
+            expect(fromAgentDB?.key).toBe('test-key');
+        });
+        it('should handle bulk inserts', async () => {
+            const entries = Array.from({ length: 10 }, (_, i) => createDefaultEntry({
+                key: `bulk-${i}`,
+                content: `Bulk content ${i}`,
+                namespace: 'bulk-test',
+            }));
+            await backend.bulkInsert(entries);
+            const count = await backend.count('bulk-test');
+            expect(count).toBe(10);
+        });
+    });
+    describe('Exact Match Queries (SQLite)', () => {
+        beforeEach(async () => {
+            // Insert test data
+            await backend.store(createDefaultEntry({
+                key: 'user-123',
+                content: 'User data for testing',
+                namespace: 'users',
+            }));
+        });
+        it('should route exact key queries to SQLite', async () => {
+            const result = await backend.getByKey('users', 'user-123');
+            expect(result).toBeDefined();
+            expect(result?.key).toBe('user-123');
+        });
+        it('should handle prefix queries via SQLite', async () => {
+            await backend.store(createDefaultEntry({
+                key: 'user-456',
+                content: 'Another user',
+                namespace: 'users',
+            }));
+            const results = await backend.queryStructured({
+                namespace: 'users',
+                keyPrefix: 'user-',
+                limit: 10,
+            });
+            expect(results.length).toBeGreaterThanOrEqual(2);
+            expect(results.every((r) => r.key.startsWith('user-'))).toBe(true);
+        });
+    });
+    describe('Semantic Search (AgentDB)', () => {
+        beforeEach(async () => {
+            // Insert test data with semantic content
+            await backend.store(createDefaultEntry({
+                key: 'doc-1',
+                content: 'Authentication and authorization patterns',
+                namespace: 'docs',
+                tags: ['security', 'auth'],
+            }));
+            await backend.store(createDefaultEntry({
+                key: 'doc-2',
+                content: 'Database optimization techniques',
+                namespace: 'docs',
+                tags: ['performance', 'database'],
+            }));
+            await backend.store(createDefaultEntry({
+                key: 'doc-3',
+                content: 'Secure authentication methods',
+                namespace: 'docs',
+                tags: ['security', 'auth'],
+            }));
+        });
+        it('should perform semantic search via AgentDB', async () => {
+            const results = await backend.querySemantic({
+                content: 'authentication security',
+                k: 5,
+                threshold: 0.1, // Low threshold for simple mock embeddings
+            });
+            expect(results.length).toBeGreaterThan(0);
+            // Should find docs about authentication
+            const hasAuthDoc = results.some((r) => r.content.includes('Authentication'));
+            expect(hasAuthDoc).toBe(true);
+        });
+        it('should support semantic search with filters', async () => {
+            const results = await backend.querySemantic({
+                content: 'security patterns',
+                k: 10,
+                filters: {
+                    type: 'semantic',
+                    tags: ['security'],
+                    limit: 10,
+                },
+            });
+            expect(results.every((r) => r.tags.includes('security'))).toBe(true);
+        });
+    });
+    describe('Hybrid Queries', () => {
+        beforeEach(async () => {
+            // Insert diverse test data
+            for (let i = 0; i < 5; i++) {
+                await backend.store(createDefaultEntry({
+                    key: `hybrid-${i}`,
+                    content: `Content about ${i % 2 === 0 ? 'authentication' : 'database'} topic ${i}`,
+                    namespace: 'hybrid-test',
+                    tags: i % 2 === 0 ? ['auth'] : ['db'],
+                }));
+            }
+        });
+        it('should combine semantic and structured queries (union)', async () => {
+            const results = await backend.queryHybrid({
+                semantic: {
+                    content: 'authentication',
+                    k: 3,
+                },
+                structured: {
+                    namespace: 'hybrid-test',
+                    keyPrefix: 'hybrid-',
+                    limit: 5,
+                },
+                combineStrategy: 'union',
+            });
+            expect(results.length).toBeGreaterThan(0);
+            expect(results.every((r) => r.namespace === 'hybrid-test')).toBe(true);
+        });
+        it('should support semantic-first strategy', async () => {
+            const results = await backend.queryHybrid({
+                semantic: {
+                    content: 'database',
+                    k: 2,
+                },
+                structured: {
+                    namespace: 'hybrid-test',
+                    limit: 3,
+                },
+                combineStrategy: 'semantic-first',
+            });
+            expect(results.length).toBeGreaterThan(0);
+            // First results should be from semantic search
+        });
+    });
+    describe('CRUD Operations', () => {
+        let testEntry;
+        beforeEach(async () => {
+            testEntry = createDefaultEntry({
+                key: 'crud-test',
+                content: 'Original content',
+                namespace: 'test',
+            });
+            await backend.store(testEntry);
+        });
+        it('should update entries in both backends', async () => {
+            const updated = await backend.update(testEntry.id, {
+                content: 'Updated content',
+                tags: ['updated'],
+            });
+            expect(updated).toBeDefined();
+            expect(updated?.content).toBe('Updated content');
+            expect(updated?.tags).toContain('updated');
+            // Verify in SQLite
+            const fromSQLite = await backend.getSQLiteBackend().get(testEntry.id);
+            expect(fromSQLite?.content).toBe('Updated content');
+            // Verify in AgentDB
+            const fromAgentDB = await backend.getAgentDBBackend().get(testEntry.id);
+            expect(fromAgentDB?.content).toBe('Updated content');
+        });
+        it('should delete entries from both backends', async () => {
+            const deleted = await backend.delete(testEntry.id);
+            expect(deleted).toBe(true);
+            const fromSQLite = await backend.getSQLiteBackend().get(testEntry.id);
+            expect(fromSQLite).toBeNull();
+            const fromAgentDB = await backend.getAgentDBBackend().get(testEntry.id);
+            expect(fromAgentDB).toBeNull();
+        });
+    });
+    describe('Namespace Operations', () => {
+        beforeEach(async () => {
+            await backend.store(createDefaultEntry({
+                key: 'ns1-key',
+                content: 'Namespace 1 content',
+                namespace: 'ns1',
+            }));
+            await backend.store(createDefaultEntry({
+                key: 'ns2-key',
+                content: 'Namespace 2 content',
+                namespace: 'ns2',
+            }));
+        });
+        it('should list all namespaces', async () => {
+            const namespaces = await backend.listNamespaces();
+            expect(namespaces).toContain('ns1');
+            expect(namespaces).toContain('ns2');
+        });
+        it('should count entries per namespace', async () => {
+            const ns1Count = await backend.count('ns1');
+            const ns2Count = await backend.count('ns2');
+            expect(ns1Count).toBe(1);
+            expect(ns2Count).toBe(1);
+        });
+        it('should clear namespace in both backends', async () => {
+            const deleted = await backend.clearNamespace('ns1');
+            expect(deleted).toBe(1);
+            const ns1Count = await backend.count('ns1');
+            expect(ns1Count).toBe(0);
+            const ns2Count = await backend.count('ns2');
+            expect(ns2Count).toBe(1);
+        });
+    });
+    describe('Statistics', () => {
+        it('should provide combined statistics', async () => {
+            // Add some test data
+            for (let i = 0; i < 5; i++) {
+                await backend.store(createDefaultEntry({
+                    key: `stats-${i}`,
+                    content: `Stats content ${i}`,
+                    namespace: 'stats',
+                }));
+            }
+            const stats = await backend.getStats();
+            expect(stats.totalEntries).toBeGreaterThanOrEqual(5);
+            expect(stats.entriesByNamespace['stats']).toBe(5);
+            expect(stats.hnswStats).toBeDefined();
+            expect(stats.cacheStats).toBeDefined();
+        });
+    });
+    describe('Health Check', () => {
+        it('should report healthy status for both backends', async () => {
+            const health = await backend.healthCheck();
+            expect(health.status).toBe('healthy');
+            expect(health.components.storage.status).toBe('healthy');
+            expect(health.components.index.status).toBe('healthy');
+            expect(health.components.cache.status).toBe('healthy');
+        });
+    });
+    describe('Query Routing', () => {
+        it('should auto-route semantic queries to AgentDB', async () => {
+            await backend.store(createDefaultEntry({
+                key: 'route-test',
+                content: 'Routing test content',
+                namespace: 'routing',
+            }));
+            const results = await backend.query({
+                type: 'semantic',
+                content: 'routing test',
+                limit: 5,
+            });
+            // Verify we got some results
+            expect(results).toBeDefined();
+        });
+        it('should auto-route exact queries to SQLite', async () => {
+            await backend.store(createDefaultEntry({
+                key: 'exact-test',
+                content: 'Exact match test',
+                namespace: 'routing',
+            }));
+            const results = await backend.query({
+                type: 'exact',
+                key: 'exact-test',
+                namespace: 'routing',
+                limit: 1,
+            });
+            // Verify we got the exact result
+            expect(results.length).toBeGreaterThan(0);
+            expect(results[0].key).toBe('exact-test');
+        });
+    });
+});
+//# sourceMappingURL=hybrid-backend.test.js.map

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

@@ -0,0 +1,207 @@
+/**
+ * @claude-flow/memory - V3 Unified Memory System
+ *
+ * Provides a unified memory interface backed by AgentDB with HNSW indexing
+ * for 150x-12,500x faster vector search compared to brute-force approaches.
+ *
+ * @module @claude-flow/memory
+ *
+ * @example
+ * ```typescript
+ * import { UnifiedMemoryService, query, QueryTemplates } from '@claude-flow/memory';
+ *
+ * // Initialize the memory service
+ * const memory = new UnifiedMemoryService({
+ *   dimensions: 1536,
+ *   cacheEnabled: true,
+ *   embeddingGenerator: async (text) => embeddings.embed(text),
+ * });
+ *
+ * await memory.initialize();
+ *
+ * // Store entries
+ * await memory.store({
+ *   key: 'auth-patterns',
+ *   content: 'OAuth 2.0 implementation patterns for secure authentication',
+ *   tags: ['auth', 'security', 'patterns'],
+ * });
+ *
+ * // Semantic search
+ * const results = await memory.semanticSearch('user authentication best practices', 5);
+ *
+ * // Query with fluent builder
+ * const entries = await memory.query(
+ *   query()
+ *     .semantic('security vulnerabilities')
+ *     .inNamespace('security')
+ *     .withTags(['critical'])
+ *     .threshold(0.8)
+ *     .limit(10)
+ *     .build()
+ * );
+ * ```
+ */
+export type { MemoryType, AccessLevel, ConsistencyLevel, DistanceMetric, MemoryEntry, MemoryEntryInput, MemoryEntryUpdate, QueryType, MemoryQuery, SearchResult, SearchOptions, HNSWConfig, HNSWStats, QuantizationConfig, IMemoryBackend, BackendStats, HealthCheckResult, ComponentHealth, CacheConfig, CacheStats, CachedEntry, MigrationSource, MigrationConfig, MigrationProgress, MigrationResult, MigrationError, MemoryEventType, MemoryEvent, MemoryEventHandler, SONAMode, LearningPattern, EmbeddingGenerator, } from './types.js';
+export { generateMemoryId, createDefaultEntry, PERFORMANCE_TARGETS, } from './types.js';
+export { AutoMemoryBridge, resolveAutoMemoryDir, findGitRoot } from './auto-memory-bridge.js';
+export type { AutoMemoryBridgeConfig, MemoryInsight, InsightCategory, SyncDirection, SyncMode, PruneStrategy, SyncResult, ImportResult, } from './auto-memory-bridge.js';
+export { LearningBridge } from './learning-bridge.js';
+export type { LearningBridgeConfig, LearningStats, ConsolidateResult, PatternMatch, } from './learning-bridge.js';
+export { RvfLearningStore } from './rvf-learning-store.js';
+export type { RvfLearningStoreConfig, PatternRecord, LoraRecord, EwcRecord, TrajectoryRecord, } from './rvf-learning-store.js';
+export { PersistentSonaCoordinator } from './persistent-sona.js';
+export type { PersistentSonaConfig } from './persistent-sona.js';
+export { RvfMigrator } from './rvf-migration.js';
+export type { RvfMigrationOptions, RvfMigrationResult } from './rvf-migration.js';
+export { MemoryGraph } from './memory-graph.js';
+export type { MemoryGraphConfig, GraphNode, GraphEdge, GraphStats, RankedResult, EdgeType, } from './memory-graph.js';
+export { resolveAgentMemoryDir, createAgentBridge, transferKnowledge, listAgentScopes, } from './agent-memory-scope.js';
+export type { AgentMemoryScope, AgentScopedConfig, TransferOptions, TransferResult, } from './agent-memory-scope.js';
+export { ControllerRegistry, INIT_LEVELS } from './controller-registry.js';
+export type { AgentDBControllerName, CLIControllerName, ControllerName, InitLevel, ControllerHealth, RegistryHealthReport, RuntimeConfig, } from './controller-registry.js';
+export { AgentDBAdapter } from './agentdb-adapter.js';
+export type { AgentDBAdapterConfig } from './agentdb-adapter.js';
+export { AgentDBBackend } from './agentdb-backend.js';
+export type { AgentDBBackendConfig } from './agentdb-backend.js';
+export type { SQLiteBackendConfig } from './sqlite-backend.js';
+export { SqlJsBackend } from './sqljs-backend.js';
+export type { SqlJsBackendConfig } from './sqljs-backend.js';
+export { HybridBackend } from './hybrid-backend.js';
+export type { HybridBackendConfig, StructuredQuery, SemanticQuery, HybridQuery, } from './hybrid-backend.js';
+export { RvfBackend } from './rvf-backend.js';
+export type { RvfBackendConfig } from './rvf-backend.js';
+export { HnswLite, cosineSimilarity } from './hnsw-lite.js';
+export type { HnswSearchResult } from './hnsw-lite.js';
+export { HNSWIndex } from './hnsw-index.js';
+export { CacheManager, TieredCacheManager } from './cache-manager.js';
+export { QueryBuilder, query, QueryTemplates } from './query-builder.js';
+export type { SortDirection, SortField } from './query-builder.js';
+export { MemoryMigrator, createMigrator, migrateMultipleSources } from './migration.js';
+export { createDatabase, getPlatformInfo, getAvailableProviders } from './database-provider.js';
+export type { DatabaseProvider, DatabaseOptions } from './database-provider.js';
+import { EventEmitter } from 'node:events';
+import { IMemoryBackend, MemoryEntry, MemoryEntryInput, MemoryEntryUpdate, MemoryQuery, SearchResult, SearchOptions, BackendStats, HealthCheckResult, EmbeddingGenerator, MigrationSource, MigrationConfig, MigrationResult } from './types.js';
+import { AgentDBAdapter, AgentDBAdapterConfig } from './agentdb-adapter.js';
+/**
+ * Configuration for UnifiedMemoryService
+ */
+export interface UnifiedMemoryServiceConfig extends Partial<AgentDBAdapterConfig> {
+    /** Enable automatic embedding generation */
+    autoEmbed?: boolean;
+    /** Default embedding dimensions */
+    dimensions?: number;
+    /** Embedding generator function */
+    embeddingGenerator?: EmbeddingGenerator;
+}
+/**
+ * Unified Memory Service
+ *
+ * High-level interface for the V3 memory system that provides:
+ * - Simple API for common operations
+ * - Automatic embedding generation
+ * - Cross-agent memory sharing
+ * - SONA integration for learning
+ * - Event-driven notifications
+ * - Performance monitoring
+ */
+export declare class UnifiedMemoryService extends EventEmitter implements IMemoryBackend {
+    private adapter;
+    private config;
+    private initialized;
+    constructor(config?: UnifiedMemoryServiceConfig);
+    initialize(): Promise<void>;
+    shutdown(): Promise<void>;
+    store(entry: MemoryEntry): Promise<void>;
+    get(id: string): Promise<MemoryEntry | null>;
+    getByKey(namespace: string, key: string): Promise<MemoryEntry | null>;
+    update(id: string, update: MemoryEntryUpdate): Promise<MemoryEntry | null>;
+    delete(id: string): Promise<boolean>;
+    query(query: MemoryQuery): Promise<MemoryEntry[]>;
+    search(embedding: Float32Array, options: SearchOptions): Promise<SearchResult[]>;
+    bulkInsert(entries: MemoryEntry[]): Promise<void>;
+    bulkDelete(ids: string[]): Promise<number>;
+    count(namespace?: string): Promise<number>;
+    listNamespaces(): Promise<string[]>;
+    clearNamespace(namespace: string): Promise<number>;
+    getStats(): Promise<BackendStats>;
+    healthCheck(): Promise<HealthCheckResult>;
+    /**
+     * Store an entry from simple input
+     */
+    storeEntry(input: MemoryEntryInput): Promise<MemoryEntry>;
+    /**
+     * Semantic search by content string
+     */
+    semanticSearch(content: string, k?: number, threshold?: number): Promise<SearchResult[]>;
+    /**
+     * Find similar entries to a given entry
+     */
+    findSimilar(id: string, k?: number): Promise<SearchResult[]>;
+    /**
+     * Get or create an entry
+     */
+    getOrCreate(namespace: string, key: string, creator: () => MemoryEntryInput | Promise<MemoryEntryInput>): Promise<MemoryEntry>;
+    /**
+     * Append content to an existing entry
+     */
+    appendContent(id: string, content: string): Promise<MemoryEntry | null>;
+    /**
+     * Add tags to an existing entry
+     */
+    addTags(id: string, tags: string[]): Promise<MemoryEntry | null>;
+    /**
+     * Remove tags from an existing entry
+     */
+    removeTags(id: string, tags: string[]): Promise<MemoryEntry | null>;
+    /**
+     * Migrate from a legacy memory source
+     */
+    migrateFrom(source: MigrationSource, sourcePath: string, options?: Partial<MigrationConfig>): Promise<MigrationResult>;
+    /**
+     * Share an entry with another agent
+     */
+    shareWith(id: string, agentId: string): Promise<MemoryEntry | null>;
+    /**
+     * Get entries shared with a specific agent
+     */
+    getSharedWith(agentId: string): Promise<MemoryEntry[]>;
+    /**
+     * Get the underlying adapter for advanced operations
+     */
+    getAdapter(): AgentDBAdapter;
+    /**
+     * Check if the service is initialized
+     */
+    isInitialized(): boolean;
+}
+/**
+ * Create a simple in-memory service (for testing)
+ */
+export declare function createInMemoryService(): UnifiedMemoryService;
+/**
+ * Create a persistent memory service
+ */
+export declare function createPersistentService(path: string): UnifiedMemoryService;
+/**
+ * Create a memory service with embedding support
+ */
+export declare function createEmbeddingService(embeddingGenerator: EmbeddingGenerator, dimensions?: number): UnifiedMemoryService;
+/**
+ * Create a hybrid memory service (SQLite + AgentDB)
+ * This is the DEFAULT recommended configuration per ADR-009
+ *
+ * @example
+ * ```typescript
+ * const memory = createHybridService('./data/memory.db', embeddingFn);
+ * await memory.initialize();
+ *
+ * // Structured queries go to SQLite
+ * const user = await memory.getByKey('users', 'john@example.com');
+ *
+ * // Semantic queries go to AgentDB
+ * const similar = await memory.semanticSearch('authentication patterns', 10);
+ * ```
+ */
+export declare function createHybridService(databasePath: string, embeddingGenerator: EmbeddingGenerator, dimensions?: number): UnifiedMemoryService;
+export default UnifiedMemoryService;
+//# sourceMappingURL=index.d.ts.map