ruvector 0.1.19 → 0.1.21

package/README.md

@@ -1,1523 +1,397 @@
-# ruvector
+# RuVector
 
-[![npm version](https://badge.fury.io/js/ruvector.svg)](https://www.npmjs.com/package/ruvector)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-[![Node Version](https://img.shields.io/node/v/ruvector)](https://nodejs.org)
-[![Downloads](https://img.shields.io/npm/dm/ruvector)](https://www.npmjs.com/package/ruvector)
-[![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg)](https://github.com/ruvnet/ruvector)
-[![Performance](https://img.shields.io/badge/latency-<0.5ms-green.svg)](https://github.com/ruvnet/ruvector)
-[![GitHub Stars](https://img.shields.io/github/stars/ruvnet/ruvector?style=social)](https://github.com/ruvnet/ruvector)
-
-**The fastest vector database for Node.js—built in Rust, runs everywhere**
-
-Ruvector is a next-generation vector database that brings **enterprise-grade semantic search** to Node.js applications. Unlike cloud-only solutions or Python-first databases, Ruvector is designed specifically for JavaScript/TypeScript developers who need **blazing-fast vector similarity search** without the complexity of external services.
-
-> 🚀 **Sub-millisecond queries** • 🎯 **52,000+ inserts/sec** • 💾 **~50 bytes per vector** • 🌍 **Runs anywhere**
-
-Built by [rUv](https://ruv.io) with production-grade Rust performance and intelligent platform detection—**automatically uses native bindings when available, falls back to WebAssembly when needed**.
-
-🌐 **[Visit ruv.io](https://ruv.io)** | 📦 **[GitHub](https://github.com/ruvnet/ruvector)** | 📚 **[Documentation](https://github.com/ruvnet/ruvector/tree/main/docs)**
-
----
-
-## 🌟 Why Ruvector?
-
-### The Problem with Existing Vector Databases
-
-Most vector databases force you to choose between three painful trade-offs:
-
-1. **Cloud-Only Services** (Pinecone, Weaviate Cloud) - Expensive, vendor lock-in, latency issues, API rate limits
-2. **Python-First Solutions** (ChromaDB, Faiss) - Poor Node.js support, require separate Python processes
-3. **Self-Hosted Complexity** (Milvus, Qdrant) - Heavy infrastructure, Docker orchestration, operational overhead
-
-**Ruvector eliminates these trade-offs.**
-
-### The Ruvector Advantage
-
-Ruvector is purpose-built for **modern JavaScript/TypeScript applications** that need vector search:
-
-🎯 **Native Node.js Integration**
-- Drop-in npm package—no Docker, no Python, no external services
-- Full TypeScript support with complete type definitions
-- Automatic platform detection with native Rust bindings
-- Seamless WebAssembly fallback for universal compatibility
+[![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![npm](https://img.shields.io/npm/v/ruvector.svg)](https://www.npmjs.com/package/ruvector)
+[![npm downloads](https://img.shields.io/npm/dm/ruvector.svg)](https://www.npmjs.com/package/ruvector)
 
-⚡ **Production-Grade Performance**
-- **52,000+ inserts/second** with native Rust (10x faster than Python alternatives)
-- **<0.5ms query latency** with HNSW indexing and SIMD optimizations
-- **~50 bytes per vector** with advanced memory optimization
-- Scales from edge devices to millions of vectors
+**A distributed vector database that learns.** Store embeddings, query with Cypher, scale horizontally, and let the index improve itself through Graph Neural Networks.
 
-🧠 **Built for AI Applications**
-- Optimized for LLM embeddings (OpenAI, Cohere, Hugging Face)
-- Perfect for RAG (Retrieval-Augmented Generation) systems
-- Agent memory and semantic caching
-- Real-time recommendation engines
+```bash
+npx ruvector
+```
 
-🌍 **Universal Deployment**
-- **Linux, macOS, Windows** with native performance
-- **Browser support** via WebAssembly (experimental)
-- **Edge computing** and serverless environments
-- **Alpine Linux** and non-glibc systems supported
+> **All-in-One Package**: The `ruvector` package includes everything — vector search, graph queries, GNN layers, distributed clustering, AI routing, and WASM support. No additional packages needed.
 
-💰 **Zero Operational Costs**
-- No cloud API fees or usage limits
-- No infrastructure to manage
-- No separate database servers
-- Open source MIT license
+## What Problem Does RuVector Solve?
 
-### Key Advantages
+Traditional vector databases just store and search. When you ask "find similar items," they return results but never get smarter.
 
-- ⚡ **Blazing Fast**: <0.5ms p50 latency with native Rust, 10-50ms with WASM fallback
-- 🎯 **Automatic Platform Detection**: Uses native when available, falls back to WASM seamlessly
-- 🧠 **AI-Native**: Built specifically for embeddings, RAG, semantic search, and agent memory
-- 🔧 **CLI Tools Included**: Full command-line interface for database management
-- 🌍 **Universal Deployment**: Works on all platforms—Linux, macOS, Windows, even browsers
-- 💾 **Memory Efficient**: ~50 bytes per vector with advanced quantization
-- 🚀 **Production Ready**: Battle-tested algorithms with comprehensive benchmarks
-- 🔓 **Open Source**: MIT licensed, community-driven
+**RuVector is different:**
 
-## 🚀 Quick Start Tutorial
+1. **Store vectors** like any vector DB (embeddings from OpenAI, Cohere, etc.)
+2. **Query with Cypher** like Neo4j (`MATCH (a)-[:SIMILAR]->(b) RETURN b`)
+3. **The index learns** — GNN layers make search results improve over time
+4. **Route AI requests** — Semantic routing and FastGRNN neural inference for LLM optimization
+5. **Compress automatically** — 2-32x memory reduction with adaptive tiered compression
+6. **Run anywhere** — Node.js, browser (WASM), or native Rust
 
-### Step 1: Installation
+## Quick Start
 
-Install Ruvector with a single npm command:
+### Installation
 
 ```bash
+# Install the package
 npm install ruvector
-```
-
-**What happens during installation:**
-- npm automatically detects your platform (Linux, macOS, Windows)
-- Downloads the correct native binary for maximum performance
-- Falls back to WebAssembly if native binaries aren't available
-- No additional setup, Docker, or external services required
 
-**Verify installation:**
-```bash
-npx ruvector info
+# Or try instantly without installing
+npx ruvector
 ```
 
-You should see your platform and implementation type (native Rust or WASM fallback).
-
-### Step 2: Your First Vector Database
-
-Let's create a simple vector database and perform basic operations. This example demonstrates the complete CRUD (Create, Read, Update, Delete) workflow:
+### Basic Usage
 
 ```javascript
-const { VectorDb } = require('ruvector');
-
-async function tutorial() {
-  // Step 2.1: Create a new vector database
-  // The 'dimensions' parameter must match your embedding model
-  // Common sizes: 128, 384 (sentence-transformers), 768 (BERT), 1536 (OpenAI)
-  const db = new VectorDb({
-    dimensions: 128,           // Vector size - MUST match your embeddings
-    maxElements: 10000,        // Maximum vectors (can grow automatically)
-    storagePath: './my-vectors.db'  // Persist to disk (omit for in-memory)
-  });
-
-  console.log('✅ Database created successfully');
-
-  // Step 2.2: Insert vectors
-  // In real applications, these would come from an embedding model
-  const documents = [
-    { id: 'doc1', text: 'Artificial intelligence and machine learning' },
-    { id: 'doc2', text: 'Deep learning neural networks' },
-    { id: 'doc3', text: 'Natural language processing' },
-  ];
-
-  for (const doc of documents) {
-    // Generate random vector for demonstration
-    // In production: use OpenAI, Cohere, or sentence-transformers
-    const vector = new Float32Array(128).map(() => Math.random());
-
-    await db.insert({
-      id: doc.id,
-      vector: vector,
-      metadata: {
-        text: doc.text,
-        timestamp: Date.now(),
-        category: 'AI'
-      }
-    });
-
-    console.log(`✅ Inserted: ${doc.id}`);
-  }
-
-  // Step 2.3: Search for similar vectors
-  // Create a query vector (in production, this would be from your search query)
-  const queryVector = new Float32Array(128).map(() => Math.random());
-
-  const results = await db.search({
-    vector: queryVector,
-    k: 5,              // Return top 5 most similar vectors
-    threshold: 0.7     // Only return results with similarity > 0.7
-  });
-
-  console.log('\n🔍 Search Results:');
-  results.forEach((result, index) => {
-    console.log(`${index + 1}. ${result.id} - Score: ${result.score.toFixed(3)}`);
-    console.log(`   Text: ${result.metadata.text}`);
-  });
-
-  // Step 2.4: Retrieve a specific vector
-  const retrieved = await db.get('doc1');
-  if (retrieved) {
-    console.log('\n📄 Retrieved document:', retrieved.metadata.text);
-  }
-
-  // Step 2.5: Get database statistics
-  const count = await db.len();
-  console.log(`\n📊 Total vectors in database: ${count}`);
-
-  // Step 2.6: Delete a vector
-  const deleted = await db.delete('doc1');
-  console.log(`\n🗑️  Deleted doc1: ${deleted ? 'Success' : 'Not found'}`);
-
-  // Final count
-  const finalCount = await db.len();
-  console.log(`📊 Final count: ${finalCount}`);
-}
+const ruvector = require('ruvector');
 
-// Run the tutorial
-tutorial().catch(console.error);
-```
-
-**Expected Output:**
-```
-✅ Database created successfully
-✅ Inserted: doc1
-✅ Inserted: doc2
-✅ Inserted: doc3
+// Create a vector database
+const db = new ruvector.VectorDB(384); // 384 dimensions
 
-🔍 Search Results:
-1. doc2 - Score: 0.892
-   Text: Deep learning neural networks
-2. doc1 - Score: 0.856
-   Text: Artificial intelligence and machine learning
-3. doc3 - Score: 0.801
-   Text: Natural language processing
+// Insert vectors with metadata
+db.insert('doc1', embedding1, { title: 'Introduction', category: 'tech' });
+db.insert('doc2', embedding2, { title: 'Advanced Topics', category: 'tech' });
 
-📄 Retrieved document: Artificial intelligence and machine learning
+// Search for similar vectors
+const results = db.search(queryEmbedding, 10);
+console.log(results); // Top 10 similar documents
 
-📊 Total vectors in database: 3
-
-🗑️  Deleted doc1: Success
-📊 Final count: 2
+// Filter by metadata
+const filtered = db.search(queryEmbedding, 10, { category: 'tech' });
 ```
 
-### Step 3: TypeScript Tutorial
+### Graph Queries (Cypher)
 
-Ruvector provides full TypeScript support with complete type safety. Here's how to use it:
+```javascript
+const { GraphDB } = require('ruvector');
 
-```typescript
-import { VectorDb, VectorEntry, SearchQuery, SearchResult } from 'ruvector';
-
-// Step 3.1: Define your custom metadata type
-interface DocumentMetadata {
-  title: string;
-  content: string;
-  author: string;
-  date: Date;
-  tags: string[];
-}
+const graph = new GraphDB();
 
-async function typescriptTutorial() {
-  // Step 3.2: Create typed database
-  const db = new VectorDb({
-    dimensions: 384,  // sentence-transformers/all-MiniLM-L6-v2
-    maxElements: 10000,
-    storagePath: './typed-vectors.db'
-  });
-
-  // Step 3.3: Type-safe vector entry
-  const entry: VectorEntry<DocumentMetadata> = {
-    id: 'article-001',
-    vector: new Float32Array(384),  // Your embedding here
-    metadata: {
-      title: 'Introduction to Vector Databases',
-      content: 'Vector databases enable semantic search...',
-      author: 'Jane Doe',
-      date: new Date('2024-01-15'),
-      tags: ['database', 'AI', 'search']
-    }
-  };
-
-  // Step 3.4: Insert with type checking
-  await db.insert(entry);
-  console.log('✅ Inserted typed document');
-
-  // Step 3.5: Type-safe search
-  const query: SearchQuery = {
-    vector: new Float32Array(384),
-    k: 10,
-    threshold: 0.8
-  };
-
-  // Step 3.6: Fully typed results
-  const results: SearchResult<DocumentMetadata>[] = await db.search(query);
-
-  // TypeScript knows the exact shape of metadata
-  results.forEach(result => {
-    console.log(`Title: ${result.metadata.title}`);
-    console.log(`Author: ${result.metadata.author}`);
-    console.log(`Tags: ${result.metadata.tags.join(', ')}`);
-    console.log(`Similarity: ${result.score.toFixed(3)}\n`);
-  });
-
-  // Step 3.7: Type-safe retrieval
-  const doc = await db.get('article-001');
-  if (doc) {
-    // TypeScript autocomplete works perfectly here
-    const publishYear = doc.metadata.date.getFullYear();
-    console.log(`Published in ${publishYear}`);
-  }
-}
+// Create nodes and relationships
+graph.execute("CREATE (a:Person {name: 'Alice'})-[:KNOWS]->(b:Person {name: 'Bob'})");
+graph.execute("CREATE (b)-[:WORKS_AT]->(c:Company {name: 'TechCorp'})");
 
-typescriptTutorial().catch(console.error);
+// Query relationships
+const friends = graph.execute("MATCH (p:Person)-[:KNOWS]->(friend) RETURN friend.name");
+const colleagues = graph.execute(`
+  MATCH (p:Person {name: 'Alice'})-[:KNOWS]->(friend)-[:WORKS_AT]->(company)
+  RETURN friend.name, company.name
+`);
 ```
 
-**TypeScript Benefits:**
-- ✅ Full autocomplete for all methods and properties
-- ✅ Compile-time type checking prevents errors
-- ✅ IDE IntelliSense shows documentation
-- ✅ Custom metadata types for your use case
-- ✅ No `any` types - fully typed throughout
-
-## 🎯 Platform Detection
-
-Ruvector automatically detects the best implementation for your platform:
+### GNN-Enhanced Search
 
 ```javascript
-const { getImplementationType, isNative, isWasm } = require('ruvector');
+const { GNNLayer } = require('ruvector');
 
-console.log(getImplementationType()); // 'native' or 'wasm'
-console.log(isNative()); // true if using native Rust
-console.log(isWasm()); // true if using WebAssembly fallback
+// Create a GNN layer (input_dim, output_dim, num_heads)
+const layer = new GNNLayer(384, 512, 4);
 
-// Performance varies by implementation:
-// Native (Rust):  <0.5ms latency, 50K+ ops/sec
-// WASM fallback:  10-50ms latency, ~1K ops/sec
-```
-
-## 🔧 CLI Tools
-
-Ruvector includes a full command-line interface for database management:
+// Enhance query with graph context
+const query = getQueryEmbedding();
+const neighbors = getNeighborEmbeddings();
+const weights = computeEdgeWeights();
 
-### Create Database
-
-```bash
-# Create a new vector database
-npx ruvector create mydb.vec --dimensions 384 --metric cosine
-
-# Options:
-#   --dimensions, -d  Vector dimensionality (required)
-#   --metric, -m      Distance metric (cosine, euclidean, dot)
-#   --max-elements    Maximum number of vectors (default: 10000)
+const enhanced = layer.forward(query, neighbors, weights);
+// Use enhanced embedding for better search results
 ```
 
-### Insert Vectors
+### Compression (2-32x Memory Savings)
 
-```bash
-# Insert vectors from JSON file
-npx ruvector insert mydb.vec vectors.json
-
-# JSON format:
-# [
-#   { "id": "doc1", "vector": [0.1, 0.2, ...], "metadata": {...} },
-#   { "id": "doc2", "vector": [0.3, 0.4, ...], "metadata": {...} }
-# ]
-```
+```javascript
+const { compress, decompress, CompressionTier } = require('ruvector');
 
-### Search Vectors
+// Automatic tier selection based on quality threshold
+const compressed = compress(embedding, 0.3); // 30% quality threshold
 
-```bash
-# Search for similar vectors
-npx ruvector search mydb.vec --vector "[0.1,0.2,0.3,...]" --top-k 10
+// Or specify tier explicitly
+const pq8 = compress(embedding, CompressionTier.PQ8);   // 8x compression
+const pq4 = compress(embedding, CompressionTier.PQ4);   // 16x compression
+const binary = compress(embedding, CompressionTier.Binary); // 32x compression
 
-# Options:
-#   --vector, -v   Query vector (JSON array)
-#   --top-k, -k    Number of results (default: 10)
-#   --threshold    Minimum similarity score
+// Decompress when needed
+const restored = decompress(compressed);
 ```
 
-### Database Statistics
+### AI Agent Routing (Tiny Dancer)
 
-```bash
-# Show database statistics
-npx ruvector stats mydb.vec
-
-# Output:
-#   Total vectors: 10,000
-#   Dimensions: 384
-#   Metric: cosine
-#   Memory usage: ~500 KB
-#   Index type: HNSW
-```
+```javascript
+const { Router } = require('ruvector');
 
-### Benchmarking
+// Create router for AI model selection
+const router = new Router({
+  confidenceThreshold: 0.85,
+  maxUncertainty: 0.15
+});
 
-```bash
-# Run performance benchmark
-npx ruvector benchmark --num-vectors 10000 --num-queries 1000
+// Route to optimal model based on query complexity
+const candidates = [
+  { id: 'gpt-4', embedding: gpt4Embedding, cost: 0.03 },
+  { id: 'gpt-3.5', embedding: gpt35Embedding, cost: 0.002 },
+  { id: 'claude', embedding: claudeEmbedding, cost: 0.015 }
+];
 
-# Options:
-#   --num-vectors   Number of vectors to insert
-#   --num-queries   Number of search queries
-#   --dimensions    Vector dimensionality (default: 128)
+const decision = router.route(queryEmbedding, candidates);
+console.log(decision);
+// { candidateId: 'gpt-3.5', confidence: 0.92, useLightweight: true }
 ```
 
-### System Information
+## CLI Usage
 
 ```bash
-# Show platform and implementation info
+# Show system info and backend status
 npx ruvector info
 
-# Output:
-#   Platform: linux-x64-gnu
-#   Implementation: native (Rust)
-#   Node.js: v18.17.0
-#   Performance: <0.5ms p50 latency
-```
-
-## 📊 Performance Benchmarks
-
-Tested on AMD Ryzen 9 5950X, 128-dimensional vectors:
-
-### Native Performance (Rust)
-
-| Operation | Throughput | Latency (p50) | Latency (p99) |
-|-----------|------------|---------------|---------------|
-| Insert    | 52,341 ops/sec | 0.019 ms | 0.045 ms |
-| Search (k=10) | 11,234 ops/sec | 0.089 ms | 0.156 ms |
-| Search (k=100) | 8,932 ops/sec | 0.112 ms | 0.203 ms |
-| Delete    | 45,678 ops/sec | 0.022 ms | 0.051 ms |
-
-**Memory Usage**: ~50 bytes per 128-dim vector (including index)
-
-### Comparison with Alternatives
-
-| Database | Insert (ops/sec) | Search (ops/sec) | Memory per Vector | Node.js | Browser |
-|----------|------------------|------------------|-------------------|---------|---------|
-| **Ruvector (Native)** | **52,341** | **11,234** | **50 bytes** | ✅ | ❌ |
-| **Ruvector (WASM)** | **~1,000** | **~100** | **50 bytes** | ✅ | ✅ |
-| Faiss (HNSW) | 38,200 | 9,800 | 68 bytes | ❌ | ❌ |
-| Hnswlib | 41,500 | 10,200 | 62 bytes | ✅ | ❌ |
-| ChromaDB | ~1,000 | ~20 | 150 bytes | ✅ | ❌ |
-
-*Benchmarks measured with 100K vectors, 128 dimensions, k=10*
-
-## 🔍 Comparison with Other Vector Databases
-
-Comprehensive comparison of Ruvector against popular vector database solutions:
-
-| Feature | Ruvector | Pinecone | Qdrant | Weaviate | Milvus | ChromaDB | Faiss |
-|---------|----------|----------|--------|----------|--------|----------|-------|
-| **Deployment** |
-| Installation | `npm install` ✅ | Cloud API ☁️ | Docker 🐳 | Docker 🐳 | Docker/K8s 🐳 | `pip install` 🐍 | `pip install` 🐍 |
-| Node.js Native | ✅ First-class | ❌ API only | ⚠️ HTTP API | ⚠️ HTTP API | ⚠️ HTTP API | ❌ Python | ❌ Python |
-| Setup Time | < 1 minute | 5-10 minutes | 10-30 minutes | 15-30 minutes | 30-60 minutes | 5 minutes | 5 minutes |
-| Infrastructure | None required | Managed cloud | Self-hosted | Self-hosted | Self-hosted | Embedded | Embedded |
-| **Performance** |
-| Query Latency (p50) | **<0.5ms** | ~2-5ms | ~1-2ms | ~2-3ms | ~3-5ms | ~50ms | ~1ms |
-| Insert Throughput | **52,341 ops/sec** | ~10,000 ops/sec | ~20,000 ops/sec | ~15,000 ops/sec | ~25,000 ops/sec | ~1,000 ops/sec | ~40,000 ops/sec |
-| Memory per Vector (128d) | **50 bytes** | ~80 bytes | 62 bytes | ~100 bytes | ~70 bytes | 150 bytes | 68 bytes |
-| Recall @ k=10 | 95%+ | 93% | 94% | 92% | 96% | 85% | 97% |
-| **Platform Support** |
-| Linux | ✅ Native | ☁️ API | ✅ Docker | ✅ Docker | ✅ Docker | ✅ Python | ✅ Python |
-| macOS | ✅ Native | ☁️ API | ✅ Docker | ✅ Docker | ✅ Docker | ✅ Python | ✅ Python |
-| Windows | ✅ Native | ☁️ API | ✅ Docker | ✅ Docker | ⚠️ WSL2 | ✅ Python | ✅ Python |
-| Browser/WASM | ✅ Yes | ❌ No | ❌ No | ❌ No | ❌ No | ❌ No | ❌ No |
-| ARM64 | ✅ Native | ☁️ API | ✅ Yes | ✅ Yes | ⚠️ Limited | ✅ Yes | ✅ Yes |
-| Alpine Linux | ✅ WASM | ☁️ API | ⚠️ Build from source | ⚠️ Build from source | ❌ No | ✅ Yes | ✅ Yes |
-| **Features** |
-| Distance Metrics | Cosine, L2, Dot | Cosine, L2, Dot | 11 metrics | 10 metrics | 8 metrics | L2, Cosine, IP | L2, IP, Cosine |
-| Filtering | ✅ Metadata | ✅ Advanced | ✅ Advanced | ✅ Advanced | ✅ Advanced | ✅ Basic | ❌ Limited |
-| Persistence | ✅ File-based | ☁️ Managed | ✅ Disk | ✅ Disk | ✅ Disk | ✅ DuckDB | ❌ Memory |
-| Indexing | HNSW | Proprietary | HNSW | HNSW | IVF/HNSW | HNSW | IVF/HNSW |
-| Quantization | ✅ PQ | ✅ Yes | ✅ Scalar | ✅ PQ | ✅ PQ/SQ | ❌ No | ✅ PQ |
-| Batch Operations | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes |
-| **Developer Experience** |
-| TypeScript Types | ✅ Full | ✅ Generated | ⚠️ Community | ⚠️ Community | ⚠️ Community | ⚠️ Partial | ❌ No |
-| Documentation | ✅ Excellent | ✅ Excellent | ✅ Good | ✅ Good | ✅ Good | ✅ Good | ⚠️ Technical |
-| Examples | ✅ Many | ✅ Many | ✅ Good | ✅ Good | ✅ Many | ✅ Good | ⚠️ Limited |
-| CLI Tools | ✅ Included | ⚠️ Limited | ✅ Yes | ✅ Yes | ✅ Yes | ⚠️ Basic | ❌ No |
-| **Operations** |
-| Monitoring | ✅ Metrics | ✅ Dashboard | ✅ Prometheus | ✅ Prometheus | ✅ Prometheus | ⚠️ Basic | ❌ No |
-| Backups | ✅ File copy | ☁️ Automatic | ✅ Snapshots | ✅ Snapshots | ✅ Snapshots | ✅ File copy | ❌ Manual |
-| High Availability | ⚠️ App-level | ✅ Built-in | ✅ Clustering | ✅ Clustering | ✅ Clustering | ❌ No | ❌ No |
-| Auto-Scaling | ⚠️ App-level | ✅ Automatic | ⚠️ Manual | ⚠️ Manual | ⚠️ K8s HPA | ❌ No | ❌ No |
-| **Cost** |
-| Pricing Model | Free (MIT) | Pay-per-use | Free (Apache) | Free (BSD) | Free (Apache) | Free (Apache) | Free (MIT) |
-| Monthly Cost (1M vectors) | **$0** | ~$70-200 | ~$20-50 (infra) | ~$30-60 (infra) | ~$50-100 (infra) | $0 | $0 |
-| Monthly Cost (10M vectors) | **$0** | ~$500-1000 | ~$100-200 (infra) | ~$150-300 (infra) | ~$200-400 (infra) | $0 | $0 |
-| API Rate Limits | None | Yes | None | None | None | None | None |
-| **Use Cases** |
-| RAG Systems | ✅ Excellent | ✅ Excellent | ✅ Excellent | ✅ Excellent | ✅ Excellent | ✅ Good | ⚠️ Limited |
-| Serverless | ✅ Perfect | ✅ Good | ❌ No | ❌ No | ❌ No | ⚠️ Possible | ⚠️ Possible |
-| Edge Computing | ✅ Excellent | ❌ No | ❌ No | ❌ No | ❌ No | ❌ No | ⚠️ Possible |
-| Production Scale (100M+) | ⚠️ Single node | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Excellent | ⚠️ Limited | ⚠️ Manual |
-| Embedded Apps | ✅ Excellent | ❌ No | ❌ No | ❌ No | ❌ No | ⚠️ Possible | ✅ Good |
-
-### When to Choose Ruvector
-
-✅ **Perfect for:**
-- **Node.js/TypeScript applications** needing embedded vector search
-- **Serverless and edge computing** where external services aren't practical
-- **Rapid prototyping and development** with minimal setup time
-- **RAG systems** with LangChain, LlamaIndex, or custom implementations
-- **Cost-sensitive projects** that can't afford cloud API pricing
-- **Offline-first applications** requiring local vector search
-- **Browser-based AI** with WebAssembly fallback
-- **Small to medium scale** (up to 10M vectors per instance)
-
-⚠️ **Consider alternatives for:**
-- **Massive scale (100M+ vectors)** - Consider Pinecone, Milvus, or Qdrant clusters
-- **Multi-tenancy requirements** - Weaviate or Qdrant offer better isolation
-- **Distributed systems** - Milvus provides better horizontal scaling
-- **Zero-ops cloud solution** - Pinecone handles all infrastructure
-
-### Why Choose Ruvector Over...
-
-**vs Pinecone:**
-- ✅ No API costs (save $1000s/month)
-- ✅ No network latency (10x faster queries)
-- ✅ No vendor lock-in
-- ✅ Works offline and in restricted environments
-- ❌ No managed multi-region clusters
-
-**vs ChromaDB:**
-- ✅ 50x faster queries (native Rust vs Python)
-- ✅ True Node.js support (not HTTP API)
-- ✅ Better TypeScript integration
-- ✅ Lower memory usage
-- ❌ Smaller ecosystem and community
-
-**vs Qdrant:**
-- ✅ Zero infrastructure setup
-- ✅ Embedded in your app (no Docker)
-- ✅ Better for serverless environments
-- ✅ Native Node.js bindings
-- ❌ No built-in clustering or HA
-
-**vs Faiss:**
-- ✅ Full Node.js support (Faiss is Python-only)
-- ✅ Easier API and better developer experience
-- ✅ Built-in persistence and metadata
-- ⚠️ Slightly lower recall at same performance
-
-## 🎯 Real-World Tutorials
-
-### Tutorial 1: Building a RAG System with OpenAI
-
-**What you'll learn:** Create a production-ready Retrieval-Augmented Generation system that enhances LLM responses with relevant context from your documents.
-
-**Prerequisites:**
-```bash
-npm install ruvector openai
-export OPENAI_API_KEY="your-api-key-here"
-```
+# Initialize a new index
+npx ruvector init my-index.bin --dimension 384 --type hnsw
 
-**Complete Implementation:**
+# Insert vectors from JSON file
+npx ruvector insert my-index.bin vectors.json
 
-```javascript
-const { VectorDb } = require('ruvector');
-const OpenAI = require('openai');
-
-class RAGSystem {
-  constructor() {
-    // Initialize OpenAI client
-    this.openai = new OpenAI({
-      apiKey: process.env.OPENAI_API_KEY
-    });
-
-    // Create vector database for OpenAI embeddings
-    // text-embedding-ada-002 produces 1536-dimensional vectors
-    this.db = new VectorDb({
-      dimensions: 1536,
-      maxElements: 100000,
-      storagePath: './rag-knowledge-base.db'
-    });
-
-    console.log('✅ RAG System initialized');
-  }
-
-  // Step 1: Index your knowledge base
-  async indexDocuments(documents) {
-    console.log(`📚 Indexing ${documents.length} documents...`);
-
-    for (let i = 0; i < documents.length; i++) {
-      const doc = documents[i];
-
-      // Generate embedding for the document
-      const response = await this.openai.embeddings.create({
-        model: 'text-embedding-ada-002',
-        input: doc.content
-      });
-
-      // Store in vector database
-      await this.db.insert({
-        id: doc.id || `doc_${i}`,
-        vector: new Float32Array(response.data[0].embedding),
-        metadata: {
-          title: doc.title,
-          content: doc.content,
-          source: doc.source,
-          date: doc.date || new Date().toISOString()
-        }
-      });
-
-      console.log(`  ✅ Indexed: ${doc.title}`);
-    }
-
-    const count = await this.db.len();
-    console.log(`\n✅ Indexed ${count} documents total`);
-  }
-
-  // Step 2: Retrieve relevant context for a query
-  async retrieveContext(query, k = 3) {
-    console.log(`🔍 Searching for: "${query}"`);
-
-    // Generate embedding for the query
-    const response = await this.openai.embeddings.create({
-      model: 'text-embedding-ada-002',
-      input: query
-    });
-
-    // Search for similar documents
-    const results = await this.db.search({
-      vector: new Float32Array(response.data[0].embedding),
-      k: k,
-      threshold: 0.7  // Only use highly relevant results
-    });
-
-    console.log(`📄 Found ${results.length} relevant documents\n`);
-
-    return results.map(r => ({
-      content: r.metadata.content,
-      title: r.metadata.title,
-      score: r.score
-    }));
-  }
-
-  // Step 3: Generate answer with retrieved context
-  async answer(question) {
-    // Retrieve relevant context
-    const context = await this.retrieveContext(question, 3);
-
-    if (context.length === 0) {
-      return "I don't have enough information to answer that question.";
-    }
-
-    // Build prompt with context
-    const contextText = context
-      .map((doc, i) => `[${i + 1}] ${doc.title}\n${doc.content}`)
-      .join('\n\n');
-
-    const prompt = `Answer the question based on the following context. If the context doesn't contain the answer, say so.
-
-Context:
-${contextText}
-
-Question: ${question}
-
-Answer:`;
-
-    console.log('🤖 Generating answer...\n');
-
-    // Generate completion
-    const completion = await this.openai.chat.completions.create({
-      model: 'gpt-4',
-      messages: [
-        { role: 'system', content: 'You are a helpful assistant that answers questions based on provided context.' },
-        { role: 'user', content: prompt }
-      ],
-      temperature: 0.3  // Lower temperature for more factual responses
-    });
-
-    return {
-      answer: completion.choices[0].message.content,
-      sources: context.map(c => c.title)
-    };
-  }
-}
+# Search with a query vector
+npx ruvector search my-index.bin --query "[0.1, 0.2, ...]" -k 10
 
-// Example Usage
-async function main() {
-  const rag = new RAGSystem();
-
-  // Step 1: Index your knowledge base
-  const documents = [
-    {
-      id: 'doc1',
-      title: 'Ruvector Introduction',
-      content: 'Ruvector is a high-performance vector database for Node.js built in Rust. It provides sub-millisecond query latency and supports over 52,000 inserts per second.',
-      source: 'documentation'
-    },
-    {
-      id: 'doc2',
-      title: 'Vector Databases Explained',
-      content: 'Vector databases store data as high-dimensional vectors, enabling semantic similarity search. They are essential for AI applications like RAG systems and recommendation engines.',
-      source: 'blog'
-    },
-    {
-      id: 'doc3',
-      title: 'HNSW Algorithm',
-      content: 'Hierarchical Navigable Small World (HNSW) is a graph-based algorithm for approximate nearest neighbor search. It provides excellent recall with low latency.',
-      source: 'research'
-    }
-  ];
-
-  await rag.indexDocuments(documents);
-
-  // Step 2: Ask questions
-  console.log('\n' + '='.repeat(60) + '\n');
-
-  const result = await rag.answer('What is Ruvector and what are its performance characteristics?');
-
-  console.log('📝 Answer:', result.answer);
-  console.log('\n📚 Sources:', result.sources.join(', '));
-}
+# Show index statistics
+npx ruvector stats my-index.bin
 
-main().catch(console.error);
+# Run performance benchmarks
+npx ruvector benchmark --dimension 384 --num-vectors 10000
 ```
 
-**Expected Output:**
-```
-✅ RAG System initialized
-📚 Indexing 3 documents...
-  ✅ Indexed: Ruvector Introduction
-  ✅ Indexed: Vector Databases Explained
-  ✅ Indexed: HNSW Algorithm
-
-✅ Indexed 3 documents total
+## Features
 
-============================================================
+### Core Capabilities
 
-🔍 Searching for: "What is Ruvector and what are its performance characteristics?"
-📄 Found 2 relevant documents
+| Feature | Description |
+|---------|-------------|
+| **Vector Search** | HNSW index, <0.5ms latency, SIMD acceleration |
+| **Cypher Queries** | `MATCH`, `WHERE`, `CREATE`, `RETURN` — Neo4j syntax |
+| **GNN Layers** | Multi-head attention on graph topology |
+| **Hyperedges** | Connect 3+ nodes simultaneously |
+| **Metadata Filtering** | Combine semantic + structured search |
+| **Collections** | Namespace isolation, multi-tenancy |
 
-🤖 Generating answer...
+### AI & ML
 
-📝 Answer: Ruvector is a high-performance vector database built in Rust for Node.js applications. Its key performance characteristics include:
-- Sub-millisecond query latency
-- Over 52,000 inserts per second
-- Optimized for semantic similarity search
+| Feature | Description |
+|---------|-------------|
+| **Tensor Compression** | f32→f16→PQ8→PQ4→Binary (2-32x reduction) |
+| **Differentiable Search** | Soft attention k-NN for end-to-end training |
+| **Semantic Router** | Route queries to optimal endpoints |
+| **Tiny Dancer** | FastGRNN neural inference for LLM cost optimization |
 
-📚 Sources: Ruvector Introduction, Vector Databases Explained
-```
+### Platform Support
 
-**Production Tips:**
-- ✅ Use batch embedding for better throughput (OpenAI supports up to 2048 texts)
-- ✅ Implement caching for frequently asked questions
-- ✅ Add error handling for API rate limits
-- ✅ Monitor token usage and costs
-- ✅ Regularly update your knowledge base
-
----
+| Platform | Package | Notes |
+|----------|---------|-------|
+| **Node.js** | `ruvector` | Native bindings via napi-rs |
+| **Browser** | `@ruvector/wasm` | Full WASM support |
+| **Bun** | `ruvector` | Native bindings |
+| **Deno** | `@ruvector/wasm` | WASM fallback |
 
-### Tutorial 2: Semantic Search Engine
+## Benchmarks
 
-**What you'll learn:** Build a semantic search engine that understands meaning, not just keywords.
+| Operation | Dimensions | Time | Throughput |
+|-----------|------------|------|------------|
+| **HNSW Search (k=10)** | 384 | 61µs | 16,400 QPS |
+| **HNSW Search (k=100)** | 384 | 164µs | 6,100 QPS |
+| **Cosine Distance** | 1536 | 143ns | 7M ops/sec |
+| **Dot Product** | 384 | 33ns | 30M ops/sec |
+| **Insert** | 384 | 20µs | 50,000/sec |
 
-**Prerequisites:**
+Run your own benchmarks:
 ```bash
-npm install ruvector @xenova/transformers
+npx ruvector benchmark --dimension 384 --num-vectors 10000
 ```
 
-**Complete Implementation:**
+## npm Packages
 
-```javascript
-const { VectorDb } = require('ruvector');
-const { pipeline } = require('@xenova/transformers');
-
-class SemanticSearchEngine {
-  constructor() {
-    this.db = null;
-    this.embedder = null;
-  }
-
-  // Step 1: Initialize the embedding model
-  async initialize() {
-    console.log('🚀 Initializing semantic search engine...');
-
-    // Load sentence-transformers model (runs locally, no API needed!)
-    console.log('📥 Loading embedding model...');
-    this.embedder = await pipeline(
-      'feature-extraction',
-      'Xenova/all-MiniLM-L6-v2'
-    );
-
-    // Create vector database (384 dimensions for all-MiniLM-L6-v2)
-    this.db = new VectorDb({
-      dimensions: 384,
-      maxElements: 50000,
-      storagePath: './semantic-search.db'
-    });
-
-    console.log('✅ Search engine ready!\n');
-  }
-
-  // Step 2: Generate embeddings
-  async embed(text) {
-    const output = await this.embedder(text, {
-      pooling: 'mean',
-      normalize: true
-    });
-
-    // Convert to Float32Array
-    return new Float32Array(output.data);
-  }
-
-  // Step 3: Index documents
-  async indexDocuments(documents) {
-    console.log(`📚 Indexing ${documents.length} documents...`);
-
-    for (const doc of documents) {
-      const vector = await this.embed(doc.content);
-
-      await this.db.insert({
-        id: doc.id,
-        vector: vector,
-        metadata: {
-          title: doc.title,
-          content: doc.content,
-          category: doc.category,
-          url: doc.url
-        }
-      });
-
-      console.log(`  ✅ ${doc.title}`);
-    }
-
-    const count = await this.db.len();
-    console.log(`\n✅ Indexed ${count} documents\n`);
-  }
-
-  // Step 4: Semantic search
-  async search(query, options = {}) {
-    const {
-      k = 5,
-      category = null,
-      threshold = 0.3
-    } = options;
-
-    console.log(`🔍 Searching for: "${query}"`);
-
-    // Generate query embedding
-    const queryVector = await this.embed(query);
-
-    // Search vector database
-    const results = await this.db.search({
-      vector: queryVector,
-      k: k * 2,  // Get more results for filtering
-      threshold: threshold
-    });
-
-    // Filter by category if specified
-    let filtered = results;
-    if (category) {
-      filtered = results.filter(r => r.metadata.category === category);
-    }
-
-    // Return top k after filtering
-    const final = filtered.slice(0, k);
-
-    console.log(`📄 Found ${final.length} results\n`);
-
-    return final.map(r => ({
-      id: r.id,
-      title: r.metadata.title,
-      content: r.metadata.content,
-      category: r.metadata.category,
-      score: r.score,
-      url: r.metadata.url
-    }));
-  }
-
-  // Step 5: Find similar documents
-  async findSimilar(documentId, k = 5) {
-    const doc = await this.db.get(documentId);
-
-    if (!doc) {
-      throw new Error(`Document ${documentId} not found`);
-    }
-
-    const results = await this.db.search({
-      vector: doc.vector,
-      k: k + 1  // +1 because the document itself will be included
-    });
-
-    // Remove the document itself from results
-    return results
-      .filter(r => r.id !== documentId)
-      .slice(0, k);
-  }
-}
+| Package | Description |
+|---------|-------------|
+| [`ruvector`](https://www.npmjs.com/package/ruvector) | All-in-one package (recommended) |
+| [`@ruvector/wasm`](https://www.npmjs.com/package/@ruvector/wasm) | Browser/WASM bindings |
+| [`@ruvector/graph`](https://www.npmjs.com/package/@ruvector/graph) | Graph database with Cypher |
+| [`@ruvector/gnn`](https://www.npmjs.com/package/@ruvector/gnn) | Graph Neural Network layers |
+| [`@ruvector/tiny-dancer`](https://www.npmjs.com/package/@ruvector/tiny-dancer) | AI agent routing (FastGRNN) |
+| [`@ruvector/router`](https://www.npmjs.com/package/@ruvector/router) | Semantic routing engine |
 
-// Example Usage
-async function main() {
-  const engine = new SemanticSearchEngine();
-  await engine.initialize();
-
-  // Sample documents (in production, load from your database)
-  const documents = [
-    {
-      id: '1',
-      title: 'Understanding Neural Networks',
-      content: 'Neural networks are computing systems inspired by biological neural networks. They learn to perform tasks by considering examples.',
-      category: 'AI',
-      url: '/docs/neural-networks'
-    },
-    {
-      id: '2',
-      title: 'Introduction to Machine Learning',
-      content: 'Machine learning is a subset of artificial intelligence that provides systems the ability to learn and improve from experience.',
-      category: 'AI',
-      url: '/docs/machine-learning'
-    },
-    {
-      id: '3',
-      title: 'Web Development Best Practices',
-      content: 'Modern web development involves responsive design, performance optimization, and accessibility considerations.',
-      category: 'Web',
-      url: '/docs/web-dev'
-    },
-    {
-      id: '4',
-      title: 'Deep Learning Applications',
-      content: 'Deep learning has revolutionized computer vision, natural language processing, and speech recognition.',
-      category: 'AI',
-      url: '/docs/deep-learning'
-    }
-  ];
-
-  // Index documents
-  await engine.indexDocuments(documents);
-
-  // Example 1: Basic semantic search
-  console.log('Example 1: Basic Search\n' + '='.repeat(60));
-  const results1 = await engine.search('AI and neural nets');
-  results1.forEach((result, i) => {
-    console.log(`${i + 1}. ${result.title} (Score: ${result.score.toFixed(3)})`);
-    console.log(`   ${result.content.slice(0, 80)}...`);
-    console.log(`   Category: ${result.category}\n`);
-  });
-
-  // Example 2: Category-filtered search
-  console.log('\nExample 2: Category-Filtered Search\n' + '='.repeat(60));
-  const results2 = await engine.search('learning algorithms', {
-    category: 'AI',
-    k: 3
-  });
-  results2.forEach((result, i) => {
-    console.log(`${i + 1}. ${result.title} (Score: ${result.score.toFixed(3)})`);
-  });
-
-  // Example 3: Find similar documents
-  console.log('\n\nExample 3: Find Similar Documents\n' + '='.repeat(60));
-  const similar = await engine.findSimilar('1', 2);
-  console.log('Documents similar to "Understanding Neural Networks":');
-  similar.forEach((doc, i) => {
-    console.log(`${i + 1}. ${doc.metadata.title} (Score: ${doc.score.toFixed(3)})`);
-  });
-}
+```bash
+# Install all-in-one (recommended)
+npm install ruvector
 
-main().catch(console.error);
+# Or install specific packages
+npm install @ruvector/graph @ruvector/gnn
 ```
 
-**Key Features:**
-- ✅ Runs completely locally (no API keys needed)
-- ✅ Understands semantic meaning, not just keywords
-- ✅ Category filtering for better results
-- ✅ "Find similar" functionality
-- ✅ Fast: ~10ms query latency
+## API Reference
 
----
-
-### Tutorial 3: AI Agent Memory System
-
-**What you'll learn:** Implement a memory system for AI agents that remembers past experiences and learns from them.
+### VectorDB
 
-**Complete Implementation:**
-
-```javascript
-const { VectorDb } = require('ruvector');
-
-class AgentMemory {
-  constructor(agentId) {
-    this.agentId = agentId;
-
-    // Create separate databases for different memory types
-    this.episodicMemory = new VectorDb({
-      dimensions: 768,
-      storagePath: `./memory/${agentId}-episodic.db`
-    });
-
-    this.semanticMemory = new VectorDb({
-      dimensions: 768,
-      storagePath: `./memory/${agentId}-semantic.db`
-    });
-
-    console.log(`🧠 Memory system initialized for agent: ${agentId}`);
-  }
-
-  // Step 1: Store an experience (episodic memory)
-  async storeExperience(experience) {
-    const {
-      state,
-      action,
-      result,
-      reward,
-      embedding
-    } = experience;
-
-    const experienceId = `exp_${Date.now()}_${Math.random()}`;
-
-    await this.episodicMemory.insert({
-      id: experienceId,
-      vector: new Float32Array(embedding),
-      metadata: {
-        state: state,
-        action: action,
-        result: result,
-        reward: reward,
-        timestamp: Date.now(),
-        type: 'episodic'
-      }
-    });
-
-    console.log(`💾 Stored experience: ${action} -> ${result} (reward: ${reward})`);
-    return experienceId;
-  }
-
-  // Step 2: Store learned knowledge (semantic memory)
-  async storeKnowledge(knowledge) {
-    const {
-      concept,
-      description,
-      embedding,
-      confidence = 1.0
-    } = knowledge;
-
-    const knowledgeId = `know_${Date.now()}`;
-
-    await this.semanticMemory.insert({
-      id: knowledgeId,
-      vector: new Float32Array(embedding),
-      metadata: {
-        concept: concept,
-        description: description,
-        confidence: confidence,
-        learned: Date.now(),
-        uses: 0,
-        type: 'semantic'
-      }
-    });
-
-    console.log(`📚 Learned: ${concept}`);
-    return knowledgeId;
-  }
-
-  // Step 3: Recall similar experiences
-  async recallExperiences(currentState, k = 5) {
-    console.log(`🔍 Recalling similar experiences...`);
-
-    const results = await this.episodicMemory.search({
-      vector: new Float32Array(currentState.embedding),
-      k: k,
-      threshold: 0.6  // Only recall reasonably similar experiences
-    });
-
-    // Sort by reward to prioritize successful experiences
-    const sorted = results.sort((a, b) => b.metadata.reward - a.metadata.reward);
-
-    console.log(`📝 Recalled ${sorted.length} relevant experiences`);
-
-    return sorted.map(r => ({
-      state: r.metadata.state,
-      action: r.metadata.action,
-      result: r.metadata.result,
-      reward: r.metadata.reward,
-      similarity: r.score
-    }));
-  }
-
-  // Step 4: Query knowledge base
-  async queryKnowledge(query, k = 3) {
-    const results = await this.semanticMemory.search({
-      vector: new Float32Array(query.embedding),
-      k: k
-    });
-
-    // Update usage statistics
-    for (const result of results) {
-      const knowledge = await this.semanticMemory.get(result.id);
-      if (knowledge) {
-        knowledge.metadata.uses += 1;
-        // In production, update the entry
-      }
-    }
-
-    return results.map(r => ({
-      concept: r.metadata.concept,
-      description: r.metadata.description,
-      confidence: r.metadata.confidence,
-      relevance: r.score
-    }));
-  }
-
-  // Step 5: Reflect and learn from experiences
-  async reflect() {
-    console.log('\n🤔 Reflecting on experiences...');
-
-    // Get all experiences
-    const totalExperiences = await this.episodicMemory.len();
-    console.log(`📊 Total experiences: ${totalExperiences}`);
-
-    // Analyze success rate
-    // In production, you'd aggregate experiences and extract patterns
-    console.log('💡 Analysis complete');
-
-    return {
-      totalExperiences: totalExperiences,
-      knowledgeItems: await this.semanticMemory.len()
-    };
-  }
-
-  // Step 6: Get memory statistics
-  async getStats() {
-    return {
-      episodicMemorySize: await this.episodicMemory.len(),
-      semanticMemorySize: await this.semanticMemory.len(),
-      agentId: this.agentId
-    };
-  }
-}
-
-// Example Usage: Simulated agent learning to navigate
-async function main() {
-  const agent = new AgentMemory('agent-001');
-
-  // Simulate embedding function (in production, use a real model)
-  function embed(text) {
-    return Array(768).fill(0).map(() => Math.random());
-  }
-
-  console.log('\n' + '='.repeat(60));
-  console.log('PHASE 1: Learning from experiences');
-  console.log('='.repeat(60) + '\n');
-
-  // Store some experiences
-  await agent.storeExperience({
-    state: { location: 'room1', goal: 'room3' },
-    action: 'move_north',
-    result: 'reached room2',
-    reward: 0.5,
-    embedding: embed('navigating from room1 to room2')
-  });
-
-  await agent.storeExperience({
-    state: { location: 'room2', goal: 'room3' },
-    action: 'move_east',
-    result: 'reached room3',
-    reward: 1.0,
-    embedding: embed('navigating from room2 to room3')
-  });
-
-  await agent.storeExperience({
-    state: { location: 'room1', goal: 'room3' },
-    action: 'move_south',
-    result: 'hit wall',
-    reward: -0.5,
-    embedding: embed('failed navigation attempt')
-  });
-
-  // Store learned knowledge
-  await agent.storeKnowledge({
-    concept: 'navigation_strategy',
-    description: 'Moving north then east is efficient for reaching room3 from room1',
-    embedding: embed('navigation strategy knowledge'),
-    confidence: 0.9
-  });
-
-  console.log('\n' + '='.repeat(60));
-  console.log('PHASE 2: Applying memory');
-  console.log('='.repeat(60) + '\n');
-
-  // Agent encounters a similar situation
-  const currentState = {
-    location: 'room1',
-    goal: 'room3',
-    embedding: embed('navigating from room1 to room3')
-  };
-
-  // Recall relevant experiences
-  const experiences = await agent.recallExperiences(currentState, 3);
-
-  console.log('\n📖 Recalled experiences:');
-  experiences.forEach((exp, i) => {
-    console.log(`${i + 1}. Action: ${exp.action} | Result: ${exp.result} | Reward: ${exp.reward} | Similarity: ${exp.similarity.toFixed(3)}`);
-  });
-
-  // Query relevant knowledge
-  const knowledge = await agent.queryKnowledge({
-    embedding: embed('how to navigate efficiently')
-  }, 2);
-
-  console.log('\n📚 Relevant knowledge:');
-  knowledge.forEach((k, i) => {
-    console.log(`${i + 1}. ${k.concept}: ${k.description} (confidence: ${k.confidence})`);
-  });
-
-  console.log('\n' + '='.repeat(60));
-  console.log('PHASE 3: Reflection');
-  console.log('='.repeat(60) + '\n');
-
-  // Reflect on learning
-  const stats = await agent.reflect();
-  const memoryStats = await agent.getStats();
-
-  console.log('\n📊 Memory Statistics:');
-  console.log(`   Episodic memories: ${memoryStats.episodicMemorySize}`);
-  console.log(`   Semantic knowledge: ${memoryStats.semanticMemorySize}`);
-  console.log(`   Agent ID: ${memoryStats.agentId}`);
+```typescript
+class VectorDB {
+  constructor(dimension: number, options?: VectorDBOptions);
+
+  insert(id: string, values: number[], metadata?: object): void;
+  insertBatch(vectors: Vector[]): void;
+  search(query: number[], k?: number, filter?: object): SearchResult[];
+  get(id: string): Vector | null;
+  delete(id: string): boolean;
+  save(path: string): void;
+  static load(path: string): VectorDB;
 }
-
-main().catch(console.error);
 ```
 
-**Expected Output:**
-```
-🧠 Memory system initialized for agent: agent-001
-
-============================================================
-PHASE 1: Learning from experiences
-============================================================
-
-💾 Stored experience: move_north -> reached room2 (reward: 0.5)
-💾 Stored experience: move_east -> reached room3 (reward: 1.0)
-💾 Stored experience: move_south -> hit wall (reward: -0.5)
-📚 Learned: navigation_strategy
-
-============================================================
-PHASE 2: Applying memory
-============================================================
-
-🔍 Recalling similar experiences...
-📝 Recalled 3 relevant experiences
+### GraphDB
 
-📖 Recalled experiences:
-1. Action: move_east | Result: reached room3 | Reward: 1.0 | Similarity: 0.892
-2. Action: move_north | Result: reached room2 | Reward: 0.5 | Similarity: 0.876
-3. Action: move_south | Result: hit wall | Reward: -0.5 | Similarity: 0.654
+```typescript
+class GraphDB {
+  constructor();
 
-📚 Relevant knowledge:
-1. navigation_strategy: Moving north then east is efficient for reaching room3 from room1 (confidence: 0.9)
+  execute(cypher: string): QueryResult;
+  createNode(label: string, properties: object): string;
+  createRelationship(from: string, to: string, type: string): void;
+  createHyperedge(nodeIds: string[], type: string): string;
+}
+```
 
-============================================================
-PHASE 3: Reflection
-============================================================
+### GNNLayer
 
-🤔 Reflecting on experiences...
-📊 Total experiences: 3
-💡 Analysis complete
+```typescript
+class GNNLayer {
+  constructor(inputDim: number, outputDim: number, numHeads: number);
 
-📊 Memory Statistics:
-   Episodic memories: 3
-   Semantic knowledge: 1
-   Agent ID: agent-001
+  forward(query: number[], neighbors: number[][], weights: number[]): number[];
+  train(data: TrainingData, epochs: number): void;
+}
 ```
 
-**Use Cases:**
-- ✅ Reinforcement learning agents
-- ✅ Chatbot conversation history
-- ✅ Game AI that learns from gameplay
-- ✅ Personal assistant memory
-- ✅ Robotic navigation systems
-
-## 🏗️ API Reference
-
-### Constructor
+### Router (Tiny Dancer)
 
 ```typescript
-new VectorDb(options: {
-  dimensions: number;        // Vector dimensionality (required)
-  maxElements?: number;      // Max vectors (default: 10000)
-  storagePath?: string;      // Persistent storage path
-  ef_construction?: number;  // HNSW construction parameter (default: 200)
-  m?: number;               // HNSW M parameter (default: 16)
-  distanceMetric?: string;  // 'cosine', 'euclidean', or 'dot' (default: 'cosine')
-})
+class Router {
+  constructor(config?: RouterConfig);
+
+  route(query: number[], candidates: Candidate[]): RoutingDecision;
+  reloadModel(): void;
+  circuitBreakerStatus(): 'closed' | 'open' | 'half-open';
+}
 ```
 
-### Methods
+## Use Cases
 
-#### insert(entry: VectorEntry): Promise<string>
-Insert a vector into the database.
+### RAG (Retrieval-Augmented Generation)
 
 ```javascript
-const id = await db.insert({
-  id: 'doc_1',
-  vector: new Float32Array([0.1, 0.2, 0.3, ...]),
-  metadata: { title: 'Document 1' }
-});
-```
+const ruvector = require('ruvector');
 
-#### search(query: SearchQuery): Promise<SearchResult[]>
-Search for similar vectors.
+async function ragQuery(question) {
+  const questionEmbedding = await embed(question);
+  const context = db.search(questionEmbedding, 5);
 
-```javascript
-const results = await db.search({
-  vector: new Float32Array([0.1, 0.2, 0.3, ...]),
-  k: 10,
-  threshold: 0.7
-});
-```
+  const prompt = `
+    Context: ${context.map(c => c.metadata.text).join('\n')}
 
-#### get(id: string): Promise<VectorEntry | null>
-Retrieve a vector by ID.
+    Question: ${question}
+    Answer:
+  `;
 
-```javascript
-const entry = await db.get('doc_1');
-if (entry) {
-  console.log(entry.vector, entry.metadata);
+  return await llm.complete(prompt);
 }
 ```
 
-#### delete(id: string): Promise<boolean>
-Remove a vector from the database.
+### Recommendation System
 
 ```javascript
-const deleted = await db.delete('doc_1');
-console.log(deleted ? 'Deleted' : 'Not found');
-```
+const { GraphDB } = require('ruvector');
 
-#### len(): Promise<number>
-Get the total number of vectors.
+const graph = new GraphDB();
 
-```javascript
-const count = await db.len();
-console.log(`Total vectors: ${count}`);
+// Find recommendations based on user behavior
+const recommendations = graph.execute(`
+  MATCH (user:User {id: $userId})-[:VIEWED]->(item:Product)
+  MATCH (item)-[:SIMILAR_TO]->(rec:Product)
+  WHERE NOT (user)-[:VIEWED]->(rec)
+  RETURN rec ORDER BY rec.score DESC LIMIT 10
+`);
 ```
 
-## 🎨 Advanced Configuration
-
-### HNSW Parameters
+### Semantic Search with Filters
 
 ```javascript
-const db = new VectorDb({
-  dimensions: 384,
-  maxElements: 1000000,
-  ef_construction: 200,  // Higher = better recall, slower build
-  m: 16,                 // Higher = better recall, more memory
-  storagePath: './large-db.db'
+const results = db.search(queryEmbedding, 20, {
+  category: 'electronics',
+  price: { $lt: 500 },
+  inStock: true
 });
 ```
 
-**Parameter Guidelines:**
-- `ef_construction`: 100-400 (higher = better recall, slower indexing)
-- `m`: 8-64 (higher = better recall, more memory)
-- Default values work well for most use cases
-
-### Distance Metrics
-
-```javascript
-// Cosine similarity (default, best for normalized vectors)
-const db1 = new VectorDb({
-  dimensions: 128,
-  distanceMetric: 'cosine'
-});
+## Architecture
 
-// Euclidean distance (L2, best for spatial data)
-const db2 = new VectorDb({
-  dimensions: 128,
-  distanceMetric: 'euclidean'
-});
-
-// Dot product (best for pre-normalized vectors)
-const db3 = new VectorDb({
-  dimensions: 128,
-  distanceMetric: 'dot'
-});
 ```
-
-### Persistence
-
-```javascript
-// Auto-save to disk
-const persistent = new VectorDb({
-  dimensions: 128,
-  storagePath: './persistent.db'
-});
-
-// In-memory only (faster, but data lost on exit)
-const temporary = new VectorDb({
-  dimensions: 128
-  // No storagePath = in-memory
-});
+┌─────────────────────────────────────────────────────────┐
+│                       ruvector                          │
+│              (All-in-One npm Package)                   │
+├─────────────┬─────────────┬─────────────┬──────────────┤
+│  VectorDB   │   GraphDB   │  GNNLayer   │   Router     │
+│  (Search)   │  (Cypher)   │  (ML)       │ (AI Routing) │
+└─────────────┴─────────────┴─────────────┴──────────────┘
+                           │
+        ┌──────────────────┼──────────────────┐
+        │                  │                  │
+   ┌────▼────┐       ┌────▼────┐       ┌────▼────┐
+   │  Native │       │  WASM   │       │  FFI    │
+   │ (napi)  │       │(wasm32) │       │  (C)    │
+   └─────────┘       └─────────┘       └─────────┘
 ```
 
-## 📦 Platform Support
-
-Automatically installs the correct implementation for:
-
-### Native (Rust) - Best Performance
-- **Linux**: x64, ARM64 (GNU libc)
-- **macOS**: x64 (Intel), ARM64 (Apple Silicon)
-- **Windows**: x64 (MSVC)
-
-Performance: **<0.5ms latency**, **50K+ ops/sec**
+The package automatically selects the best available backend (native > WASM).
 
-### WASM Fallback - Universal Compatibility
-- Any platform where native module isn't available
-- Browser environments (experimental)
-- Alpine Linux (musl) and other non-glibc systems
+## Comparison
 
-Performance: **10-50ms latency**, **~1K ops/sec**
+| Feature | RuVector | Pinecone | Qdrant | ChromaDB |
+|---------|----------|----------|--------|----------|
+| **Latency** | **61µs** | ~2ms | ~1ms | ~50ms |
+| **Graph Queries** | ✅ Cypher | ❌ | ❌ | ❌ |
+| **Self-Learning** | ✅ GNN | ❌ | ❌ | ❌ |
+| **AI Routing** | ✅ | ❌ | ❌ | ❌ |
+| **Browser/WASM** | ✅ | ❌ | ❌ | ❌ |
+| **Compression** | 2-32x | ❌ | ❌ | ❌ |
+| **Open Source** | ✅ MIT | ❌ | ✅ | ✅ |
 
-**Node.js 18+ required** for all platforms.
+## Documentation
 
-## 🔧 Building from Source
+- [Getting Started Guide](https://github.com/ruvnet/ruvector/blob/main/docs/guide/GETTING_STARTED.md)
+- [Cypher Reference](https://github.com/ruvnet/ruvector/blob/main/docs/api/CYPHER_REFERENCE.md)
+- [GNN Architecture](https://github.com/ruvnet/ruvector/blob/main/docs/gnn-layer-implementation.md)
+- [Performance Tuning](https://github.com/ruvnet/ruvector/blob/main/docs/optimization/PERFORMANCE_TUNING_GUIDE.md)
+- [API Reference](https://github.com/ruvnet/ruvector/tree/main/docs/api)
 
-If you need to rebuild the native module:
+## Contributing
 
 ```bash
-# Install Rust toolchain
-curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
-
 # Clone repository
 git clone https://github.com/ruvnet/ruvector.git
 cd ruvector
 
-# Build native module
-cd npm/packages/core
-npm run build:napi
-
-# Build wrapper package
-cd ../ruvector
+# Install dependencies
 npm install
-npm run build
 
 # Run tests
 npm test
-```
-
-**Requirements:**
-- Rust 1.77+
-- Node.js 18+
-- Cargo
-
-## 🌍 Ecosystem
-
-### Related Packages
-
-- **[ruvector-core](https://www.npmjs.com/package/ruvector-core)** - Core native bindings (lower-level API)
-- **[ruvector-wasm](https://www.npmjs.com/package/ruvector-wasm)** - WebAssembly implementation for browsers
-- **[ruvector-cli](https://www.npmjs.com/package/ruvector-cli)** - Standalone CLI tools
-
-### Platform-Specific Packages (auto-installed)
-
-- **[ruvector-core-linux-x64-gnu](https://www.npmjs.com/package/ruvector-core-linux-x64-gnu)**
-- **[ruvector-core-linux-arm64-gnu](https://www.npmjs.com/package/ruvector-core-linux-arm64-gnu)**
-- **[ruvector-core-darwin-x64](https://www.npmjs.com/package/ruvector-core-darwin-x64)**
-- **[ruvector-core-darwin-arm64](https://www.npmjs.com/package/ruvector-core-darwin-arm64)**
-- **[ruvector-core-win32-x64-msvc](https://www.npmjs.com/package/ruvector-core-win32-x64-msvc)**
 
-## 🐛 Troubleshooting
-
-### Native Module Not Loading
-
-If you see "Cannot find module 'ruvector-core-*'":
-
-```bash
-# Reinstall with optional dependencies
-npm install --include=optional ruvector
-
-# Verify platform
-npx ruvector info
-
-# Check Node.js version (18+ required)
-node --version
+# Build
+npm run build
 ```
 
-### WASM Fallback Performance
-
-If you're using WASM fallback and need better performance:
-
-1. **Install native toolchain** for your platform
-2. **Rebuild native module**: `npm rebuild ruvector`
-3. **Verify native**: `npx ruvector info` should show "native (Rust)"
+See [CONTRIBUTING.md](https://github.com/ruvnet/ruvector/blob/main/docs/development/CONTRIBUTING.md) for guidelines.
 
-### Platform Compatibility
+## License
 
-- **Alpine Linux**: Uses WASM fallback (musl not supported)
-- **Windows ARM**: Not yet supported, uses WASM fallback
-- **Node.js < 18**: Not supported, upgrade to Node.js 18+
-
-## 📚 Documentation
-
-- 🏠 [Homepage](https://ruv.io)
-- 📦 [GitHub Repository](https://github.com/ruvnet/ruvector)
-- 📚 [Full Documentation](https://github.com/ruvnet/ruvector/tree/main/docs)
-- 🚀 [Getting Started Guide](https://github.com/ruvnet/ruvector/blob/main/docs/guide/GETTING_STARTED.md)
-- 📖 [API Reference](https://github.com/ruvnet/ruvector/blob/main/docs/api/NODEJS_API.md)
-- 🎯 [Performance Tuning](https://github.com/ruvnet/ruvector/blob/main/docs/optimization/PERFORMANCE_TUNING_GUIDE.md)
-- 🐛 [Issue Tracker](https://github.com/ruvnet/ruvector/issues)
-- 💬 [Discussions](https://github.com/ruvnet/ruvector/discussions)
-
-## 🤝 Contributing
-
-We welcome contributions! See [CONTRIBUTING.md](https://github.com/ruvnet/ruvector/blob/main/docs/development/CONTRIBUTING.md) for guidelines.
-
-### Quick Start
-
-1. Fork the repository
-2. Create a feature branch: `git checkout -b feature/amazing-feature`
-3. Commit changes: `git commit -m 'Add amazing feature'`
-4. Push to branch: `git push origin feature/amazing-feature`
-5. Open a Pull Request
-
-## 🌐 Community & Support
-
-- **GitHub**: [github.com/ruvnet/ruvector](https://github.com/ruvnet/ruvector) - ⭐ Star and follow
-- **Discord**: [Join our community](https://discord.gg/ruvnet) - Chat with developers
-- **Twitter**: [@ruvnet](https://twitter.com/ruvnet) - Follow for updates
-- **Issues**: [Report bugs](https://github.com/ruvnet/ruvector/issues)
-
-### Enterprise Support
-
-Need custom development or consulting?
-
-📧 [enterprise@ruv.io](mailto:enterprise@ruv.io)
-
-## 📜 License
-
-**MIT License** - see [LICENSE](https://github.com/ruvnet/ruvector/blob/main/LICENSE) for details.
-
-Free for commercial and personal use.
-
-## 🙏 Acknowledgments
-
-Built with battle-tested technologies:
-
-- **HNSW**: Hierarchical Navigable Small World graphs
-- **SIMD**: Hardware-accelerated vector operations via simsimd
-- **Rust**: Memory-safe, zero-cost abstractions
-- **NAPI-RS**: High-performance Node.js bindings
-- **WebAssembly**: Universal browser compatibility
+MIT License — free for commercial and personal use.
 
 ---
 
 <div align="center">
 
-**Built with ❤️ by [rUv](https://ruv.io)**
-
-[![npm](https://img.shields.io/npm/v/ruvector.svg)](https://www.npmjs.com/package/ruvector)
-[![GitHub Stars](https://img.shields.io/github/stars/ruvnet/ruvector?style=social)](https://github.com/ruvnet/ruvector)
-[![Twitter](https://img.shields.io/twitter/follow/ruvnet?style=social)](https://twitter.com/ruvnet)
+**Built by [rUv](https://ruv.io)** • [GitHub](https://github.com/ruvnet/ruvector) • [npm](https://npmjs.com/package/ruvector)
 
-**[Get Started](https://github.com/ruvnet/ruvector/blob/main/docs/guide/GETTING_STARTED.md)** • **[Documentation](https://github.com/ruvnet/ruvector/tree/main/docs)** • **[API Reference](https://github.com/ruvnet/ruvector/blob/main/docs/api/NODEJS_API.md)** • **[Contributing](https://github.com/ruvnet/ruvector/blob/main/docs/development/CONTRIBUTING.md)**
+*Vector search that gets smarter over time.*
 
 </div>