ruvector/docs/guides/GETTING_STARTED.md

Getting Started with Ruvector

What is Ruvector?

Ruvector is a high-performance, Rust-native vector database designed for modern AI applications. It provides:

• 10-100x performance improvements over Python/TypeScript implementations
• Sub-millisecond latency with HNSW indexing and SIMD optimization
• AgenticDB API compatibility for seamless migration
• Multi-platform deployment (Rust, Node.js, WASM/Browser, CLI)
• Advanced features including quantization, hybrid search, and causal memory

Quick Start

Installation

Rust

# Add to Cargo.toml
[dependencies]
ruvector-core = "0.1.0"

Node.js

npm install ruvector
# or
yarn add ruvector

CLI

cargo install ruvector-cli

Basic Usage

Rust

use ruvector_core::{VectorDB, VectorEntry, SearchQuery, DbOptions};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a new vector database
    let mut options = DbOptions::default();
    options.dimensions = 128;
    options.storage_path = "./vectors.db".to_string();

    let db = VectorDB::new(options)?;

    // Insert a vector
    let entry = VectorEntry {
        id: None,
        vector: vec![0.1; 128],
        metadata: None,
    };
    let id = db.insert(entry)?;
    println!("Inserted vector: {}", id);

    // Search for similar vectors
    let query = SearchQuery {
        vector: vec![0.1; 128],
        k: 10,
        filter: None,
        include_vectors: false,
    };
    let results = db.search(&query)?;

    for (i, result) in results.iter().enumerate() {
        println!("{}. ID: {}, Distance: {}", i + 1, result.id, result.distance);
    }

    Ok(())
}

Node.js

const { VectorDB } = require('ruvector');

async function main() {
    // Create a new vector database
    const db = new VectorDB({
        dimensions: 128,
        storagePath: './vectors.db',
        distanceMetric: 'cosine'
    });

    // Insert a vector
    const id = await db.insert({
        vector: new Float32Array(128).fill(0.1),
        metadata: { text: 'Example document' }
    });
    console.log('Inserted vector:', id);

    // Search for similar vectors
    const results = await db.search({
        vector: new Float32Array(128).fill(0.1),
        k: 10
    });

    results.forEach((result, i) => {
        console.log(`${i + 1}. ID: ${result.id}, Distance: ${result.distance}`);
    });
}

main().catch(console.error);

CLI

# Create a database
ruvector create --path ./vectors.db --dimensions 128

# Insert vectors from a JSON file
ruvector insert --db ./vectors.db --input vectors.json --format json

# Search for similar vectors
ruvector search --db ./vectors.db --query "[0.1, 0.2, ...]" --top-k 10

# Show database info
ruvector info --db ./vectors.db

Core Concepts

1. Vector Database

A vector database stores high-dimensional vectors (embeddings) and enables fast similarity search. Common use cases:

• Semantic search: Find similar documents, images, or audio
• Recommendation systems: Find similar products or content
• RAG (Retrieval Augmented Generation): Retrieve relevant context for LLMs
• Agent memory: Store and retrieve experiences for AI agents

2. Distance Metrics

Ruvector supports multiple distance metrics:

• Euclidean (L2): Standard distance in Euclidean space
• Cosine: Measures angle between vectors (normalized dot product)
• Dot Product: Inner product (useful for pre-normalized vectors)
• Manhattan (L1): Sum of absolute differences

3. HNSW Indexing

Hierarchical Navigable Small World (HNSW) provides:

• O(log n) search complexity
• 95%+ recall with proper tuning
• Sub-millisecond latency for millions of vectors

Key parameters:

• m: Connections per node (16-64, default 32)
• ef_construction: Build quality (100-400, default 200)
• ef_search: Search quality (50-500, default 100)

4. Quantization

Reduce memory usage with quantization:

• Scalar (int8): 4x compression, 97-99% recall
• Product: 8-16x compression, 90-95% recall
• Binary: 32x compression, 80-90% recall (filtering)

5. AgenticDB Features

Advanced features for AI agents:

• Reflexion Memory: Self-critique episodes for learning
• Skill Library: Reusable action patterns
• Causal Memory: Cause-effect relationships
• Learning Sessions: RL training data

Next Steps

• Installation Guide - Detailed installation instructions
• Basic Tutorial - Step-by-step tutorial
• Advanced Features - Hybrid search, quantization, filtering
• AgenticDB Migration Guide - Migrate from agenticDB
• API Reference - Complete API documentation
• Examples - Working code examples

Performance Tips

1. Choose the right distance metric: Cosine for normalized embeddings, Euclidean otherwise
2. Tune HNSW parameters: Higher m and ef_construction for better recall
3. Enable quantization: Reduces memory 4-32x with minimal accuracy loss
4. Batch operations: Use insert_batch() for better throughput
5. Memory-map large datasets: Set mmap_vectors: true for datasets larger than RAM

Common Issues

Out of Memory

• Enable quantization to reduce memory usage
• Use memory-mapped vectors for large datasets
• Reduce max_elements or increase available RAM

Slow Search

• Lower ef_search for faster (but less accurate) search
• Enable quantization for cache-friendly operations
• Check if SIMD is enabled (RUSTFLAGS="-C target-cpu=native")

Low Recall

• Increase ef_construction during index building
• Increase ef_search during queries
• Use full-precision vectors instead of quantization

Community & Support

• GitHub: https://github.com/ruvnet/ruvector
• Issues: https://github.com/ruvnet/ruvector/issues
• Documentation: https://docs.rs/ruvector-core

License

Ruvector is licensed under the MIT License. See LICENSE for details.