@claude-flow/memory 3.0.0-alpha.1 → 3.0.0-alpha.10

package/examples/agentdb-example.ts

@@ -1,345 +0,0 @@
-/**
- * AgentDB Backend Example
- *
- * Demonstrates agentdb@2.0.0-alpha.3.4 integration with V3 memory system
- */
-
-import { AgentDBBackend, HybridBackend, createDefaultEntry } from '../src/index.js';
-
-// ===== Example 1: Basic AgentDBBackend Usage =====
-
-async function basicExample() {
-  console.log('\n=== Basic AgentDBBackend Example ===\n');
-
-  // Initialize backend
-  const backend = new AgentDBBackend({
-    dbPath: ':memory:',
-    namespace: 'demo',
-    vectorDimension: 384, // Using MiniLM embeddings
-    hnswM: 16,
-    hnswEfConstruction: 200,
-  });
-
-  await backend.initialize();
-
-  // Check if AgentDB is available
-  if (backend.isAvailable()) {
-    console.log('✓ AgentDB available with HNSW indexing');
-  } else {
-    console.log('⚠ AgentDB not available, using fallback');
-  }
-
-  // Store some entries
-  const entries = [
-    createDefaultEntry({
-      key: 'auth-oauth',
-      content: 'OAuth 2.0 authentication flow with refresh tokens',
-      tags: ['auth', 'oauth', 'security'],
-    }),
-    createDefaultEntry({
-      key: 'auth-jwt',
-      content: 'JWT token-based authentication for REST APIs',
-      tags: ['auth', 'jwt', 'api'],
-    }),
-    createDefaultEntry({
-      key: 'auth-session',
-      content: 'Session-based authentication with cookies',
-      tags: ['auth', 'session', 'cookies'],
-    }),
-  ];
-
-  console.log('Storing entries...');
-  for (const entry of entries) {
-    await backend.store(entry);
-  }
-
-  // Query by exact key
-  console.log('\n--- Exact Key Query ---');
-  const oauth = await backend.getByKey('demo', 'auth-oauth');
-  console.log('Found:', oauth?.content);
-
-  // Query by prefix
-  console.log('\n--- Prefix Query ---');
-  const authEntries = await backend.query({
-    type: 'prefix',
-    keyPrefix: 'auth-',
-    limit: 10,
-  });
-  console.log(`Found ${authEntries.length} entries with prefix 'auth-'`);
-
-  // Query by tags
-  console.log('\n--- Tag Query ---');
-  const jwtEntries = await backend.query({
-    type: 'tag',
-    tags: ['jwt'],
-    limit: 10,
-  });
-  console.log(`Found ${jwtEntries.length} entries with tag 'jwt'`);
-
-  // Get statistics
-  console.log('\n--- Statistics ---');
-  const stats = await backend.getStats();
-  console.log('Total entries:', stats.totalEntries);
-  console.log('Avg query time:', stats.avgQueryTime.toFixed(2), 'ms');
-  console.log('Memory usage:', (stats.memoryUsage / 1024).toFixed(2), 'KB');
-
-  if (stats.hnswStats) {
-    console.log('HNSW vectors:', stats.hnswStats.vectorCount);
-    console.log('HNSW avg search:', stats.hnswStats.avgSearchTime.toFixed(2), 'ms');
-  }
-
-  // Health check
-  console.log('\n--- Health Check ---');
-  const health = await backend.healthCheck();
-  console.log('Status:', health.status);
-  console.log('Storage:', health.components.storage.status);
-  console.log('Index:', health.components.index.status);
-
-  await backend.shutdown();
-  console.log('\n✓ Backend shutdown complete');
-}
-
-// ===== Example 2: Hybrid Backend (SQLite + AgentDB) =====
-
-async function hybridExample() {
-  console.log('\n=== Hybrid Backend Example ===\n');
-
-  // Simulated embedding function (normally would use real embeddings)
-  const mockEmbedding = async (text: string): Promise<Float32Array> => {
-    const hash = Array.from(text).reduce((acc, char) => acc + char.charCodeAt(0), 0);
-    const dim = 384;
-    const result = new Float32Array(dim);
-    for (let i = 0; i < dim; i++) {
-      result[i] = Math.sin((hash + i) * 0.1);
-    }
-    return result;
-  };
-
-  const hybrid = new HybridBackend({
-    sqlite: {
-      dbPath: ':memory:',
-    },
-    agentdb: {
-      dbPath: ':memory:',
-      vectorDimension: 384,
-      hnswM: 16,
-    },
-    embeddingGenerator: mockEmbedding,
-    dualWrite: true,
-  });
-
-  await hybrid.initialize();
-
-  console.log('✓ Hybrid backend initialized (SQLite + AgentDB)');
-
-  // Store entries with embeddings
-  console.log('\nStoring entries with embeddings...');
-  const techEntries = [
-    createDefaultEntry({
-      key: 'pattern-singleton',
-      content: 'Singleton design pattern ensures only one instance exists',
-      namespace: 'patterns',
-      tags: ['design-pattern', 'creational'],
-    }),
-    createDefaultEntry({
-      key: 'pattern-factory',
-      content: 'Factory pattern creates objects without specifying exact classes',
-      namespace: 'patterns',
-      tags: ['design-pattern', 'creational'],
-    }),
-    createDefaultEntry({
-      key: 'pattern-observer',
-      content: 'Observer pattern defines one-to-many dependency between objects',
-      namespace: 'patterns',
-      tags: ['design-pattern', 'behavioral'],
-    }),
-  ];
-
-  for (const entry of techEntries) {
-    await hybrid.store(entry);
-  }
-
-  // Structured query (goes to SQLite)
-  console.log('\n--- Structured Query (SQLite) ---');
-  const structured = await hybrid.queryStructured({
-    namespace: 'patterns',
-    type: 'episodic',
-    limit: 10,
-  });
-  console.log(`Found ${structured.length} entries in 'patterns' namespace`);
-
-  // Semantic query (goes to AgentDB)
-  console.log('\n--- Semantic Query (AgentDB HNSW) ---');
-  const semantic = await hybrid.querySemantic({
-    content: 'object creation patterns',
-    k: 5,
-    threshold: 0.5,
-  });
-  console.log(`Found ${semantic.length} semantically similar entries`);
-  semantic.forEach((entry, i) => {
-    console.log(`  ${i + 1}. ${entry.key}: ${entry.content.substring(0, 60)}...`);
-  });
-
-  // Hybrid query (combines both)
-  console.log('\n--- Hybrid Query (Both Backends) ---');
-  const hybridResults = await hybrid.queryHybrid({
-    semantic: {
-      content: 'design patterns for object creation',
-      k: 10,
-      threshold: 0.3,
-    },
-    structured: {
-      namespace: 'patterns',
-    },
-    combineStrategy: 'semantic-first',
-  });
-  console.log(`Found ${hybridResults.length} entries (hybrid query)`);
-
-  // Statistics from both backends
-  console.log('\n--- Hybrid Statistics ---');
-  const hybridStats = await hybrid.getStats();
-  console.log('Total entries:', hybridStats.totalEntries);
-  console.log('Entries by namespace:', hybridStats.entriesByNamespace);
-  console.log('SQLite queries:', (hybrid as any).stats.sqliteQueries);
-  console.log('AgentDB queries:', (hybrid as any).stats.agentdbQueries);
-  console.log('Hybrid queries:', (hybrid as any).stats.hybridQueries);
-
-  await hybrid.shutdown();
-  console.log('\n✓ Hybrid backend shutdown complete');
-}
-
-// ===== Example 3: Vector Search Performance =====
-
-async function vectorSearchExample() {
-  console.log('\n=== Vector Search Performance Example ===\n');
-
-  const backend = new AgentDBBackend({
-    dbPath: ':memory:',
-    vectorDimension: 128, // Smaller for demo
-    hnswM: 16,
-    hnswEfConstruction: 100,
-    hnswEfSearch: 50,
-  });
-
-  await backend.initialize();
-
-  // Generate mock embeddings
-  const generateEmbedding = (seed: number): Float32Array => {
-    const embedding = new Float32Array(128);
-    for (let i = 0; i < 128; i++) {
-      embedding[i] = Math.sin((seed + i) * 0.1) * Math.cos(seed * 0.05);
-    }
-    return embedding;
-  };
-
-  // Insert many vectors
-  console.log('Inserting 1000 vectors...');
-  const startInsert = performance.now();
-
-  for (let i = 0; i < 1000; i++) {
-    const entry = createDefaultEntry({
-      key: `vector-${i}`,
-      content: `Content for vector ${i}`,
-      namespace: 'vectors',
-    });
-    entry.embedding = generateEmbedding(i);
-    await backend.store(entry);
-  }
-
-  const insertTime = performance.now() - startInsert;
-  console.log(`Inserted 1000 vectors in ${insertTime.toFixed(2)}ms`);
-
-  // Perform searches
-  console.log('\nPerforming 100 searches...');
-  const queryEmbedding = generateEmbedding(42);
-
-  const startSearch = performance.now();
-
-  for (let i = 0; i < 100; i++) {
-    await backend.search(queryEmbedding, { k: 10 });
-  }
-
-  const searchTime = performance.now() - startSearch;
-  console.log(`100 searches in ${searchTime.toFixed(2)}ms`);
-  console.log(`Avg per search: ${(searchTime / 100).toFixed(2)}ms`);
-
-  // Get final statistics
-  const stats = await backend.getStats();
-  console.log('\n--- Final Statistics ---');
-  console.log('Total searches:', stats.avgSearchTime > 0 ? 'Yes' : 'No');
-  console.log('Memory usage:', (stats.memoryUsage / 1024 / 1024).toFixed(2), 'MB');
-
-  await backend.shutdown();
-  console.log('\n✓ Performance test complete');
-}
-
-// ===== Example 4: Graceful Degradation =====
-
-async function gracefulDegradationExample() {
-  console.log('\n=== Graceful Degradation Example ===\n');
-
-  // Create backend that might not have agentdb
-  const backend = new AgentDBBackend({
-    dbPath: ':memory:',
-  });
-
-  await backend.initialize();
-
-  // Check availability
-  if (backend.isAvailable()) {
-    console.log('✓ AgentDB available - using HNSW indexing');
-  } else {
-    console.log('⚠ AgentDB not available - using fallback in-memory storage');
-    console.log('  (Install: npm install agentdb@2.0.0-alpha.3.4)');
-  }
-
-  // Store entries (works either way)
-  const entry = createDefaultEntry({
-    key: 'test',
-    content: 'Test content',
-  });
-  entry.embedding = new Float32Array([0.1, 0.2, 0.3, 0.4]);
-
-  await backend.store(entry);
-
-  // Search (falls back to brute-force if needed)
-  const results = await backend.search(new Float32Array([0.1, 0.2, 0.3, 0.4]), {
-    k: 5,
-  });
-
-  console.log(`Search found ${results.length} results`);
-  console.log('Fallback behavior: ', backend.isAvailable() ? 'HNSW' : 'Brute-force');
-
-  await backend.shutdown();
-  console.log('\n✓ Graceful degradation demonstrated');
-}
-
-// ===== Run All Examples =====
-
-async function main() {
-  console.log('╔═══════════════════════════════════════════════════════════╗');
-  console.log('║  AgentDB Integration Examples                             ║');
-  console.log('║  V3 Memory Module with agentdb@2.0.0-alpha.3.4            ║');
-  console.log('╚═══════════════════════════════════════════════════════════╝');
-
-  try {
-    await basicExample();
-    await hybridExample();
-    await vectorSearchExample();
-    await gracefulDegradationExample();
-
-    console.log('\n╔═══════════════════════════════════════════════════════════╗');
-    console.log('║  All examples completed successfully!                     ║');
-    console.log('╚═══════════════════════════════════════════════════════════╝\n');
-  } catch (error) {
-    console.error('\n❌ Error running examples:', error);
-    process.exit(1);
-  }
-}
-
-// Run if called directly
-if (import.meta.url === `file://${process.argv[1]}`) {
-  main();
-}
-
-export { basicExample, hybridExample, vectorSearchExample, gracefulDegradationExample };

package/examples/cross-platform-usage.ts

@@ -1,326 +0,0 @@
-/**
- * Cross-Platform Database Usage Examples
- *
- * Demonstrates how to use the database provider for Windows, macOS, and Linux
- */
-
-import {
-  createDatabase,
-  getPlatformInfo,
-  getAvailableProviders,
-  createDefaultEntry,
-} from '../src/index.js';
-
-/**
- * Example 1: Automatic Platform Detection
- */
-async function automaticProviderSelection() {
-  console.log('=== Automatic Provider Selection ===\n');
-
-  // Get platform information
-  const platformInfo = getPlatformInfo();
-  console.log('Platform Information:');
-  console.log(`  OS: ${platformInfo.os}`);
-  console.log(`  Windows: ${platformInfo.isWindows}`);
-  console.log(`  macOS: ${platformInfo.isMacOS}`);
-  console.log(`  Linux: ${platformInfo.isLinux}`);
-  console.log(`  Recommended: ${platformInfo.recommendedProvider}\n`);
-
-  // Check available providers
-  const available = await getAvailableProviders();
-  console.log('Available Providers:');
-  console.log(`  better-sqlite3: ${available.betterSqlite3 ? '✓' : '✗'}`);
-  console.log(`  sql.js: ${available.sqlJs ? '✓' : '✗'}`);
-  console.log(`  JSON: ${available.json ? '✓' : '✗'}\n`);
-
-  // Create database with automatic provider selection
-  const db = await createDatabase('./data/auto-memory.db');
-  console.log('✓ Database created with automatic provider selection\n');
-
-  // Store some test data
-  const entry = createDefaultEntry({
-    key: 'platform-test',
-    content: `Running on ${platformInfo.os}`,
-    namespace: 'platform',
-    tags: [platformInfo.os],
-  });
-
-  await db.store(entry);
-  console.log('✓ Test entry stored');
-
-  // Retrieve and verify
-  const retrieved = await db.get(entry.id);
-  console.log('✓ Entry retrieved:', retrieved?.content);
-
-  await db.shutdown();
-  console.log('✓ Database shutdown\n');
-}
-
-/**
- * Example 2: Windows-Specific Configuration
- */
-async function windowsConfiguration() {
-  console.log('=== Windows-Specific Configuration ===\n');
-
-  // On Windows, use sql.js for maximum compatibility
-  const db = await createDatabase('./data/windows-memory.db', {
-    provider: 'sql.js',
-    verbose: true,
-    autoPersistInterval: 10000, // Persist every 10 seconds
-  });
-
-  console.log('✓ Windows-compatible database created\n');
-
-  // Store data
-  const entries = [
-    createDefaultEntry({
-      key: 'windows-app-1',
-      content: 'Windows application data',
-      namespace: 'apps',
-      tags: ['windows', 'production'],
-    }),
-    createDefaultEntry({
-      key: 'windows-app-2',
-      content: 'More Windows data',
-      namespace: 'apps',
-      tags: ['windows', 'staging'],
-    }),
-  ];
-
-  await db.bulkInsert(entries);
-  console.log('✓ Bulk inserted 2 entries');
-
-  // Query by namespace
-  const results = await db.query({
-    type: 'hybrid',
-    namespace: 'apps',
-    limit: 10,
-  });
-
-  console.log(`✓ Found ${results.length} entries in 'apps' namespace`);
-
-  await db.shutdown();
-  console.log('✓ Database shutdown (changes persisted to disk)\n');
-}
-
-/**
- * Example 3: macOS/Linux Native SQLite
- */
-async function unixConfiguration() {
-  console.log('=== macOS/Linux Native SQLite ===\n');
-
-  // On Unix systems, use better-sqlite3 for best performance
-  const available = await getAvailableProviders();
-
-  if (!available.betterSqlite3) {
-    console.log('⚠ better-sqlite3 not available, falling back to sql.js\n');
-  }
-
-  const db = await createDatabase('./data/unix-memory.db', {
-    provider: available.betterSqlite3 ? 'better-sqlite3' : 'sql.js',
-    verbose: true,
-    walMode: true, // Enable WAL mode for better-sqlite3
-    optimize: true,
-  });
-
-  console.log('✓ Unix-optimized database created\n');
-
-  // Store data
-  const entry = createDefaultEntry({
-    key: 'unix-service',
-    content: 'Unix service configuration',
-    namespace: 'services',
-    tags: ['unix', 'production'],
-  });
-
-  await db.store(entry);
-  console.log('✓ Entry stored');
-
-  // Health check
-  const health = await db.healthCheck();
-  console.log('✓ Health check:', health.status);
-  console.log('  Storage:', health.components.storage.status);
-  console.log('  Index:', health.components.index.status);
-  console.log('  Cache:', health.components.cache.status);
-
-  await db.shutdown();
-  console.log('✓ Database shutdown\n');
-}
-
-/**
- * Example 4: Fallback to JSON
- */
-async function jsonFallback() {
-  console.log('=== JSON Fallback Example ===\n');
-
-  // JSON backend works everywhere, no native dependencies
-  const db = await createDatabase('./data/json-memory.db', {
-    provider: 'json',
-    verbose: true,
-  });
-
-  console.log('✓ JSON database created (no native dependencies)\n');
-
-  // Store data
-  const entry = createDefaultEntry({
-    key: 'json-data',
-    content: 'This works everywhere!',
-    namespace: 'portable',
-    tags: ['cross-platform', 'json'],
-  });
-
-  await db.store(entry);
-  console.log('✓ Entry stored');
-
-  // Get statistics
-  const stats = await db.getStats();
-  console.log('✓ Statistics:', {
-    totalEntries: stats.totalEntries,
-    avgQueryTime: `${stats.avgQueryTime.toFixed(2)}ms`,
-  });
-
-  await db.shutdown();
-  console.log('✓ Database shutdown\n');
-}
-
-/**
- * Example 5: Cross-Platform Application
- */
-async function crossPlatformApp() {
-  console.log('=== Cross-Platform Application Example ===\n');
-
-  const platformInfo = getPlatformInfo();
-
-  // Use different optimizations based on platform
-  const config = platformInfo.isWindows
-    ? {
-        // Windows: sql.js with frequent persistence
-        provider: 'sql.js' as const,
-        autoPersistInterval: 5000,
-      }
-    : {
-        // Unix: better-sqlite3 with WAL mode
-        provider: 'better-sqlite3' as const,
-        walMode: true,
-      };
-
-  console.log(`Creating database for ${platformInfo.os}...`);
-  const db = await createDatabase('./data/cross-platform.db', config);
-  console.log('✓ Platform-optimized database created\n');
-
-  // Store platform-specific configuration
-  const configEntry = createDefaultEntry({
-    key: 'app-config',
-    content: JSON.stringify({
-      platform: platformInfo.os,
-      optimizations: config,
-      timestamp: Date.now(),
-    }),
-    namespace: 'config',
-    tags: ['platform', platformInfo.os],
-  });
-
-  await db.store(configEntry);
-  console.log('✓ Platform configuration stored');
-
-  // Retrieve and display
-  const retrieved = await db.getByKey('config', 'app-config');
-  if (retrieved) {
-    const data = JSON.parse(retrieved.content);
-    console.log('✓ Configuration:', JSON.stringify(data, null, 2));
-  }
-
-  await db.shutdown();
-  console.log('✓ Database shutdown\n');
-}
-
-/**
- * Example 6: Migration Between Providers
- */
-async function providerMigration() {
-  console.log('=== Provider Migration Example ===\n');
-
-  // Create source database (JSON)
-  console.log('Creating source database (JSON)...');
-  const sourceDb = await createDatabase('./data/source.db', {
-    provider: 'json',
-  });
-
-  // Add test data
-  const testData = Array.from({ length: 5 }, (_, i) =>
-    createDefaultEntry({
-      key: `migrate-${i}`,
-      content: `Migration test data ${i}`,
-      namespace: 'migration',
-      tags: ['test', 'migration'],
-    })
-  );
-
-  await sourceDb.bulkInsert(testData);
-  console.log('✓ Source database populated with 5 entries');
-
-  // Get all entries from source
-  const sourceEntries = await sourceDb.query({
-    type: 'hybrid',
-    namespace: 'migration',
-    limit: 100,
-  });
-
-  await sourceDb.shutdown();
-  console.log('✓ Source database shutdown\n');
-
-  // Create destination database (best available provider)
-  console.log('Creating destination database (auto provider)...');
-  const destDb = await createDatabase('./data/destination.db');
-
-  // Migrate data
-  await destDb.bulkInsert(sourceEntries);
-  console.log(`✓ Migrated ${sourceEntries.length} entries to destination`);
-
-  // Verify migration
-  const count = await destDb.count('migration');
-  console.log(`✓ Verified: ${count} entries in destination database`);
-
-  await destDb.shutdown();
-  console.log('✓ Destination database shutdown\n');
-}
-
-/**
- * Main execution
- */
-async function main() {
-  console.log('\n╔════════════════════════════════════════╗');
-  console.log('║  Cross-Platform Database Examples     ║');
-  console.log('╚════════════════════════════════════════╝\n');
-
-  try {
-    // Run all examples
-    await automaticProviderSelection();
-    await windowsConfiguration();
-    await unixConfiguration();
-    await jsonFallback();
-    await crossPlatformApp();
-    await providerMigration();
-
-    console.log('╔════════════════════════════════════════╗');
-    console.log('║  All examples completed successfully! ║');
-    console.log('╚════════════════════════════════════════╝\n');
-  } catch (error) {
-    console.error('Error:', error);
-    process.exit(1);
-  }
-}
-
-// Run examples if executed directly
-if (import.meta.url === `file://${process.argv[1]}`) {
-  main().catch(console.error);
-}
-
-export {
-  automaticProviderSelection,
-  windowsConfiguration,
-  unixConfiguration,
-  jsonFallback,
-  crossPlatformApp,
-  providerMigration,
-};