Hugging Face's logo

ArchibaldAI
/
ruvector-fixed

Model card Files
xet
Community
ruvector-fixed / README.md
Archie
Fix dimension/dimensions bug and positional insert/search args
40d7073
preview code
|
raw
history blame contribute delete
71.4 kB

ruvector

npm version License: MIT Node Version Downloads Build Status Performance GitHub Stars

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 30+ 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

🌟 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(n*k) 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(n*k) 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

Platform-Specific Packages (auto-installed)

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:

# Build and run the self-booting example
cd crates/rvf && cargo run --example self_booting
# Output:
#   Ingested 50 vectors (128 dims)
#   Pre-kernel query: top-5 results OK (nearest ID=25)
#   Kernel: 4,640 bytes embedded (x86_64, Hermit)
#   Witness chain: 5 entries, all verified
#   File: bootable.rvf (31 KB) — data + runtime in one file

// The pattern: vectors + kernel + witness in one file
let mut store = RvfStore::create("bootable.rvf", options)?;
store.ingest_batch(&vectors, &ids, None)?;
store.embed_kernel(KernelArch::X86_64 as u8, KernelType::Hermit as u8,
    0x0018, &kernel_image, 8080, Some("console=ttyS0 quiet"))?;
// Result: drop on a VM and it boots as a query service

Linux Microkernel Distribution

20-package Linux distro with SSH keys and kernel in a single file:

cd crates/rvf && cargo run --example linux_microkernel
# Output:
#   Installed 20 packages as vector embeddings
#   Kernel embedded: Linux x86_64 (4,640 bytes)
#   SSH keys: Ed25519, signed and verified
#   Witness chain: 22 entries (1 per package + kernel + SSH)
#   File: microkernel.rvf (14 KB) — immutable bootable system

Features: package search by embedding similarity, Ed25519 signed SSH keys, witness-audited installs, COW-derived child images for atomic updates.

Claude Code AI Appliance

A sealed, bootable AI development environment:

cd crates/rvf && cargo run --example claude_code_appliance
# Output:
#   20 dev packages (rust, node, python, docker, ...)
#   Kernel: Linux x86_64 with SSH on port 2222
#   eBPF: XDP distance program for fast-path lookups
#   Witness chain: 6 entries, all verified
#   Crypto: Ed25519 signature
#   File: claude_code_appliance.rvf (17 KB)

CLI Full Lifecycle 

# Create → Ingest → Query → Derive → Inspect
rvf create vectors.rvf --dimension 384
rvf ingest vectors.rvf --input data.json --format json
rvf query vectors.rvf --vector "0.1,0.2,..." --k 10
rvf derive vectors.rvf child.rvf --type filter
rvf inspect vectors.rvf

# Embed kernel and launch as microVM
rvf embed-kernel vectors.rvf --image bzImage
rvf launch vectors.rvf --port 8080

# Verify tamper-evident witness chain
rvf verify-witness vectors.rvf
rvf verify-attestation vectors.rvf

Integration Tests (46 passing) 

cd crates/rvf
cargo test --workspace
# attestation .............. 6 passed
# crypto ................... 10 passed
# computational_container .. 8 passed
# cow_branching ............ 8 passed
# cross_platform ........... 6 passed
# lineage .................. 4 passed
# smoke .................... 4 passed
# Total: 46/46 passed

🐛 Troubleshooting

Native Module Not Loading

If you see "Cannot find module 'ruvector-core-*'":

# Reinstall with optional dependencies
npm install --include=optional ruvector

# Verify platform
npx ruvector info

# Check Node.js version (18+ required)
node --version

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

Platform Compatibility

  • 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

🤝 Contributing

We welcome contributions! See 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

Enterprise Support

Need custom development or consulting?

📧 enterprise@ruv.io

📜 License

MIT License - see 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

Built with ❤️ by rUv

npm GitHub Stars Twitter

Get Started • Documentation • API Reference • Contributing