VecStore

An embeddable vector database for Rust, with optional Python and WebAssembly interfaces. Store vectors alongside metadata, search for similar records, and keep the data inside your application.

Status: alpha, version 0.1.x. APIs and file formats can change. Use regenerable data while evaluating the project.

Run the quick start

With Rust 1.92+, start from a fresh checkout:

git clone https://github.com/PhilipJohnBasile/vecstore.git
cd vecstore
cargo run --locked --example quickstart

The example creates a temporary database, inserts three records, searches with metadata filters, then saves and reopens the store. It uses fixed vectors, so no model, service, or API key is needed. It finishes with Store reloaded, count: 3.

The Rust interface

use std::collections::HashMap;
use vecstore::{Metadata, Query, VecStore};

fn main() -> anyhow::Result<()> {
    let directory = tempfile::tempdir()?;
    let mut store = VecStore::open(directory.path().join("vectors"))?;
    let metadata = Metadata {
        fields: HashMap::from([("title".into(), serde_json::json!("Hello"))]),
    };
    store.upsert("doc1".into(), vec![0.1, 0.2, 0.3], metadata)?;
    let neighbors = store.query(Query::new(vec![0.1, 0.2, 0.3]).with_limit(1))?;
    assert_eq!(neighbors[0].id, "doc1");
    Ok(())
}

This uses the current checkout's API. A standalone application also needs anyhow, serde_json, and tempfile alongside its vecstore dependency.

What to explore

Area	Entry point
Vector indexing and persistence	Store implementation, architecture
Metadata filters	Quick start, filter examples
Hybrid retrieval	Hybrid search example
Python	Python guide, python Cargo feature
Browser / WebAssembly	WASM guide, wasm Cargo feature
Optional backends	Cargo features, examples

Optional GPU, server, embedding, and distributed components have separate dependencies and validation needs. The default Rust quick start does not establish readiness for those configurations.

Benchmarks

The repository includes benchmark harnesses. A useful report needs the dataset, vector dimensions, distance metric, index settings, recall, hardware, and latency distribution together. Use the harness on your intended workload; this README does not make a universal sub-millisecond latency claim.

Development and releases

cargo test --locked --lib
cargo fmt --all -- --check

CI runs the project's build, test, and lint checks. See verification notes for the fresh-checkout results and Releases for published GitHub releases. A Cargo version in source is not itself a published release.

Contributing · Security policy · Issues

License

MIT, matching the root license and Rust package metadata.