@claude-flow/memory 3.0.0-alpha.1

package/examples/agentdb-example.ts

@@ -0,0 +1,345 @@
+/**
+ * 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

@@ -0,0 +1,326 @@
+/**
+ * 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,
+};