embedvec — High-Performance Embedded Vector Database

The fastest pure-Rust vector database — HNSW indexing, SIMD acceleration, E8 and H4 lattice quantization, and flexible persistence (Sled, RocksDB, or PostgreSQL/pgvector).

Why embedvec Over the Competition?

Key Advantages

1. 10-100× Lower Latency — No network round-trips. embedvec runs in your process. Sub-millisecond queries are the norm, not the exception.

2. Up to 16× Less Memory — E8 and H4 lattice quantization (from QuIP#/QTIP research) achieve 1.25–1.73 bits/dimension with <5% recall loss. Store 1M 768-dim vectors in ~196 MB instead of 3 GB.

3. No Infrastructure — No Docker, no Kubernetes, no managed service bills. Just cargo add embedvec. Perfect for edge devices, mobile, WASM, and serverless.

4. Scale When Ready — Start embedded, then seamlessly migrate to PostgreSQL/pgvector for distributed deployments without changing your code.

5. True Rust Safety — No unsafe FFI, no C++ dependencies (unless you opt into RocksDB). Memory-safe, thread-safe, and panic-free.

When to Use embedvec

Why embedvec?

• Pure Rust — No C++ dependencies (unless using RocksDB/pgvector), safe and portable
• Blazing Fast — AVX2/FMA SIMD acceleration, optimized HNSW with O(1) lookups
• Memory Efficient — H4 (~15.7×) and E8 (~24.8×) quantization with <5% recall loss
• Two Lattice Modes — E8 (8D, 240 roots) for maximum compression; H4 (4D, 600-cell) for fast decoding
• Flexible Persistence — Sled (pure Rust), RocksDB (high perf), or PostgreSQL/pgvector (distributed)
• Production Ready — Async API, metadata filtering, batch operations

Benchmarks

All measurements on 768-dimensional vectors. Run cargo bench -- lattice to reproduce.

Lattice Quantization Comparison (768-dim, 100 vectors per batch)

H4 search is fast because HNSW indexes the raw float vector at insert time; the quantized H4 representation is used for storage only. E8 search decodes each candidate during HNSW graph traversal, adding decode overhead per distance call.

Core Operations (768-dim, 10k dataset, AVX2)

Memory Usage at Scale (768-dim vectors)

Core Features

Quick Start — Rust

[dependencies]
embedvec = "0.6"
tokio = { version = "1.0", features = ["rt-multi-thread", "macros"] }
serde_json = "1.0"

use embedvec::{Distance, EmbedVec, FilterExpr, Quantization};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // H4: best balance of compression (15.7×) and fast decode
    let mut db = EmbedVec::builder()
        .dimension(768)
        .metric(Distance::Cosine)
        .m(32)
        .ef_construction(200)
        .quantization(Quantization::h4_default())  // 15.7× memory savings
        .build()
        .await?;

    // Or E8 for maximum compression (24.8×) at the cost of slower encode/search
    // .quantization(Quantization::e8_default())

    // Add vectors with metadata
    let vectors = vec![vec![0.1; 768], vec![0.2; 768]];
    let payloads = vec![
        serde_json::json!({"doc_id": "123", "category": "finance", "timestamp": 1737400000}),
        serde_json::json!({"doc_id": "456", "category": "tech",    "timestamp": 1737500000}),
    ];
    db.add_many(&vectors, payloads).await?;

    // Search with metadata filter
    let filter = FilterExpr::eq("category", "finance")
        .and(FilterExpr::gt("timestamp", 1730000000));

    let results = db.search(&vec![0.15; 768], 10, 128, Some(filter)).await?;

    for hit in results {
        println!("id: {}, score: {:.4}, payload: {:?}", hit.id, hit.score, hit.payload);
    }
    Ok(())
}

Quick Start — Python

pip install embedvec-py

import embedvec_py
import numpy as np

# Create database with H4 quantization (15.7× memory savings, fast decode)
db = embedvec_py.EmbedVec(
    dim=768,
    metric="cosine",
    m=32,
    ef_construction=200,
    quantization="h4",     # or None, "e8-10bit", "e8-8bit", "e8-12bit"
    persist_path=None,
)

vectors = np.random.randn(50000, 768).tolist()
payloads = [{"doc_id": str(i), "tag": "news" if i % 3 == 0 else "blog"}
            for i in range(50000)]
db.add_many(vectors, payloads)

query = np.random.randn(768).tolist()
hits = db.search(query_vector=query, k=10, ef_search=128, filter={"tag": "news"})

for hit in hits:
    print(f"score: {hit['score']:.4f}  id: {hit['id']}  {hit['payload']}")

API Reference

EmbedVec Builder

EmbedVec::builder()
    .dimension(768)                         // Vector dimension (required)
    .metric(Distance::Cosine)               // Distance metric
    .m(32)                                  // HNSW M parameter
    .ef_construction(200)                   // HNSW build parameter
    .quantization(Quantization::h4_default()) // None | h4_default() | e8_default()
    .persistence("path/to/db")             // Optional disk persistence
    .build()
    .await?;

Core Operations

FilterExpr — Composable Filters

FilterExpr::eq("category", "finance")
FilterExpr::gt("timestamp", 1730000000)
FilterExpr::gte("score", 0.5)
FilterExpr::lt("price", 100)
FilterExpr::contains("name", "test")
FilterExpr::starts_with("path", "/api")
FilterExpr::in_values("status", vec!["active", "pending"])
FilterExpr::exists("optional_field")

// Boolean composition
FilterExpr::eq("a", 1)
    .and(FilterExpr::eq("b", 2))
    .or(FilterExpr::not(FilterExpr::eq("c", 3)))

Quantization Reference

Choosing a Mode

H4 — 4D 600-Cell Lattice

// Default: Hadamard preprocessing, reproducible seed
Quantization::h4_default()

// Custom
Quantization::H4 {
    use_hadamard: true,
    random_seed: 0xdeadbeef,
}

The H4 quantizer maps each 4D block to the nearest vertex of the regular 600-cell polytope (120 vertices with icosahedral symmetry). Each block is stored as a single u8 index.

• ~1.73 bits/dimension effective
• 15.7× compression vs raw f32 at 768 dimensions
• Fast decode: table lookup + 4D Hadamard inverse (~2.5 µs per vector)

E8 — 8D D8 Lattice

// Default: 10-bit, Hadamard preprocessing
Quantization::e8_default()

// Custom bit-depth
Quantization::E8 {
    bits_per_block: 10,   // 8, 10, or 12
    use_hadamard: true,
    random_seed: 0xcafef00d,
}

The E8 quantizer uses the D8 ∪ (D8 + ½) double-cover decomposition to find the nearest E8 lattice point per 8D block. Achieves maximum compression density.

• ~1.25 bits/dimension effective
• 24.8× compression vs raw f32 at 768 dimensions
• Slower decode than H4 due to 8D parity reconstruction

E8 and H4 Lattice Quantization

Both quantizers implement the same pipeline:

1. Random Sign Preprocessing — Multiply each coordinate by ±1 from a seeded PRNG
2. Hadamard Transform — Fast Walsh-Hadamard transform decorrelates coordinates
3. Scale Normalization — Global scale factor computed per vector
4. Nearest Lattice Point — Exhaustive search over roots (E8: 240, H4: 120)
5. Compact Storage — E8: u16 code + f32 scale; H4: u8 index per 4D block + f32 scale
6. Asymmetric Search — Query stays FP32; database decoded on-the-fly

Based on QuIP#/NestQuant/QTIP research (2024–2025).

Performance

Projected Performance at Scale

Feature Flags

[dependencies]
embedvec = { version = "0.6", features = ["persistence-sled", "async"] }

Persistence Backends

Sled (Default)

Pure Rust embedded database.

let db = EmbedVec::with_persistence("/path/to/db", 768, Distance::Cosine, 32, 200).await?;

RocksDB (Optional)

embedvec = { version = "0.6", features = ["persistence-rocksdb", "async"] }

let config = BackendConfig::new("/path/to/db")
    .backend(BackendType::RocksDb)
    .cache_size(256 * 1024 * 1024);
let db = EmbedVec::with_backend(config, 768, Distance::Cosine, 32, 200).await?;

pgvector (PostgreSQL)

embedvec = { version = "0.6", features = ["persistence-pgvector", "async"] }

let config = BackendConfig::pgvector("postgresql://user:pass@localhost/mydb", 768)
    .table_name("my_vectors")
    .index_type("hnsw");
let backend = PgVectorBackend::connect(&config).await?;

Testing

cargo test

# Lattice comparison benchmarks only
cargo bench -- lattice

# Full benchmark suite
cargo bench

Roadmap

• v0.6 (current): H4 lattice quantization, E8 fixes, lattice benchmark suite
• v0.7: Delete support, batch queries, LangChain/LlamaIndex integration
• Future: Hybrid sparse-dense, full-text + vector, SIMD-accelerated lattice decode

License

MIT OR Apache-2.0

Contributing

Contributions welcome! Please read CONTRIBUTING.md before submitting PRs.

Acknowledgments

• HNSW algorithm: Malkov & Yashunin (2016)
• E8 quantization: Inspired by QuIP#, NestQuant, QTIP (2024–2025)
• H4 quantization: Regular 600-cell polytope (icosahedral symmetry in ℝ⁴)
• Rust ecosystem: serde, tokio, pyo3, sled

embedvec — The "SQLite of vector search" for Rust-first teams in 2026.