agentdb 1.0.0

package/examples/quick-start.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+
+/**
+ * Quick Start Example
+ *
+ * Demonstrates basic usage of sqlite-vector
+ */
+
+const { SqliteVectorDB, Presets } = require('../dist/index.js');
+
+async function main() {
+  console.log('🚀 SQLiteVector Quick Start\n');
+
+  // 1. Create in-memory database
+  console.log('1️⃣ Creating in-memory database...');
+  const db = await SqliteVectorDB.new(Presets.inMemory(128));
+  console.log('   ✅ Database created\n');
+
+  // 2. Insert some vectors
+  console.log('2️⃣ Inserting vectors...');
+  const vectors = Array.from({ length: 100 }, (_, i) => ({
+    data: Array(128).fill(0).map(() => Math.random()),
+    metadata: { id: i, type: 'example' }
+  }));
+
+  const insertResult = await db.insertBatch(vectors);
+  console.log(`   ✅ Inserted ${insertResult.inserted.length} vectors in ${insertResult.totalTimeMs}ms\n`);
+
+  // 3. Search for similar vectors
+  console.log('3️⃣ Searching for similar vectors...');
+  const queryVector = Array(128).fill(0).map(() => Math.random());
+
+  const startTime = Date.now();
+  const results = await db.search({ data: queryVector }, 5, 'cosine', 0.0);
+  const searchTime = Date.now() - startTime;
+
+  console.log(`   ✅ Found ${results.length} results in ${searchTime}ms`);
+  console.log('   Top result:');
+  console.log(`     - Similarity: ${results[0].similarity.toFixed(4)}`);
+  console.log(`     - Metadata: ${JSON.stringify(results[0].metadata)}\n`);
+
+  // 4. Get statistics
+  console.log('4️⃣ Database statistics:');
+  const stats = await db.getStats();
+  console.log(`   - Total vectors: ${stats.totalVectors}`);
+  console.log(`   - Dimension: ${stats.dimension}`);
+  console.log(`   - Mode: ${stats.mode}`);
+  console.log(`   - Memory usage: ${(stats.memoryUsageBytes / 1024 / 1024).toFixed(2)} MB`);
+  console.log(`   - Avg search latency: ${stats.performance.avgSearchLatencyUs.toFixed(0)} μs\n`);
+
+  // 5. Close database
+  console.log('5️⃣ Closing database...');
+  await db.close();
+  console.log('   ✅ Database closed\n');
+
+  console.log('✨ Quick start complete!\n');
+  console.log('Next steps:');
+  console.log('  - Read the README: https://github.com/ruvnet/agentic-flow/tree/main/packages/sqlite-vector');
+  console.log('  - Try persistent storage: Presets.smallDataset(128, "./vectors.db")');
+  console.log('  - Enable QUIC sync: Presets.withQuicSync(128, "./synced.db", "127.0.0.1:4433")');
+  console.log('  - Explore ReasoningBank: Presets.withReasoningBank(128, "./reasoning.db")');
+  console.log('');
+}
+
+main().catch(error => {
+  console.error('❌ Error:', error.message);
+  process.exit(1);
+});

package/examples/wasm-example.ts

@@ -0,0 +1,222 @@
+/**
+ * Example: Using SQLiteVector with WASM backend
+ *
+ * This example demonstrates:
+ * - WASM backend initialization
+ * - Vector insertion and search
+ * - Import/Export for persistence
+ * - Performance benchmarking
+ */
+
+import { SQLiteVectorDB, BackendType, WasmBackend } from '../src/index';
+
+async function basicUsage() {
+  console.log('=== Basic WASM Backend Usage ===\n');
+
+  // Create database with WASM backend
+  const db = new SQLiteVectorDB({
+    backend: BackendType.WASM
+  });
+
+  // WASM requires async initialization
+  await db.initializeAsync();
+  console.log('✓ Database initialized');
+
+  // Insert vectors
+  const vectors = [
+    { id: 'vec1', embedding: [1.0, 0.0, 0.0], metadata: { label: 'x-axis' } },
+    { id: 'vec2', embedding: [0.0, 1.0, 0.0], metadata: { label: 'y-axis' } },
+    { id: 'vec3', embedding: [0.0, 0.0, 1.0], metadata: { label: 'z-axis' } },
+    { id: 'vec4', embedding: [0.7, 0.7, 0.0], metadata: { label: 'diagonal' } }
+  ];
+
+  const ids = db.insertBatch(vectors);
+  console.log(`✓ Inserted ${ids.length} vectors`);
+
+  // Search for similar vectors
+  const query = [1.0, 0.0, 0.0];
+  const results = db.search(query, 3, 'cosine', 0.0);
+
+  console.log('\nSearch results for [1.0, 0.0, 0.0]:');
+  results.forEach((result, i) => {
+    console.log(`  ${i + 1}. ${result.id} - Score: ${result.score.toFixed(4)} - ${result.metadata?.label}`);
+  });
+
+  // Get statistics
+  const stats = db.stats();
+  console.log(`\nDatabase stats: ${stats.count} vectors, ${(stats.size / 1024).toFixed(2)} KB`);
+
+  db.close();
+  console.log('✓ Database closed\n');
+}
+
+async function persistenceExample() {
+  console.log('=== Persistence with Import/Export ===\n');
+
+  // Create and populate database
+  const db = new SQLiteVectorDB({ backend: BackendType.WASM });
+  await db.initializeAsync();
+
+  const vectors = Array.from({ length: 100 }, (_, i) => ({
+    embedding: [Math.random(), Math.random(), Math.random()],
+    metadata: { index: i }
+  }));
+
+  db.insertBatch(vectors);
+  console.log('✓ Inserted 100 vectors');
+
+  // Export to binary
+  const binary = db.export();
+  console.log(`✓ Exported database: ${binary.byteLength} bytes`);
+
+  db.close();
+
+  // Import to new database
+  const newDb = new SQLiteVectorDB({ backend: BackendType.WASM });
+  await newDb.importAsync(binary);
+  console.log('✓ Imported database');
+
+  const stats = newDb.stats();
+  console.log(`✓ Verified: ${stats.count} vectors restored\n`);
+
+  newDb.close();
+}
+
+async function performanceBenchmark() {
+  console.log('=== Performance Benchmark ===\n');
+
+  const db = new SQLiteVectorDB({ backend: BackendType.WASM });
+  await db.initializeAsync();
+
+  // Benchmark: Batch insert
+  const insertSize = 1000;
+  const vectors = Array.from({ length: insertSize }, (_, i) => ({
+    embedding: Array.from({ length: 384 }, () => Math.random())
+  }));
+
+  const insertStart = performance.now();
+  db.insertBatch(vectors);
+  const insertDuration = performance.now() - insertStart;
+
+  console.log(`Batch Insert (${insertSize} vectors, 384-dim):`);
+  console.log(`  Total time: ${insertDuration.toFixed(2)}ms`);
+  console.log(`  Rate: ${(insertSize / (insertDuration / 1000)).toFixed(0)} vectors/sec`);
+
+  // Benchmark: Search
+  const searchIterations = 100;
+  const query = Array.from({ length: 384 }, () => Math.random());
+
+  const searchStart = performance.now();
+  for (let i = 0; i < searchIterations; i++) {
+    db.search(query, 10, 'cosine', 0.0);
+  }
+  const searchDuration = performance.now() - searchStart;
+
+  console.log(`\nSearch (${searchIterations} iterations, k=10):`);
+  console.log(`  Avg time: ${(searchDuration / searchIterations).toFixed(2)}ms`);
+  console.log(`  Rate: ${(searchIterations / (searchDuration / 1000)).toFixed(0)} searches/sec`);
+
+  // Memory usage
+  const stats = db.stats();
+  console.log(`\nMemory usage: ${(stats.size / (1024 * 1024)).toFixed(2)} MB`);
+
+  db.close();
+}
+
+async function similarityComparison() {
+  console.log('\n=== Similarity Metrics Comparison ===\n');
+
+  const db = new SQLiteVectorDB({ backend: BackendType.WASM });
+  await db.initializeAsync();
+
+  // Insert test vectors
+  const vectors = [
+    { id: 'parallel', embedding: [1.0, 1.0, 1.0] },
+    { id: 'orthogonal', embedding: [1.0, -1.0, 0.0] },
+    { id: 'opposite', embedding: [-1.0, -1.0, -1.0] },
+    { id: 'similar', embedding: [0.9, 0.9, 0.9] }
+  ];
+
+  db.insertBatch(vectors);
+
+  const query = [1.0, 1.0, 1.0];
+
+  // Compare metrics
+  console.log('Query: [1.0, 1.0, 1.0]\n');
+
+  const cosineResults = db.search(query, 4, 'cosine', 0.0);
+  console.log('Cosine Similarity:');
+  cosineResults.forEach(r => {
+    console.log(`  ${r.id.padEnd(12)} - ${r.score.toFixed(4)}`);
+  });
+
+  const euclideanResults = db.search(query, 4, 'euclidean', 0.0);
+  console.log('\nEuclidean Distance:');
+  euclideanResults.forEach(r => {
+    console.log(`  ${r.id.padEnd(12)} - ${r.score.toFixed(4)}`);
+  });
+
+  const dotResults = db.search(query, 4, 'dot', 0.0);
+  console.log('\nDot Product:');
+  dotResults.forEach(r => {
+    console.log(`  ${r.id.padEnd(12)} - ${r.score.toFixed(4)}`);
+  });
+
+  db.close();
+  console.log();
+}
+
+async function directBackendUsage() {
+  console.log('\n=== Direct WASM Backend Usage ===\n');
+
+  // Use WasmBackend directly for more control
+  const backend = new WasmBackend();
+  await backend.initializeAsync({
+    cacheSize: 50 * 1024, // 50MB cache
+    memoryMode: true
+  });
+
+  console.log('✓ WASM backend initialized');
+
+  // All operations same as unified API
+  const id = backend.insert({
+    embedding: [1, 2, 3, 4, 5],
+    metadata: { type: 'test' }
+  });
+
+  const vector = backend.get(id);
+  console.log(`✓ Retrieved vector: ${vector?.embedding.slice(0, 5)}`);
+
+  const results = backend.search([1, 2, 3, 4, 5], 1, 'cosine', 0.0);
+  console.log(`✓ Search found ${results.length} results`);
+
+  backend.close();
+  console.log('✓ Backend closed\n');
+}
+
+// Run all examples
+async function main() {
+  console.log('SQLiteVector WASM Backend Examples\n');
+  console.log('===================================\n');
+
+  try {
+    await basicUsage();
+    await persistenceExample();
+    await performanceBenchmark();
+    await similarityComparison();
+    await directBackendUsage();
+
+    console.log('===================================\n');
+    console.log('✓ All examples completed successfully!');
+  } catch (error) {
+    console.error('Error:', error);
+    process.exit(1);
+  }
+}
+
+// Run if executed directly
+if (require.main === module) {
+  main();
+}
+
+export { main };

package/package.json

@@ -0,0 +1,118 @@
+{
+  "name": "agentdb",
+  "version": "1.0.0",
+  "description": "Ultra-fast agent memory and vector database with ReasoningBank for AI agents. Built on SQLite with QUIC sync. From ruv.io - Advanced AI Infrastructure.",
+  "keywords": [
+    "agent",
+    "agentdb",
+    "agent-memory",
+    "vector",
+    "database",
+    "sqlite",
+    "embeddings",
+    "ai",
+    "wasm",
+    "quic",
+    "similarity-search",
+    "machine-learning",
+    "vector-database",
+    "semantic-search",
+    "agentic",
+    "claude",
+    "mcp",
+    "reasoning",
+    "memory",
+    "rag",
+    "ruv",
+    "ruvnet"
+  ],
+  "author": "rUv (@ruvnet) <team@agentic-flow.dev>",
+  "license": "MIT OR Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ruvnet/agentic-flow.git",
+    "directory": "packages/agentdb"
+  },
+  "bugs": {
+    "url": "https://github.com/ruvnet/agentic-flow/issues"
+  },
+  "homepage": "https://ruv.io",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "agentdb": "./bin/agentdb.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "examples",
+    "README.md",
+    "LICENSE-MIT",
+    "LICENSE-APACHE"
+  ],
+  "scripts": {
+    "prepack": "npm run build",
+    "build": "npm run build:ts",
+    "build:ts": "tsc && tsc -p tsconfig.esm.json && node scripts/build-esm.js",
+    "build:native": "echo 'Native backend uses better-sqlite3 (already built)'",
+    "build:wasm": "echo 'WASM backend uses sql.js (no compilation needed)'",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "test:wasm": "jest --testPathPattern=wasm-backend",
+    "test:native": "jest --testPathPattern=native-backend",
+    "test:backends": "jest --testPathPattern=backend",
+    "bench": "ts-node benchmarks/sync-performance.bench.ts",
+    "bench:comprehensive": "ts-node benchmarks/comprehensive-performance.bench.ts",
+    "bench:backends": "jest --testPathPattern=backend-comparison --verbose",
+    "lint": "eslint src tests --ext .ts",
+    "format": "prettier --write 'src/**/*.ts'",
+    "typecheck": "tsc --noEmit",
+    "_prepublishOnly_disabled": "npm run test && npm run build",
+    "verify": "node scripts/verify-install.js",
+    "mcp": "node bin/agentdb.js mcp"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.20.1",
+    "ajv": "^8.12.0",
+    "better-sqlite3": "^9.2.2",
+    "chalk": "^5.3.0",
+    "commander": "^11.1.0",
+    "inquirer": "^9.2.12",
+    "msgpackr": "^1.10.1",
+    "sql.js": "^1.13.0",
+    "yaml": "^2.3.4",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/inquirer": "^9.0.9",
+    "@types/jest": "^29.5.11",
+    "@types/node": "^20.10.6",
+    "@types/sql.js": "^1.4.9",
+    "@typescript-eslint/eslint-plugin": "^6.17.0",
+    "@typescript-eslint/parser": "^6.17.0",
+    "benchmark": "^2.1.4",
+    "eslint": "^8.56.0",
+    "jest": "^29.7.0",
+    "prettier": "^3.6.2",
+    "ts-jest": "^29.1.1",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}