agentdb 1.0.0

package/bin/agentdb.js

@@ -0,0 +1,485 @@
+#!/usr/bin/env node
+
+/**
+ * AgentDB CLI
+ *
+ * Command-line interface for agentdb operations
+ */
+
+const { version } = require('../package.json');
+
+const COMMANDS = {
+  help: showHelp,
+  version: showVersion,
+  mcp: startMcpServer,
+  init: initDatabase,
+  benchmark: runBenchmark,
+  repl: startRepl,
+  'create-plugin': createPlugin,
+  'list-plugins': listPlugins,
+  'list-templates': listTemplates,
+  'plugin-info': pluginInfo,
+  'use-plugin': usePlugin,
+  import: importCommand,
+  export: exportCommand,
+  query: queryCommand,
+  stats: statsCommand,
+};
+
+function showHelp() {
+  // Try to load the comprehensive help system
+  try {
+    const helpPath = require.resolve('../dist/cli/help.js');
+    const { showComprehensiveHelp } = require(helpPath);
+    showComprehensiveHelp();
+    return;
+  } catch (error) {
+    // Fallback to basic help if compiled version not available
+    console.log(`
+█▀█ █▀▀ █▀▀ █▄░█ ▀█▀ █▀▄ █▄▄
+█▀█ █▄█ ██▄ █░▀█ ░█░ █▄▀ █▄█
+
+Agent Memory & Vector Database v${version}
+
+USAGE:
+  npx agentdb [command] [options]
+
+COMMANDS:
+  help              Show comprehensive help with subsections
+  version           Show version information
+  mcp               Start MCP server for Claude Code integration
+  init <path>       Initialize new vector database
+  benchmark         Run performance benchmarks
+  repl              Start interactive REPL (experimental)
+
+LEARNING PLUGIN COMMANDS:
+  create-plugin     Create new learning plugin with wizard
+  list-plugins      List all available plugins
+  list-templates    List available plugin templates
+  plugin-info       Get information about a plugin
+  use-plugin        Load and use a plugin
+  test-plugin       Test a plugin
+  validate-plugin   Validate plugin configuration
+
+DATABASE COMMANDS:
+  import            Import vectors from file
+  export            Export vectors to file
+  query             Query vector database
+  stats             Show database statistics
+
+ADVANCED COMMANDS:
+  optimize          Optimize database performance
+  train             Train a learning plugin
+  deploy            Deploy plugin to production
+
+QUICK START:
+  # Create a learning plugin in 2 minutes
+  npx agentdb create-plugin
+
+  # Initialize database
+  npx agentdb init ./agents.db
+
+  # Run benchmarks
+  npx agentdb benchmark
+
+  # View comprehensive help
+  npx agentdb help
+
+EXAMPLES:
+  npx agentdb create-plugin -t q-learning -n my-q
+  npx agentdb list-templates --detailed
+  npx agentdb plugin-info my-plugin
+  npx agentdb test-plugin my-plugin --coverage
+
+DOCUMENTATION:
+  GitHub: https://github.com/ruvnet/agentic-flow/tree/main/packages/agentdb
+  Issues: https://github.com/ruvnet/agentic-flow/issues
+  Author: @ruvnet (https://github.com/ruvnet)
+  Website: https://ruv.io
+  Quick Start: docs/PLUGIN_QUICKSTART.md
+  API Reference: docs/PLUGIN_API.md
+
+TIP: Run 'npx agentdb help' for comprehensive help with subsections.
+     Run 'npx agentdb <command> --help' for command-specific help.
+
+LICENSE:
+  MIT OR Apache-2.0
+`);
+  }
+}
+
+function showVersion() {
+  console.log(`agentdb v${version}`);
+  console.log(`Node: ${process.version}`);
+  console.log(`Platform: ${process.platform} ${process.arch}`);
+}
+
+async function startMcpServer() {
+  console.error('🚀 Starting AgentDB MCP Server...');
+  console.error('');
+
+  try {
+    // Check if MCP implementation exists
+    const mcpPath = require.resolve('../dist/mcp-server.js');
+
+    // Import and start the MCP server
+    const { AgentDBMCPServer } = require(mcpPath);
+    const server = new AgentDBMCPServer();
+    await server.start();
+  } catch (error) {
+    console.error('❌ Failed to start MCP server');
+    console.error('');
+    console.error('Error:', error.message);
+    console.error('');
+    console.error('Make sure to build the project first:');
+    console.error('  npm run build');
+    console.error('');
+    process.exit(1);
+  }
+}
+
+function initDatabase(path) {
+  if (!path) {
+    console.error('❌ Error: Database path required');
+    console.error('');
+    console.error('Usage: agentdb init <path>');
+    console.error('Example: agentdb init ./agents.db');
+    process.exit(1);
+  }
+
+  console.log(`📦 Initializing agent memory database: ${path}`);
+  console.log('');
+
+  try {
+    const { SqliteVectorDB, Presets } = require('../dist/index.js');
+
+    // Create a small test database
+    const config = Presets.smallDataset(1536, path);
+    const db = SqliteVectorDB.new(config);
+
+    console.log('✅ Database initialized successfully!');
+    console.log('');
+    console.log('Configuration:');
+    console.log(`  Path: ${path}`);
+    console.log(`  Dimension: 1536`);
+    console.log(`  Mode: persistent`);
+    console.log('');
+    console.log('Next steps:');
+    console.log('  1. Import the library: const { SqliteVectorDB } = require("agentdb")');
+    console.log('  2. Insert vectors: await db.insert({ data: [...], metadata: {...} })');
+    console.log('  3. Search: await db.search(queryVector, 5)');
+    console.log('');
+
+    db.close();
+  } catch (error) {
+    console.error('❌ Failed to initialize database:', error.message);
+    process.exit(1);
+  }
+}
+
+function runBenchmark() {
+  console.log('📊 Running AgentDB Performance Benchmarks...');
+  console.log('');
+  console.log('This will test:');
+  console.log('  - Native & WASM backend performance');
+  console.log('  - Insert operations (single & batch)');
+  console.log('  - Search operations (various metrics)');
+  console.log('  - Memory usage');
+  console.log('  - Backend comparison');
+  console.log('');
+
+  try {
+    // Try to run compiled benchmark first
+    const benchmarkPath = require.resolve('../dist/benchmarks/comprehensive-performance.bench.js');
+    const { PerformanceBenchmark } = require(benchmarkPath);
+
+    const benchmark = new PerformanceBenchmark();
+    benchmark.runAll()
+      .then(() => {
+        console.log('\n✅ All benchmarks completed successfully');
+        process.exit(0);
+      })
+      .catch((error) => {
+        console.error('\n❌ Benchmark failed:', error);
+        process.exit(1);
+      });
+  } catch (error) {
+    // If compiled version doesn't exist, try TypeScript version with ts-node
+    try {
+      console.error('⚠️  Compiled benchmarks not found, trying TypeScript version...');
+      console.error('');
+
+      const { spawn } = require('child_process');
+      const benchmarkProcess = spawn('npx', ['ts-node', 'benchmarks/comprehensive-performance.bench.ts'], {
+        stdio: 'inherit',
+        cwd: require('path').resolve(__dirname, '..')
+      });
+
+      benchmarkProcess.on('close', (code) => {
+        process.exit(code);
+      });
+    } catch (tsError) {
+      console.error('❌ Benchmarks not available');
+      console.error('');
+      console.error('To run benchmarks:');
+      console.error('  1. Build the project: npm run build');
+      console.error('  2. Run benchmarks: npx agentdb benchmark');
+      console.error('');
+      console.error('Or run directly:');
+      console.error('  npm run bench');
+      console.error('  npm run bench:comprehensive');
+      console.error('');
+      process.exit(1);
+    }
+  }
+}
+
+function startRepl() {
+  console.log('🔧 Interactive REPL (experimental)');
+  console.log('');
+  console.error('❌ REPL not implemented yet');
+  console.error('');
+  console.error('For now, use Node.js REPL:');
+  console.error('  node');
+  console.error('  > const { SqliteVectorDB, Presets } = require("agentdb")');
+  console.error('  > const db = await SqliteVectorDB.new(Presets.inMemory(1536))');
+  console.error('');
+  process.exit(1);
+}
+
+// Learning Plugin CLI commands
+function createPlugin(...args) {
+  try {
+    const wrapperPath = require('path').join(__dirname, 'plugin-cli-wrapper.mjs');
+    // Use the .mjs wrapper to load the ES module
+    // Prepend 'create-plugin' command since plugin-cli expects it
+    const { spawn } = require('child_process');
+    const child = spawn('node', [wrapperPath, 'create-plugin', ...args], {
+      stdio: 'inherit',
+      cwd: require('path').resolve(__dirname, '..')
+    });
+
+    child.on('close', (code) => {
+      process.exit(code);
+    });
+  } catch (error) {
+    console.error('❌ Plugin CLI not available');
+    console.error('');
+    console.error('Error:', error.message);
+    console.error('');
+    console.error('Make sure to build the project first:');
+    console.error('  npm run build');
+    console.error('');
+    process.exit(1);
+  }
+}
+
+function listPlugins(...args) {
+  // Call plugin CLI wrapper with list-plugins command
+  const wrapperPath = require('path').join(__dirname, 'plugin-cli-wrapper.mjs');
+  const { spawn } = require('child_process');
+  const child = spawn('node', [wrapperPath, 'list-plugins', ...args], {
+    stdio: 'inherit',
+    cwd: require('path').resolve(__dirname, '..')
+  });
+  child.on('close', (code) => process.exit(code));
+}
+
+function listTemplates(...args) {
+  const wrapperPath = require('path').join(__dirname, 'plugin-cli-wrapper.mjs');
+  const { spawn} = require('child_process');
+  const child = spawn('node', [wrapperPath, 'list-templates', ...args], {
+    stdio: 'inherit',
+    cwd: require('path').resolve(__dirname, '..')
+  });
+  child.on('close', (code) => process.exit(code));
+}
+
+function pluginInfo(...args) {
+  const wrapperPath = require('path').join(__dirname, 'plugin-cli-wrapper.mjs');
+  const { spawn } = require('child_process');
+  const child = spawn('node', [wrapperPath, 'plugin-info', ...args], {
+    stdio: 'inherit',
+    cwd: require('path').resolve(__dirname, '..')
+  });
+  child.on('close', (code) => process.exit(code));
+}
+
+function usePlugin(...args) {
+  const wrapperPath = require('path').join(__dirname, 'plugin-cli-wrapper.mjs');
+  const { spawn } = require('child_process');
+  const child = spawn('node', [wrapperPath, 'use-plugin', ...args], {
+    stdio: 'inherit',
+    cwd: require('path').resolve(__dirname, '..')
+  });
+  child.on('close', (code) => process.exit(code));
+}
+
+// Database commands
+function importCommand(...args) {
+  const [database, file, ...flags] = args;
+
+  if (!database || !file) {
+    console.error('❌ Usage: agentdb import <database> <file> [options]');
+    console.error('');
+    console.error('Options:');
+    console.error('  -f, --format <format>       File format (json|csv), default: json');
+    console.error('  -b, --batch-size <size>     Batch size for imports, default: 1000');
+    console.error('  -v, --verbose               Verbose output');
+    console.error('');
+    console.error('Examples:');
+    console.error('  agentdb import ./db.sqlite vectors.json');
+    console.error('  agentdb import ./db.sqlite data.csv -f csv -v');
+    process.exit(1);
+  }
+
+  try {
+    const { importVectors } = require('../dist/cli/db-commands.js');
+    const options = parseFlags(flags);
+    importVectors(database, file, options).catch(err => {
+      console.error('❌ Import failed:', err.message);
+      process.exit(1);
+    });
+  } catch (error) {
+    console.error('❌ Database commands not available. Please run: npm run build');
+    process.exit(1);
+  }
+}
+
+function exportCommand(...args) {
+  const [database, file, ...flags] = args;
+
+  if (!database || !file) {
+    console.error('❌ Usage: agentdb export <database> <file> [options]');
+    console.error('');
+    console.error('Options:');
+    console.error('  -f, --format <format>       File format (json|csv), default: json');
+    console.error('  -l, --limit <number>        Limit number of vectors');
+    console.error('  -v, --verbose               Verbose output');
+    console.error('');
+    console.error('Examples:');
+    console.error('  agentdb export ./db.sqlite vectors.json');
+    console.error('  agentdb export ./db.sqlite data.csv -f csv -l 1000');
+    process.exit(1);
+  }
+
+  try {
+    const { exportVectors } = require('../dist/cli/db-commands.js');
+    const options = parseFlags(flags);
+    exportVectors(database, file, options).catch(err => {
+      console.error('❌ Export failed:', err.message);
+      process.exit(1);
+    });
+  } catch (error) {
+    console.error('❌ Database commands not available. Please run: npm run build');
+    process.exit(1);
+  }
+}
+
+function queryCommand(...args) {
+  const [database, embedding, ...flags] = args;
+
+  if (!database || !embedding) {
+    console.error('❌ Usage: agentdb query <database> <embedding> [options]');
+    console.error('');
+    console.error('Options:');
+    console.error('  -k, --top-k <number>        Number of results, default: 5');
+    console.error('  -m, --metric <metric>       Similarity metric (cosine|euclidean|dot), default: cosine');
+    console.error('  -t, --threshold <number>    Minimum similarity threshold, default: 0.0');
+    console.error('  -f, --format <format>       Output format (table|json), default: table');
+    console.error('  -v, --verbose               Verbose output');
+    console.error('');
+    console.error('Examples:');
+    console.error('  agentdb query ./db.sqlite "[0.1,0.2,0.3]"');
+    console.error('  agentdb query ./db.sqlite "0.1 0.2 0.3" -k 10 -m euclidean');
+    process.exit(1);
+  }
+
+  try {
+    const { queryVectors } = require('../dist/cli/db-commands.js');
+    const options = parseFlags(flags);
+    queryVectors(database, embedding, options).catch(err => {
+      console.error('❌ Query failed:', err.message);
+      process.exit(1);
+    });
+  } catch (error) {
+    console.error('❌ Database commands not available. Please run: npm run build');
+    process.exit(1);
+  }
+}
+
+function statsCommand(...args) {
+  const [database, ...flags] = args;
+
+  if (!database) {
+    console.error('❌ Usage: agentdb stats <database> [options]');
+    console.error('');
+    console.error('Options:');
+    console.error('  -d, --detailed              Show detailed statistics');
+    console.error('  -f, --format <format>       Output format (table|json), default: table');
+    console.error('');
+    console.error('Examples:');
+    console.error('  agentdb stats ./db.sqlite');
+    console.error('  agentdb stats ./db.sqlite -d -f json');
+    process.exit(1);
+  }
+
+  try {
+    const { showStats } = require('../dist/cli/db-commands.js');
+    const options = parseFlags(flags);
+    showStats(database, options).catch(err => {
+      console.error('❌ Stats command failed:', err.message);
+      process.exit(1);
+    });
+  } catch (error) {
+    console.error('❌ Database commands not available. Please run: npm run build');
+    process.exit(1);
+  }
+}
+
+// Parse command line flags into options object
+function parseFlags(flags) {
+  const options = {};
+  for (let i = 0; i < flags.length; i++) {
+    const flag = flags[i];
+
+    if (flag === '-f' || flag === '--format') {
+      options.format = flags[++i];
+    } else if (flag === '-b' || flag === '--batch-size') {
+      options.batchSize = parseInt(flags[++i], 10);
+    } else if (flag === '-k' || flag === '--top-k') {
+      options.k = parseInt(flags[++i], 10);
+    } else if (flag === '-m' || flag === '--metric') {
+      options.metric = flags[++i];
+    } else if (flag === '-t' || flag === '--threshold') {
+      options.threshold = parseFloat(flags[++i]);
+    } else if (flag === '-l' || flag === '--limit') {
+      options.limit = parseInt(flags[++i], 10);
+    } else if (flag === '-d' || flag === '--detailed') {
+      options.detailed = true;
+    } else if (flag === '-v' || flag === '--verbose') {
+      options.verbose = true;
+    }
+  }
+  return options;
+}
+
+// Parse command line arguments
+const [,, command = 'help', ...args] = process.argv;
+
+const handler = COMMANDS[command];
+if (handler) {
+  // Handle async commands
+  const result = handler(...args);
+  if (result instanceof Promise) {
+    result.catch(error => {
+      console.error('Error:', error);
+      process.exit(1);
+    });
+  }
+} else {
+  console.error(`❌ Unknown command: ${command}`);
+  console.error('');
+  console.error('Run "agentdb help" for usage information');
+  process.exit(1);
+}

package/bin/plugin-cli-wrapper.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * Wrapper to load the ES module plugin CLI
+ * This file uses .mjs extension to signal ES module to Node.js
+ */
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Import the plugin CLI ES module (.mjs version)
+const cliPath = join(__dirname, '../dist/cli/plugin-cli.mjs');
+import(pathToFileURL(cliPath).href).catch(err => {
+  console.error('Failed to load plugin CLI:', err);
+  process.exit(1);
+});
+
+function pathToFileURL(path) {
+  return new URL(`file://${path.startsWith('/') ? '' : '/'}${path}`);
+}

package/dist/cache/query-cache.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Query Cache with LRU eviction for ultra-fast repeated queries
+ *
+ * Provides 50-100x speedup for repeated vector searches by caching results.
+ * Uses LRU (Least Recently Used) eviction strategy with TTL (Time To Live).
+ *
+ * @example
+ * ```typescript
+ * const cache = new QueryCache({ maxSize: 1000, ttl: 300000 }); // 5 min TTL
+ *
+ * // First query: miss, executes full search
+ * const results1 = cache.get(key) ?? performSearch();
+ * cache.set(key, results1);
+ *
+ * // Second query: hit, returns cached results (sub-millisecond)
+ * const results2 = cache.get(key); // 50-100x faster
+ * ```
+ */
+export interface QueryCacheConfig {
+    /** Maximum number of cached queries (default: 1000) */
+    maxSize: number;
+    /** Time-to-live in milliseconds (default: 300000 = 5 minutes) */
+    ttl: number;
+    /** Enable cache statistics tracking (default: true) */
+    enableStats: boolean;
+}
+export interface CacheEntry<T> {
+    results: T;
+    expiry: number;
+    lastAccessed: number;
+    accessCount: number;
+}
+export interface CacheStats {
+    hits: number;
+    misses: number;
+    hitRate: number;
+    size: number;
+    evictions: number;
+    avgAccessTime: number;
+}
+export declare class QueryCache<T = any> {
+    private cache;
+    private config;
+    private stats;
+    constructor(config?: Partial<QueryCacheConfig>);
+    /**
+     * Generate cache key from query parameters
+     */
+    static generateKey(embedding: number[], k: number, metric?: string, threshold?: number): string;
+    /**
+     * Get cached results if available and not expired
+     */
+    get(key: string): T | null;
+    /**
+     * Store results in cache with LRU eviction
+     */
+    set(key: string, results: T): void;
+    /**
+     * Evict least recently used entry
+     */
+    private evictLRU;
+    /**
+     * Clear all cached entries
+     */
+    clear(): void;
+    /**
+     * Clear expired entries
+     */
+    clearExpired(): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): CacheStats;
+    /**
+     * Reset statistics
+     */
+    resetStats(): void;
+    private recordHit;
+    private recordMiss;
+    /**
+     * Get current cache size
+     */
+    get size(): number;
+    /**
+     * Check if cache has key
+     */
+    has(key: string): boolean;
+    /**
+     * Delete specific entry
+     */
+    delete(key: string): boolean;
+    /**
+     * Get all cache keys
+     */
+    keys(): string[];
+    /**
+     * Get cache configuration
+     */
+    getConfig(): Required<QueryCacheConfig>;
+    /**
+     * Update cache configuration
+     */
+    updateConfig(config: Partial<QueryCacheConfig>): void;
+}
+//# sourceMappingURL=query-cache.d.ts.map

package/dist/cache/query-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-cache.d.ts","sourceRoot":"","sources":["../../src/cache/query-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,GAAG,EAAE,MAAM,CAAC;IACZ,uDAAuD;IACvD,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,OAAO,EAAE,CAAC,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,UAAU,CAAC,CAAC,GAAG,GAAG;IAC7B,OAAO,CAAC,KAAK,CAAyC;IACtD,OAAO,CAAC,MAAM,CAA6B;IAG3C,OAAO,CAAC,KAAK,CAMX;gBAEU,MAAM,GAAE,OAAO,CAAC,gBAAgB,CAAM;IAQlD;;OAEG;IACH,MAAM,CAAC,WAAW,CAChB,SAAS,EAAE,MAAM,EAAE,EACnB,CAAC,EAAE,MAAM,EACT,MAAM,CAAC,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM;IAMT;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI;IAyB1B;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI;IAelC;;OAEG;IACH,OAAO,CAAC,QAAQ;IAmBhB;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,YAAY,IAAI,IAAI;IAapB;;OAEG;IACH,QAAQ,IAAI,UAAU;IActB;;OAEG;IACH,UAAU,IAAI,IAAI;IAUlB,OAAO,CAAC,SAAS;IAQjB,OAAO,CAAC,UAAU;IAQlB;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAazB;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI5B;;OAEG;IACH,IAAI,IAAI,MAAM,EAAE;IAIhB;;OAEG;IACH,SAAS,IAAI,QAAQ,CAAC,gBAAgB,CAAC;IAIvC;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,IAAI;CAetD"}