Self-learning vector database for Node.js — hybrid search, Graph RAG, FlashAttention-3, DiskANN, 50+ attention mechanisms
The fastest vector database for Node.js—built in Rust, runs everywhere
Ruvector is a self-learning vector database with enterprise-grade semantic search, hybrid retrieval (sparse + dense), Graph RAG, FlashAttention-3, and billion-scale DiskANN — all in a single npm package. Unlike cloud-only solutions or Python-first databases, Ruvector is designed for JavaScript/TypeScript developers who need blazing-fast vector search without external services.
🚀 Sub-millisecond queries • 🎯 52,000+ inserts/sec • 💾 ~50 bytes per vector • 🌍 Runs anywhere • 🧠 859 tests passing
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
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
.claude/agents/ configs| Backend | Read Time | Speedup |
|---|---|---|
| ONNX inference | ~400ms | baseline |
| HNSW search | ~0.045ms | 8,800x |
| Memory cache | ~0.01ms | 40,000x |
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 signalshooks_ast_analyze, hooks_ast_complexity — Code structure analysishooks_diff_analyze, hooks_diff_classify — Change classificationhooks_coverage_route, hooks_coverage_suggest — Test-aware routinghooks_graph_mincut, hooks_graph_cluster — Code boundarieshooks_security_scan — Vulnerability detectionhooks_rag_context — Semantic context retrievalhooks_attention_info, hooks_gnn_info — Neural capabilitiesbrain_search, brain_share, brain_status — Shared brain knowledgebrain_agi_status, brain_sona_stats, brain_temporal, brain_explore — AGI diagnosticsbrain_midstream, brain_flags — Midstream platform + feature flagsmidstream_status, midstream_attractor, midstream_scheduler — Streaming analysismidstream_benchmark, midstream_search, midstream_health — Latency benchmarks + healthAccess 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
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)
Most vector databases force you to choose between three painful trade-offs:
Ruvector eliminates these trade-offs.
Ruvector is purpose-built for modern JavaScript/TypeScript applications that need vector search:
🎯 Native Node.js Integration
⚡ Production-Grade Performance
🧠 Built for AI Applications
🌍 Universal Deployment
💰 Zero Operational Costs
Install Ruvector with a single npm command:
npm install ruvector
What happens during installation:
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).
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
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:
any types - fully typed throughoutRuvector 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
Ruvector includes a full command-line interface for database management:
# 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 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 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
# Show database statistics
npx ruvector stats mydb.vec
# Output:
# Total vectors: 10,000
# Dimensions: 384
# Metric: cosine
# Memory usage: ~500 KB
# Index type: HNSW
# 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)
# 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
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).
Ruvector includes Graph Neural Network (GNN) capabilities for advanced tensor compression and differentiable search.
# 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
# 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
# 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
# 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)
Ruvector includes high-performance attention mechanisms for transformer-based operations, hyperbolic embeddings, and graph attention.
# Install the attention module (optional)
npm install @ruvector/attention
| 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 |
# 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
# List all available attention mechanisms
npx ruvector attention list
# With verbose details
npx ruvector attention list -v
# 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)
# 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)
| 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 |
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)
.ruvector/models/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:
Ruvector includes self-learning intelligence hooks for Claude Code integration with ONNX embeddings, AST analysis, and coverage-aware routing.
# 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.
# Start a session (load intelligence data)
npx ruvector hooks session-start
# End a session (save learned patterns)
npx ruvector hooks session-end
# 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"
# 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"
# 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)
# 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
# Get relevant context for current task
npx ruvector hooks suggest-context
# Output: Based on recent files, suggests relevant context
# 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
# Get agent recommendation for task type
npx ruvector hooks swarm-recommend "code-review"
# Output: Recommended agents for code review task
# 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
# 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
# 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
# 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
# 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
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" }] }]
}
}
Tested on AMD Ryzen 9 5950X, 128-dimensional vectors:
| 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)
| 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
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 |
✅ Perfect for:
⚠️ Consider alternatives for:
vs Pinecone:
vs ChromaDB:
vs Qdrant:
vs Faiss:
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:
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:
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:
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')
})
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 for similar vectors.
const results = await db.search({
vector: new Float32Array([0.1, 0.2, 0.3, ...]),
k: 10,
threshold: 0.7
});
Retrieve a vector by ID.
const entry = await db.get('doc_1');
if (entry) {
console.log(entry.vector, entry.metadata);
}
Remove a vector from the database.
const deleted = await db.delete('doc_1');
console.log(deleted ? 'Deleted' : 'Not found');
Get the total number of vectors.
const count = await db.len();
console.log(`Total vectors: ${count}`);
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)// 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'
});
// 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
});
Automatically installs the correct implementation for:
Performance: <0.5ms latency, 50K+ ops/sec
Performance: 10-50ms latency, ~1K ops/sec
Node.js 18+ required for all platforms.
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:
Ruvector integrates with RVF (RuVector Format) — a universal binary substrate that stores vectors, models, graphs, compute kernels, and attestation in a single .rvf file.
# 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
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
| 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) |
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/
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
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.
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)
# 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
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
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
If you're using WASM fallback and need better performance:
npm rebuild ruvectornpx ruvector info should show "native (Rust)"We welcome contributions! See CONTRIBUTING.md for guidelines.
git checkout -b feature/amazing-featuregit commit -m 'Add amazing feature'git push origin feature/amazing-featureNeed custom development or consulting?
MIT License - see LICENSE for details.
Free for commercial and personal use.
Built with battle-tested technologies:
FAQs
Self-learning vector database for Node.js — hybrid search, Graph RAG, FlashAttention-3, DiskANN, 50+ attention mechanisms
The npm package ruvector receives a total of 28,220 weekly downloads. As such, ruvector popularity was classified as popular.
We found that ruvector demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.
