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 with production-grade Rust performance and intelligent platform detection—automatically uses native bindings when available, falls back to WebAssembly when needed.

🌐 Visit ruv.io | 📦 GitHub | 📚 Documentation

🧠 Claude Code Intelligence v2.0

Self-learning intelligence for Claude Code — RuVector provides optimized hooks with ONNX embeddings, AST analysis, and coverage-aware routing.

# One-command setup with pretrain and agent generation
npx ruvector hooks init --pretrain --build-agents quality

Core Features

• 🎯 Smart Agent Routing — Q-learning optimized suggestions with 80%+ accuracy
• 📚 9-Phase Pretrain — AST, diff, coverage, neural, and graph analysis
• 🤖 Agent Builder — Generates optimized .claude/agents/ configs
• 🔗 Co-edit Patterns — Learns file relationships from git history
• 💾 Vector Memory — HNSW-indexed semantic recall (150x faster)

New in v2.0

• ⚡ ONNX WASM Embeddings — all-MiniLM-L6-v2 (384d) runs locally, no API needed
• 🌳 AST Analysis — Symbol extraction, complexity metrics, import graphs
• 📊 Diff Embeddings — Semantic change classification with risk scoring
• 🧪 Coverage Routing — Test coverage-aware agent selection
• 🔍 Graph Algorithms — MinCut boundaries, Louvain communities, Spectral clustering
• 🛡️ Security Scanning — Parallel vulnerability pattern detection
• 🎯 RAG Context — Semantic retrieval with HNSW indexing

Performance

| Backend | Read Time | Speedup | |---------|-----------|---------| | ONNX inference | ~400ms | baseline | | HNSW search | ~0.045ms | 8,800x | | Memory cache | ~0.01ms | 40,000x |

📖 Full Hooks Documentation →

MCP Server Integration

RuVector includes an MCP server for Claude Code with 103 tools:

# Add to Claude Code
claude mcp add ruvector -- npx ruvector mcp start

Available MCP Tools:

• hooks_route, hooks_route_enhanced — Agent routing with signals
• hooks_ast_analyze, hooks_ast_complexity — Code structure analysis
• hooks_diff_analyze, hooks_diff_classify — Change classification
• hooks_coverage_route, hooks_coverage_suggest — Test-aware routing
• hooks_graph_mincut, hooks_graph_cluster — Code boundaries
• hooks_security_scan — Vulnerability detection
• hooks_rag_context — Semantic context retrieval
• hooks_attention_info, hooks_gnn_info — Neural capabilities
• brain_search, brain_share, brain_status — Shared brain knowledge
• brain_agi_status, brain_sona_stats, brain_temporal, brain_explore — AGI diagnostics
• brain_midstream, brain_flags — Midstream platform + feature flags
• midstream_status, midstream_attractor, midstream_scheduler — Streaming analysis
• midstream_benchmark, midstream_search, midstream_health — Latency benchmarks + health

Brain AGI Commands

Access all 8 AGI subsystems deployed at π.ruv.io:

npx ruvector brain agi status          # Combined AGI + midstream diagnostics
npx ruvector brain agi sona            # SONA patterns, trajectories, ticks
npx ruvector brain agi temporal        # Knowledge evolution velocity
npx ruvector brain agi explore         # Meta-learning curiosity & regret
npx ruvector brain agi midstream       # Scheduler, attractor, solver, strange-loop
npx ruvector brain agi flags           # Feature flag state

Midstream Commands

Real-time streaming analysis platform:

npx ruvector midstream status          # Platform overview
npx ruvector midstream attractor       # Lyapunov attractor analysis
npx ruvector midstream scheduler       # Nanosecond scheduler metrics
npx ruvector midstream benchmark       # Latency benchmark (p50/p90/p99)

🌟 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

⚡ 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

🧠 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

🌍 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

💰 Zero Operational Costs

• No cloud API fees or usage limits
• No infrastructure to manage
• No separate database servers
• Open source MIT license

Key Advantages

• ⚡ 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

🚀 Quick Start Tutorial

Step 1: Installation

Install Ruvector with a single npm command:

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

Windows Installation (without build tools):

# Skip native compilation, use WASM fallback
npm install ruvector --ignore-scripts

# The ONNX WASM runtime (7.4MB) works without build tools
# Memory cache provides 40,000x speedup over inference

Verify installation:

npx ruvector info

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:

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}`);
}

// Run the tutorial
tutorial().catch(console.error);

Expected Output:

✅ Database created successfully
✅ Inserted: doc1
✅ Inserted: doc2
✅ Inserted: doc3

🔍 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

📄 Retrieved document: Artificial intelligence and machine learning

📊 Total vectors in database: 3

🗑️  Deleted doc1: Success
📊 Final count: 2

Step 3: TypeScript Tutorial

Ruvector provides full TypeScript support with complete type safety. Here's how to use it:

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[];
}

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}`);
  }
}

typescriptTutorial().catch(console.error);

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:

const { getImplementationType, isNative, isWasm } = require('ruvector');

console.log(getImplementationType()); // 'native' or 'wasm'
console.log(isNative()); // true if using native Rust
console.log(isWasm()); // true if using WebAssembly fallback

// 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:

Create Database

# 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)

Insert Vectors

# 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": {...} }
# ]

Search Vectors

# Search for similar vectors
npx ruvector search mydb.vec --vector "[0.1,0.2,0.3,...]" --top-k 10

# Options:
#   --vector, -v   Query vector (JSON array)
#   --top-k, -k    Number of results (default: 10)
#   --threshold    Minimum similarity score

Database Statistics

# Show database statistics
npx ruvector stats mydb.vec

# Output:
#   Total vectors: 10,000
#   Dimensions: 384
#   Metric: cosine
#   Memory usage: ~500 KB
#   Index type: HNSW

Benchmarking

# Run performance benchmark
npx ruvector benchmark --num-vectors 10000 --num-queries 1000

# Options:
#   --num-vectors   Number of vectors to insert
#   --num-queries   Number of search queries
#   --dimensions    Vector dimensionality (default: 128)

System Information

# Show platform and implementation info
npx ruvector info

# Output:
#   Platform: linux-x64-gnu
#   Implementation: native (Rust)
#   GNN Module: Available
#   Node.js: v18.17.0
#   Performance: <0.5ms p50 latency

Install Optional Packages

Ruvector supports optional packages that extend functionality. Use the install command to add them:

# List available packages
npx ruvector install

# Output:
#   Available Ruvector Packages:
#
#     gnn      not installed
#              Graph Neural Network layers, tensor compression, differentiable search
#              npm: @ruvector/gnn
#
#     core     ✓ installed
#              Core vector database with native Rust bindings
#              npm: @ruvector/core

# Install specific package
npx ruvector install gnn

# Install all optional packages
npx ruvector install --all

# Interactive selection
npx ruvector install -i

The install command auto-detects your package manager (npm, yarn, pnpm, bun).

GNN Commands

Ruvector includes Graph Neural Network (GNN) capabilities for advanced tensor compression and differentiable search.

GNN Info

# Show GNN module information
npx ruvector gnn info

# Output:
#   GNN Module Information
#     Status:         Available
#     Platform:       linux
#     Architecture:   x64
#
#   Available Features:
#     • RuvectorLayer   - GNN layer with multi-head attention
#     • TensorCompress  - Adaptive tensor compression (5 levels)
#     • differentiableSearch - Soft attention-based search
#     • hierarchicalForward  - Multi-layer GNN processing

GNN Layer

# Create and test a GNN layer
npx ruvector gnn layer -i 128 -h 256 --test

# Options:
#   -i, --input-dim   Input dimension (required)
#   -h, --hidden-dim  Hidden dimension (required)
#   -a, --heads       Number of attention heads (default: 4)
#   -d, --dropout     Dropout rate (default: 0.1)
#   --test            Run a test forward pass
#   -o, --output      Save layer config to JSON file

GNN Compress

# Compress embeddings using adaptive tensor compression
npx ruvector gnn compress -f embeddings.json -l pq8 -o compressed.json

# Options:
#   -f, --file         Input JSON file with embeddings (required)
#   -l, --level        Compression level: none|half|pq8|pq4|binary (default: auto)
#   -a, --access-freq  Access frequency for auto compression (default: 0.5)
#   -o, --output       Output file for compressed data

# Compression levels:
#   none   (freq > 0.8)  - Full precision, hot data
#   half   (freq > 0.4)  - ~50% savings, warm data
#   pq8    (freq > 0.1)  - ~8x compression, cool data
#   pq4    (freq > 0.01) - ~16x compression, cold data
#   binary (freq <= 0.01) - ~32x compression, archive

GNN Search

# Differentiable search with soft attention
npx ruvector gnn search -q "[1.0,0.0,0.0]" -c candidates.json -k 5

# Options:
#   -q, --query        Query vector as JSON array (required)
#   -c, --candidates   Candidates file - JSON array of vectors (required)
#   -k, --top-k        Number of results (default: 5)
#   -t, --temperature  Softmax temperature (default: 1.0)

Attention Commands

Ruvector includes high-performance attention mechanisms for transformer-based operations, hyperbolic embeddings, and graph attention.

# Install the attention module (optional)
npm install @ruvector/attention

Attention Mechanisms Reference

| Mechanism | Type | Complexity | When to Use | |-----------|------|------------|-------------| | DotProductAttention | Core | O(n²) | Standard scaled dot-product attention for transformers | | MultiHeadAttention | Core | O(n²) | Parallel attention heads for capturing different relationships | | FlashAttention | Core | O(n²) IO-optimized | Memory-efficient attention for long sequences | | HyperbolicAttention | Core | O(n²) | Hierarchical data, tree-like structures, taxonomies | | LinearAttention | Core | O(n) | Very long sequences where O(n²) is prohibitive | | MoEAttention | Core | O(nk) | Mixture of Experts routing, specialized attention | | GraphRoPeAttention | Graph | O(n²) | Graph data with rotary position embeddings | | EdgeFeaturedAttention | Graph | O(n²) | Graphs with rich edge features/attributes | | DualSpaceAttention | Graph | O(n²) | Combined Euclidean + hyperbolic representation | | LocalGlobalAttention | Graph | O(nk) | Large graphs with local + global context |

Attention Info

# Show attention module information
npx ruvector attention info

# Output:
#   Attention Module Information
#     Status:         Available
#     Version:        0.1.0
#     Platform:       linux
#     Architecture:   x64
#
#   Core Attention Mechanisms:
#     • DotProductAttention  - Scaled dot-product attention
#     • MultiHeadAttention   - Multi-head self-attention
#     • FlashAttention       - Memory-efficient IO-aware attention
#     • HyperbolicAttention  - Poincaré ball attention
#     • LinearAttention      - O(n) linear complexity attention
#     • MoEAttention         - Mixture of Experts attention

Attention List

# List all available attention mechanisms
npx ruvector attention list

# With verbose details
npx ruvector attention list -v

Attention Benchmark

# Benchmark attention mechanisms
npx ruvector attention benchmark -d 256 -n 100 -i 100

# Options:
#   -d, --dimension     Vector dimension (default: 256)
#   -n, --num-vectors   Number of vectors (default: 100)
#   -i, --iterations    Benchmark iterations (default: 100)
#   -t, --types         Attention types to benchmark (default: dot,flash,linear)

# Example output:
#   Dimension:    256
#   Vectors:      100
#   Iterations:   100
#
#   dot:   0.012ms/op (84,386 ops/sec)
#   flash: 0.012ms/op (82,844 ops/sec)
#   linear: 0.066ms/op (15,259 ops/sec)

Hyperbolic Operations

# Calculate Poincaré distance between two points
npx ruvector attention hyperbolic -a distance -v "[0.1,0.2,0.3]" -b "[0.4,0.5,0.6]"

# Project vector to Poincaré ball
npx ruvector attention hyperbolic -a project -v "[1.5,2.0,0.8]"

# Möbius addition in hyperbolic space
npx ruvector attention hyperbolic -a mobius-add -v "[0.1,0.2]" -b "[0.3,0.4]"

# Exponential map (tangent space → Poincaré ball)
npx ruvector attention hyperbolic -a exp-map -v "[0.1,0.2,0.3]"

# Options:
#   -a, --action      Action: distance|project|mobius-add|exp-map|log-map
#   -v, --vector      Input vector as JSON array (required)
#   -b, --vector-b    Second vector for binary operations
#   -c, --curvature   Poincaré ball curvature (default: 1.0)

When to Use Each Attention Type

| Use Case | Recommended Attention | Reason | |----------|----------------------|--------| | Standard NLP/Transformers | MultiHeadAttention | Industry standard, well-tested | | Long Documents (>4K tokens) | FlashAttention or LinearAttention | Memory efficient | | Hierarchical Classification | HyperbolicAttention | Captures tree-like structures | | Knowledge Graphs | GraphRoPeAttention | Position-aware graph attention | | Multi-Relational Graphs | EdgeFeaturedAttention | Leverages edge attributes | | Taxonomy/Ontology Search | DualSpaceAttention | Best of both Euclidean + hyperbolic | | Large-Scale Graphs | LocalGlobalAttention | Efficient local + global context | | Model Routing/MoE | MoEAttention | Expert selection and routing |

⚡ ONNX WASM Embeddings (v2.0)

RuVector includes a pure JavaScript ONNX runtime for local embeddings - no Python, no API calls, no build tools required.

# Embeddings work out of the box
npx ruvector hooks remember "important context" -t project
npx ruvector hooks recall "context query"
npx ruvector hooks rag-context "how does auth work"

Model: all-MiniLM-L6-v2 (384 dimensions, 23MB)

• Downloads automatically on first use
• Cached in .ruvector/models/
• SIMD-accelerated when available

Performance: | Operation | Time | Notes | |-----------|------|-------| | Model load | ~2s | First use only | | Embedding | ~50ms | Per text chunk | | HNSW search | 0.045ms | 150x faster than brute force | | Cache hit | 0.01ms | 40,000x faster than inference |

Fallback Chain:

1. Native SQLite → best persistence
2. WASM SQLite → cross-platform
3. Memory Cache → fastest (no persistence)

🧠 Self-Learning Hooks v2.0

Ruvector includes self-learning intelligence hooks for Claude Code integration with ONNX embeddings, AST analysis, and coverage-aware routing.

Initialize Hooks

# Initialize hooks in your project
npx ruvector hooks init

# Options:
#   --force      Overwrite existing configuration
#   --minimal    Minimal configuration (no optional hooks)
#   --pretrain   Initialize + pretrain from git history
#   --build-agents quality  Generate optimized agent configs

This creates .claude/settings.json with pre-configured hooks and CLAUDE.md with comprehensive documentation.

Session Management

# Start a session (load intelligence data)
npx ruvector hooks session-start

# End a session (save learned patterns)
npx ruvector hooks session-end

Pre/Post Edit Hooks

# Before editing a file - get agent recommendations
npx ruvector hooks pre-edit src/index.ts
# Output: 🤖 Recommended: typescript-developer (85% confidence)

# After editing - record success/failure for learning
npx ruvector hooks post-edit src/index.ts --success
npx ruvector hooks post-edit src/index.ts --error "Type error on line 42"

Pre/Post Command Hooks

# Before running a command - risk analysis
npx ruvector hooks pre-command "npm test"
# Output: ✅ Risk: LOW, Category: test

# After running - record outcome
npx ruvector hooks post-command "npm test" --success
npx ruvector hooks post-command "npm test" --error "3 tests failed"

Agent Routing

# Get agent recommendation for a task
npx ruvector hooks route "fix the authentication bug in login.ts"
# Output: 🤖 Recommended: security-specialist (92% confidence)

npx ruvector hooks route "add unit tests for the API"
# Output: 🤖 Recommended: tester (88% confidence)

Memory Operations

# Store context in vector memory
npx ruvector hooks remember "API uses JWT tokens with 1h expiry" --type decision
npx ruvector hooks remember "Database schema in docs/schema.md" --type reference

# Semantic search memory
npx ruvector hooks recall "authentication mechanism"
# Returns relevant stored memories

Context Suggestions

# Get relevant context for current task
npx ruvector hooks suggest-context
# Output: Based on recent files, suggests relevant context

Intelligence Statistics

# Show learned patterns and statistics
npx ruvector hooks stats

# Output:
#   Patterns: 156 learned
#   Success rate: 87%
#   Top agents: rust-developer, tester, reviewer
#   Memory entries: 42

Swarm Recommendations

# Get agent recommendation for task type
npx ruvector hooks swarm-recommend "code-review"
# Output: Recommended agents for code review task

AST Analysis (v2.0)

# Analyze file structure, symbols, imports, complexity
npx ruvector hooks ast-analyze src/index.ts --json

# Get complexity metrics for multiple files
npx ruvector hooks ast-complexity src/*.ts --threshold 15
# Flags files exceeding cyclomatic complexity threshold

Diff & Risk Analysis (v2.0)

# Analyze commit with semantic embeddings and risk scoring
npx ruvector hooks diff-analyze HEAD
# Output: risk score, category, affected files

# Classify change type (feature, bugfix, refactor, docs, test)
npx ruvector hooks diff-classify

# Find similar past commits via embeddings
npx ruvector hooks diff-similar -k 5

# Git churn analysis (hot spots)
npx ruvector hooks git-churn --days 30

Coverage-Aware Routing (v2.0)

# Get coverage-aware routing for a file
npx ruvector hooks coverage-route src/api.ts
# Output: agent weights based on test coverage

# Suggest tests for files based on coverage gaps
npx ruvector hooks coverage-suggest src/*.ts

Graph Analysis (v2.0)

# Find optimal code boundaries (MinCut algorithm)
npx ruvector hooks graph-mincut src/*.ts

# Detect code communities (Louvain/Spectral clustering)
npx ruvector hooks graph-cluster src/*.ts --method louvain

Security & RAG (v2.0)

# Parallel security vulnerability scan
npx ruvector hooks security-scan src/*.ts

# RAG-enhanced context retrieval
npx ruvector hooks rag-context "how does auth work"

# Enhanced routing with all signals
npx ruvector hooks route-enhanced "fix bug" --file src/api.ts

Hooks Configuration

The hooks integrate with Claude Code via .claude/settings.json:

{
  "env": {
    "RUVECTOR_INTELLIGENCE_ENABLED": "true",
    "RUVECTOR_LEARNING_RATE": "0.1",
    "RUVECTOR_AST_ENABLED": "true",
    "RUVECTOR_DIFF_EMBEDDINGS": "true",
    "RUVECTOR_COVERAGE_ROUTING": "true",
    "RUVECTOR_GRAPH_ALGORITHMS": "true",
    "RUVECTOR_SECURITY_SCAN": "true"
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [{ "type": "command", "command": "npx ruvector hooks pre-edit \"$TOOL_INPUT_file_path\"" }]
      },
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "npx ruvector hooks pre-command \"$TOOL_INPUT_command\"" }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [{ "type": "command", "command": "npx ruvector hooks post-edit \"$TOOL_INPUT_file_path\"" }]
      }
    ],
    "SessionStart": [{ "hooks": [{ "type": "command", "command": "npx ruvector hooks session-start" }] }],
    "Stop": [{ "hooks": [{ "type": "command", "command": "npx ruvector hooks session-end" }] }]
  }
}

How Self-Learning Works

1. Pattern Recording: Every edit and command is recorded with context
2. Q-Learning: Success/failure updates agent routing weights
3. AST Analysis: Code complexity informs agent selection
4. Diff Embeddings: Change patterns improve risk assessment
5. Coverage Routing: Test coverage guides testing priorities
6. Vector Memory: Decisions and references stored for semantic recall (HNSW indexed)
7. Continuous Improvement: The more you use it, the smarter it gets

📊 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:

npm install ruvector openai
export OPENAI_API_KEY="your-api-key-here"

Complete Implementation:

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)
    };
  }
}

// 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(', '));
}

main().catch(console.error);

Expected Output:

✅ RAG System initialized
📚 Indexing 3 documents...
  ✅ Indexed: Ruvector Introduction
  ✅ Indexed: Vector Databases Explained
  ✅ Indexed: HNSW Algorithm

✅ Indexed 3 documents total

============================================================

🔍 Searching for: "What is Ruvector and what are its performance characteristics?"
📄 Found 2 relevant documents

🤖 Generating answer...

📝 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

📚 Sources: Ruvector Introduction, Vector Databases Explained

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

Tutorial 2: Semantic Search Engine

What you'll learn: Build a semantic search engine that understands meaning, not just keywords.

Prerequisites:

npm install ruvector @xenova/transformers

Complete Implementation:

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);
  }
}

// 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)})`);
  });
}

main().catch(console.error);

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

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.

Complete Implementation:

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}`);
}

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

📖 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

📚 Relevant knowledge:
1. navigation_strategy: Moving north then east is efficient for reaching room3 from room1 (confidence: 0.9)

============================================================
PHASE 3: Reflection
============================================================

🤔 Reflecting on experiences...
📊 Total experiences: 3
💡 Analysis complete

📊 Memory Statistics:
   Episodic memories: 3
   Semantic knowledge: 1
   Agent ID: agent-001

Use Cases:

• ✅ Reinforcement learning agents
• ✅ Chatbot conversation history
• ✅ Game AI that learns from gameplay
• ✅ Personal assistant memory
• ✅ Robotic navigation systems

🏗️ API Reference

Constructor

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')
})

Methods

insert(entry: VectorEntry): Promise

Insert a vector into the database.

const id = await db.insert({
  id: 'doc_1',
  vector: new Float32Array([0.1, 0.2, 0.3, ...]),
  metadata: { title: 'Document 1' }
});

search(query: SearchQuery): Promise<SearchResult[]>

Search for similar vectors.

const results = await db.search({
  vector: new Float32Array([0.1, 0.2, 0.3, ...]),
  k: 10,
  threshold: 0.7
});

get(id: string): Promise<VectorEntry | null>

Retrieve a vector by ID.

const entry = await db.get('doc_1');
if (entry) {
  console.log(entry.vector, entry.metadata);
}

delete(id: string): Promise

Remove a vector from the database.

const deleted = await db.delete('doc_1');
console.log(deleted ? 'Deleted' : 'Not found');

len(): Promise

Get the total number of vectors.

const count = await db.len();
console.log(`Total vectors: ${count}`);

🎨 Advanced Configuration

HNSW Parameters

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'
});

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

// Cosine similarity (default, best for normalized vectors)
const db1 = new VectorDb({
  dimensions: 128,
  distanceMetric: 'cosine'
});

// 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

// 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
});

📦 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

WASM Fallback - Universal Compatibility

• Any platform where native module isn't available
• Browser environments (experimental)
• Alpine Linux (musl) and other non-glibc systems

Performance: 10-50ms latency, ~1K ops/sec

Node.js 18+ required for all platforms.

🔧 Building from Source

If you need to rebuild the native module:

# 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
npm install
npm run build

# Run tests
npm test

Requirements:

• Rust 1.77+
• Node.js 18+
• Cargo

🌍 Ecosystem

Related Packages

• ruvector-core - Core native bindings (lower-level API)
• ruvector-wasm - WebAssembly implementation for browsers
• ruvector-cli - Standalone CLI tools
• @ruvector/rvf - RVF cognitive container SDK
• @ruvector/rvf-wasm - RVF WASM build for browsers, Deno, and edge
• rvlite - Lightweight vector database with SQL, SPARQL, and Cypher

Platform-Specific Packages (auto-installed)

• ruvector-core-linux-x64-gnu
• ruvector-core-linux-arm64-gnu
• ruvector-core-darwin-x64
• ruvector-core-darwin-arm64
• ruvector-core-win32-x64-msvc

RVF Cognitive Containers

Ruvector integrates with RVF (RuVector Format) — a universal binary substrate that stores vectors, models, graphs, compute kernels, and attestation in a single .rvf file.

Enable RVF Backend

# Install the optional RVF package
npm install @ruvector/rvf

# Set backend via environment variable
export RUVECTOR_BACKEND=rvf

# Or detect automatically (native -> rvf -> wasm fallback)
npx ruvector info

import { getImplementationType, isRvf } from 'ruvector';

console.log(getImplementationType()); // 'native' | 'rvf' | 'wasm'
console.log(isRvf()); // true if RVF backend is active

RVF CLI Commands

8 RVF-specific subcommands are available through the ruvector CLI:

# Create an RVF store
npx ruvector rvf create mydb.rvf -d 384 --metric cosine

# Ingest vectors from JSON
npx ruvector rvf ingest mydb.rvf --input vectors.json --format json

# Query nearest neighbors
npx ruvector rvf query mydb.rvf --vector "[0.1,0.2,...]" --k 10

# File status and segment listing
npx ruvector rvf status mydb.rvf
npx ruvector rvf segments mydb.rvf

# COW branching — derive a child file
npx ruvector rvf derive mydb.rvf --output child.rvf

# Compact and reclaim space
npx ruvector rvf compact mydb.rvf

# Export to JSON
npx ruvector rvf export mydb.rvf --output dump.json

RVF Platform Support

| Platform | Runtime | Backend | |----------|---------|---------| | Linux x86_64 / aarch64 | Node.js 18+ | Native (N-API) | | macOS x86_64 / arm64 | Node.js 18+ | Native (N-API) | | Windows x86_64 | Node.js 18+ | Native (N-API) | | Any | Deno | WASM (@ruvector/rvf-wasm) | | Any | Browser | WASM (@ruvector/rvf-wasm) | | Any | Cloudflare Workers | WASM (@ruvector/rvf-wasm) |

Download Example .rvf Files

45 pre-built example files are available (~11 MB total):

# Download a specific example
curl -LO https://raw.githubusercontent.com/ruvnet/ruvector/main/examples/rvf/output/basic_store.rvf

# Popular examples:
#   basic_store.rvf (152 KB)        — 1,000 vectors, dim 128
#   semantic_search.rvf (755 KB)    — Semantic search with HNSW
#   rag_pipeline.rvf (303 KB)       — RAG pipeline embeddings
#   agent_memory.rvf (32 KB)        — AI agent memory store
#   self_booting.rvf (31 KB)        — Self-booting with kernel
#   progressive_index.rvf (2.5 MB)  — Large-scale HNSW index

# Generate all examples locally
cd crates/rvf && cargo run --example generate_all

Full catalog: examples/rvf/output/

Working Examples: Cognitive Containers

Self-Booting Microservice

A single .rvf file that contains vectors AND a bootable Linux kernel:

#