agentdb 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+All notable changes to AgentDB will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.1] - 2025-10-18
+
+### Added
+- WASM files now bundled in npm distribution for browser usage
+- Build script automatically copies sql.js WASM files to dist/wasm/
+- Concise CLI help system with command-specific subhelps
+- Support for `--help` and `-h` flags on all commands
+- Comprehensive command-specific help pages for 11 commands
+
+### Changed
+- Homepage updated to https://agentdb.ruv.io
+- Main help output reduced by 80% for better readability
+- Help system now hierarchical: brief main help → detailed subhelp
+- WASM loader defaults to bundled files instead of CDN
+
+### Fixed
+- Browser examples now work offline with bundled WASM
+- Plugin wizard creates files correctly in ./plugins/ directory
+- All CLI help commands now work consistently
+- Version mismatch risk eliminated between package and CDN
+
+### Technical Details
+- WASM bundle includes: sql-wasm.wasm (645KB), sql-wasm.js (48KB), debug variants
+- Total of 1.7MB WASM files included in npm package
+- Build process: `npm run build:wasm` copies files from node_modules/sql.js
+- Files array in package.json already includes dist/ (WASM files included)
+
+## [1.0.0] - 2025-10-17
+
+### Added
+- Initial release of AgentDB
+- Ultra-fast vector database built on SQLite
+- ReasoningBank integration for AI agents
+- QUIC sync support for distributed operations
+- HNSW index for fast similarity search
+- Learning plugin system with 11 algorithm templates
+- Interactive CLI wizard for plugin creation
+- MCP server for Claude Code integration
+- Browser WASM backend support
+- Native backend with better-sqlite3
+- Comprehensive benchmark suite
+- 10 browser examples for self-learning architectures
+
+### Features
+- Vector similarity search (cosine, euclidean, dot product)
+- Product quantization for reduced storage
+- Query caching for improved performance
+- Batch operations for high throughput
+- Export/import functionality (JSON, CSV)
+- Full TypeScript support with type definitions
+- Dual-mode: persistent SQLite files or in-memory
+
+### Plugins
+- Decision Transformer (recommended)
+- Q-Learning
+- SARSA
+- Actor-Critic
+- Curiosity-Driven Learning
+- Active Learning
+- Federated Learning
+- Multi-Task Learning
+- Neural Architecture Search
+- Curriculum Learning
+- Adversarial Training
+
+[1.0.1]: https://github.com/ruvnet/agentic-flow/compare/agentdb-v1.0.0...agentdb-v1.0.1
+[1.0.0]: https://github.com/ruvnet/agentic-flow/releases/tag/agentdb-v1.0.0

package/README.md

@@ -15,11 +15,11 @@ When you're building agentic systems, every millisecond, every inference, and ev
 
 ### What AgentDB delivers
 
-⚡ **Instant startup** – Memory ready in milliseconds
-🪶 **Minimal footprint** – Run in-memory or persist to disk, with zero config
-🧠 **Built-in reasoning** – Pattern storage, experience tracking, context recall
-🔄 **Live sync** – Agents share discoveries in real time using a lightweight protocol
-🌍 **Universal runtime** – Works in Node.js, browser, edge, or agent hosts
+- ⚡ **Instant startup** – Memory ready in milliseconds
+- 🪶 **Minimal footprint** – Run in-memory or persist to disk, with zero config
+- 🧠 **Built-in reasoning** – Pattern storage, experience tracking, context recall
+- 🔄 **Live sync** – Agents share discoveries in real time using a lightweight protocol
+- 🌍 **Universal runtime** – Works in Node.js, browser, edge, or agent hosts
 
 Run anywhere: **Claude Code**, **Cursor**, **GitHub Copilot**, **Node.js**, **browsers**, **edge functions**, and **distributed agent networks**.
 

package/bin/agentdb.js

@@ -26,85 +26,304 @@ const COMMANDS = {
   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();
+function showHelp(subcommand) {
+  // Show command-specific help if requested
+  if (subcommand && COMMANDS[subcommand]) {
+    showCommandHelp(subcommand);
     return;
-  } catch (error) {
-    // Fallback to basic help if compiled version not available
-    console.log(`
+  }
+
+  console.log(`
 █▀█ █▀▀ █▀▀ █▄░█ ▀█▀ █▀▄ █▄▄
 █▀█ █▄█ ██▄ █░▀█ ░█░ █▄▀ █▄█
 
-Agent Memory & Vector Database v${version}
+AgentDB v${version} - Agent Memory & Vector Database
+Website: https://agentdb.ruv.io
 
-USAGE:
-  npx agentdb [command] [options]
+USAGE
+  npx agentdb <command> [options]
+  npx agentdb <command> --help    (detailed command help)
 
-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
+CORE COMMANDS
+  init <path>       Initialize vector database
+  mcp               Start MCP server for Claude Code
   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
+  version           Show version information
 
-  # Initialize database
-  npx agentdb init ./agents.db
+PLUGIN COMMANDS
+  create-plugin     Create learning plugin (interactive wizard)
+  list-plugins      List available plugins
+  list-templates    List plugin templates
+  plugin-info       Show plugin details
+
+DATABASE COMMANDS
+  import <file>     Import vectors from file
+  export <file>     Export vectors to file
+  query <db>        Query vector database
+  stats <db>        Show database statistics
+
+QUICK START
+  npx agentdb create-plugin              # Create plugin
+  npx agentdb init ./agents.db           # Initialize DB
+  npx agentdb mcp                        # Start MCP server
+  npx agentdb benchmark                  # Run benchmarks
+
+HELP & INFO
+  npx agentdb help <command>             # Command-specific help
+  npx agentdb <command> --help           # Alternative syntax
+  npx agentdb version                    # Version info
+
+DOCUMENTATION
+  GitHub:  https://github.com/ruvnet/agentic-flow/tree/main/packages/agentdb
+  Issues:  https://github.com/ruvnet/agentic-flow/issues
+  License: MIT OR Apache-2.0
+`);
+}
 
-  # Run benchmarks
+function showCommandHelp(command) {
+  const helps = {
+    init: `
+COMMAND: init
+
+Initialize a new vector database
+
+USAGE
+  npx agentdb init <path> [options]
+
+ARGUMENTS
+  <path>            Database file path (e.g., ./vectors.db)
+
+OPTIONS
+  --dimension <n>   Vector dimension (default: 1536)
+  --preset <name>   Use preset: small, medium, large
+  --in-memory       Create in-memory database
+
+EXAMPLES
+  npx agentdb init ./vectors.db
+  npx agentdb init ./vectors.db --dimension 768
+  npx agentdb init ./vectors.db --preset large
+`,
+    mcp: `
+COMMAND: mcp
+
+Start Model Context Protocol server for Claude Code integration
+
+USAGE
+  npx agentdb mcp [options]
+
+OPTIONS
+  --port <number>   Port to listen on (default: 3000)
+  --host <string>   Host to bind to (default: localhost)
+  --log <level>     Log level: debug, info, warn, error
+
+EXAMPLES
+  npx agentdb mcp
+  npx agentdb mcp --port 3000
+  npx agentdb mcp --log debug
+
+CLAUDE DESKTOP CONFIG
+  Add to ~/.config/claude/config.json:
+  {
+    "mcpServers": {
+      "agentdb": {
+        "command": "npx",
+        "args": ["agentdb", "mcp"]
+      }
+    }
+  }
+`,
+    'create-plugin': `
+COMMAND: create-plugin
+
+Create a new learning plugin with interactive wizard
+
+USAGE
+  npx agentdb create-plugin [options]
+
+OPTIONS
+  -t, --template <name>     Use template (see list-templates)
+  -n, --name <name>         Plugin name (lowercase-hyphenated)
+  --no-customize            Skip customization (use defaults)
+  -o, --output <dir>        Output directory (default: ./plugins)
+  --force                   Overwrite existing plugin
+  --dry-run                 Preview without creating files
+
+AVAILABLE TEMPLATES
+  decision-transformer      Sequence modeling RL (recommended)
+  q-learning               Value-based learning
+  sarsa                    On-policy TD learning
+  actor-critic             Policy gradient with baseline
+
+EXAMPLES
+  npx agentdb create-plugin
+  npx agentdb create-plugin -t q-learning -n my-agent
+  npx agentdb create-plugin --dry-run
+`,
+    import: `
+COMMAND: import
+
+Import vectors from file into database
+
+USAGE
+  npx agentdb import <database> <file> [options]
+
+ARGUMENTS
+  <database>        Database path
+  <file>            Input file (JSON, CSV)
+
+OPTIONS
+  -f, --format <type>       Format: json, csv (default: json)
+  -b, --batch-size <n>      Batch size (default: 1000)
+  -v, --verbose             Verbose output
+
+EXAMPLES
+  npx agentdb import ./db.sqlite vectors.json
+  npx agentdb import ./db.sqlite data.csv -f csv -v
+`,
+    export: `
+COMMAND: export
+
+Export vectors from database to file
+
+USAGE
+  npx agentdb export <database> <file> [options]
+
+ARGUMENTS
+  <database>        Database path
+  <file>            Output file
+
+OPTIONS
+  -f, --format <type>       Format: json, csv (default: json)
+  -l, --limit <n>           Limit number of vectors
+  -v, --verbose             Verbose output
+
+EXAMPLES
+  npx agentdb export ./db.sqlite vectors.json
+  npx agentdb export ./db.sqlite data.csv -f csv -l 1000
+`,
+    query: `
+COMMAND: query
+
+Query vector database for similar vectors
+
+USAGE
+  npx agentdb query <database> <embedding> [options]
+
+ARGUMENTS
+  <database>        Database path
+  <embedding>       Vector as JSON array or space-separated
+
+OPTIONS
+  -k, --top-k <n>           Results to return (default: 5)
+  -m, --metric <name>       Metric: cosine, euclidean, dot
+  -t, --threshold <n>       Min similarity threshold
+  -f, --format <type>       Output: table, json (default: table)
+  -v, --verbose             Verbose output
+
+EXAMPLES
+  npx agentdb query ./db.sqlite "[0.1,0.2,0.3]"
+  npx agentdb query ./db.sqlite "0.1 0.2 0.3" -k 10
+`,
+    stats: `
+COMMAND: stats
+
+Show database statistics and information
+
+USAGE
+  npx agentdb stats <database> [options]
+
+ARGUMENTS
+  <database>        Database path
+
+OPTIONS
+  -d, --detailed            Show detailed statistics
+  -f, --format <type>       Output: table, json (default: table)
+
+EXAMPLES
+  npx agentdb stats ./db.sqlite
+  npx agentdb stats ./db.sqlite -d -f json
+`,
+    benchmark: `
+COMMAND: benchmark
+
+Run comprehensive performance benchmarks
+
+USAGE
+  npx agentdb benchmark [options]
+
+OPTIONS
+  --suite <name>            Suite: insertion, search, all
+  --size <n>                Dataset size (default: 10000)
+  --dimension <n>           Vector dimension (default: 1536)
+
+EXAMPLES
   npx agentdb benchmark
+  npx agentdb benchmark --suite insertion
+  npx agentdb benchmark --size 50000
+`,
+    'list-plugins': `
+COMMAND: list-plugins
+
+List all available learning plugins
+
+USAGE
+  npx agentdb list-plugins [options]
+
+OPTIONS
+  -v, --verbose             Show detailed information
+  --filter <pattern>        Filter by name pattern
+  --json                    Output as JSON
+
+EXAMPLES
+  npx agentdb list-plugins
+  npx agentdb list-plugins --verbose
+  npx agentdb list-plugins --filter "q-*"
+`,
+    'list-templates': `
+COMMAND: list-templates
+
+List all available plugin templates
+
+USAGE
+  npx agentdb list-templates [options]
+
+OPTIONS
+  -d, --detailed            Show detailed information
+  -c, --category <name>     Filter by category
+  --json                    Output as JSON
+
+EXAMPLES
+  npx agentdb list-templates
+  npx agentdb list-templates --detailed
+  npx agentdb list-templates -c reinforcement-learning
+`,
+    'plugin-info': `
+COMMAND: plugin-info
 
-  # View comprehensive help
-  npx agentdb help
+Get detailed information about a plugin
 
-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
+USAGE
+  npx agentdb plugin-info <name> [options]
 
-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
+ARGUMENTS
+  <name>            Plugin name
 
-TIP: Run 'npx agentdb help' for comprehensive help with subsections.
-     Run 'npx agentdb <command> --help' for command-specific help.
+OPTIONS
+  --json                    Output as JSON
+  --metrics                 Include performance metrics
+  --dependencies            Show dependencies
 
-LICENSE:
-  MIT OR Apache-2.0
-`);
+EXAMPLES
+  npx agentdb plugin-info my-plugin
+  npx agentdb plugin-info my-plugin --metrics
+`
+  };
+
+  if (helps[command]) {
+    console.log(helps[command]);
+  } else {
+    console.error(`No detailed help available for: ${command}`);
+    console.error(`Run: npx agentdb ${command} --help`);
   }
 }
 
@@ -467,6 +686,18 @@ function parseFlags(flags) {
 // Parse command line arguments
 const [,, command = 'help', ...args] = process.argv;
 
+// Handle --help and -h flags at root level
+if (command === '--help' || command === '-h') {
+  showHelp();
+  process.exit(0);
+}
+
+// Handle --help flag for any command
+if (args.includes('--help') || args.includes('-h')) {
+  showCommandHelp(command);
+  process.exit(0);
+}
+
 const handler = COMMANDS[command];
 if (handler) {
   // Handle async commands
@@ -480,6 +711,6 @@ if (handler) {
 } else {
   console.error(`❌ Unknown command: ${command}`);
   console.error('');
-  console.error('Run "agentdb help" for usage information');
+  console.error('Run "npx agentdb help" for usage information');
   process.exit(1);
 }