Recern Vector

A single-file vector database. Embedded, inspectable, boring in the best way.

Status: Phase 1 prototype (0.0.x). The file format and API will change between releases.

pip install recern-vector           # Python
cargo add recern-vector             # Rust library
cargo install recern-vector-cli     # the recern-vector command

Project page: recern.net/vector · Benchmark report: recern.net/vector/benchmarks

Recern Vector stores vectors, JSON metadata and an HNSW index in one file — no server, no configuration. Its internals are part of the API: every query can explain how it was executed, every collection reports its graph structure and memory, and recall can be measured against exact search at any time.

Quick start (CLI)

cargo build --release
alias rv=target/release/recern-vector

rv init docs.rvec
rv create-collection docs.rvec chunks --dim 384 --metric cosine
rv insert docs.rvec chunks chunks.jsonl     # {"id": "...", "vector": [...], "metadata": {...}} per line; --threads N

rv query docs.rvec chunks --like chunk-42 -k 5 --explain
rv query docs.rvec chunks --vector '[0.1, ...]' --filter '{"lang": "en", "year": {"$gte": 2020}}'

rv inspect docs.rvec                        # layers, degree, reachability, memory, hints
rv recall docs.rvec chunks --ef 16,32,64,128
rv delete docs.rvec chunks chunk-1 chunk-2
rv compact docs.rvec chunks

Python

import numpy as np
import recern_vector as rv

with rv.Database.open_or_create("docs.rvec") as db:          # saves on clean exit
    chunks = db.create_collection("chunks", dim=384, metric="cosine")
    chunks.upsert_many(ids, np.asarray(embeddings, dtype=np.float32), metadatas)
    hits = chunks.search(query, k=5, filter={"lang": "en"})
    print(chunks.explain(query, k=5), chunks.stats())

Build and test from crates/recern-vector-py (see its README). One abi3 wheel covers CPython 3.11+. Calls release the GIL during search, batch inserts, recall estimation and saving.

Rust API

use recern_vector::{CollectionConfig, Database, Filter, Metric, RecallOptions, SearchOptions};

let mut db = Database::open_or_create("docs.rvec")?;
let chunks = db.create_collection("chunks", CollectionConfig::new(384, Metric::Cosine))?;
chunks.upsert("chunk-1", &embedding, Some(serde_json::json!({"lang": "en"})))?;
chunks.upsert_many(records)?;                          // atomic batch, index built on all cores

let options = SearchOptions::default().filter(Filter::eq("lang", "en"));
let report = chunks.explain(&query, 10, &options)?;   // hits + strategy, visited nodes, timing
let recall = chunks.estimate_recall(&RecallOptions::default())?;
db.save()?;

What is inside

The file layout is documented in storage.rs.

Benchmark

Standard ANN-Benchmarks datasets, top-10, one query at a time from Python (after a warm-up pass), Apple M3 Max (14 cores). Full method, sweeps and reproduction: bench/RESULTS.md.

SIFT1M (1M × 128, L2) — QPS at a recall@10 target:

GloVe-100 (1.18M × 100, cosine):

Searches run on one thread for Recern Vector and faiss.

What this says about the prototype:

• Faster than the reference HNSW at equal recall: 1.2–1.3× on SIFT and 1.4–1.8× on GloVe. Recall per ef is slightly higher than faiss (denser layer-0 links), and search prefetches every neighbor's vector before computing distances, so memory loads overlap.
• Build is within 1.1–1.2× of faiss on the same cores and scales ~10× on 14 cores.
• Single-query latency is 4–21× lower than LanceDB from Python. Against sqlite-vec's exact scan it is ~760× faster on SIFT and ~90× on GloVe at recall ≥ 0.95.
• The Python layer adds about 1 µs per query (bench/profile_search.py).

cargo run --release --example bench -- [records] [dim] [noise] runs a quick synthetic sanity check without downloading datasets.

Prototype limitations

• The whole database is loaded into memory; save() rewrites the entire file (no WAL yet).
• Single writer; single upserts link sequentially (use upsert_many for bulk loads).
• f32 only; no quantization yet.
• No Node.js bindings yet.

Next steps

1. Tune filter planning: the exact-scan threshold is currently conservative
2. WAL for incremental writes, int8 quantization
3. Flat layer-0 adjacency to cut pointer chasing further

Contributing

Issues and pull requests are welcome. Before sending a change, run:

cargo fmt --all --check
cargo clippy --all-targets -- -D warnings
cargo test

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.