git-vdb

A local vector database stored entirely in Git.

git-vdb is an embedded Rust library and CLI: no server, daemon, account, or external database. Open a directory, write vectors, and search.

Install

cargo add git-vdb       # Rust library
cargo install git-vdb   # CLI

Rust quickstart

use git_vdb::{open, Point};

# fn main() -> git_vdb::Result<()> {
let db = open("./vectors.git")?;
let docs = db.collection("docs");
docs.upsert([
    Point::new("east", [1.0, 0.0]),
    Point::new("north", [0.0, 1.0]),
])?;
let hits = docs.search([0.9, 0.1], 1)?;
assert_eq!(hits[0].id.to_string(), "east");
# Ok(())
# }

The database and collection are created on the first write. Vector dimensions are inferred, payloads are returned by default, and search automatically chooses exact or approximate execution.

CLI quickstart

git-vdb --db vectors.git upsert docs --id east --vector '1,0'
git-vdb --db vectors.git upsert docs --id north --vector '0,1'
git-vdb --db vectors.git search docs --vector '0.9,0.1' --limit 1

Batch upserts accept a JSON Lines file or - for stdin.

Need local text embeddings? Use cargo add git-vdb --features fastembed; the embedding guide has the complete example.

Why Git-native?

• Local: one directory and no service to operate.
• Versioned: commits and refs provide optional history and atomic writes.
• Deterministic: equivalent data produces the same root tree.
• Portable: clone, fetch, push, archive, inspect, and maintain it with Git.

Guides

• Five-minute quickstart
• Persistence and reopening
• Filtering and detailed queries
• History and Git transport
• Text and embedding models
• Rust API reference

Advanced users can work directly with immutable snapshots, historical roots, compare-and-swap writes, validation, and ANN controls through Database, Collection, and SnapshotEngine.

Internals and benchmarks

• Canonical format version 2
• Legacy format version 1
• Snapshot design
• Current limitations and findings
• LanceDB performance evidence

See CONTRIBUTING.md for development and validation. Licensed under the Apache License 2.0.