ManualFor developers · v0.5.0 MVP

Quick
start

From pip install to your first hybrid search in under five minutes. Zero configuration, zero servers, zero network — just durable local memory and RRF-fused retrieval.

Quickstart$ pip install vantadb-py

Ir a 5-Minute Quickstart

§01

Installation

VantaDB ships as a native Python package with pre-compiled wheels for Windows, macOS, and Linux. Pick the path that matches your stack.

Python · pip

Recommended

pip install vantadb-py

Distribution name is vantadb-py · canonical import is import vantadb

Rust · Cargo.toml

[dependencies]
vantadb = "0.1"

For Rust-native integration

Precompiled CLI binary

Download and install the CLI binary in a single command — no compiling.

# Linux / macOS / WSL
curl -fsSL https://raw.githubusercontent.com/ness-e/Vantadb/main/scripts/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/ness-e/Vantadb/main/scripts/install.ps1 | iex

Or via Cargo: cargo install --git https://github.com/ness-e/Vantadb.git --bin vanta-cli

Trust: both one-liners use TLS against the official ness-e/Vantadb repo, and the script verifies the payload `.sha256` before installing. The installer chains to the setup wizard unless skipped with `--no-wizard` / `-NoWizard`; preview with `--dry-run` / `-DryRun`. Source: README § One-Line Installation + QUICKSTART §0.

Dev from source: pip install -e ./vantadb-python

§02

5-Minute Quickstart

Initialize a persistent memory store, save structured records with vectors, and execute hybrid retrieval in pure Python.

quickstart.py

import vantadb

# 1. Open or create a local database (zero configuration)
db = vantadb.VantaDB("./vanta_data", memory_limit_bytes=512_000_000)

# 2. Store a memory record with payload, metadata, and embedding
record = db.put(
    "agent/main",
    "memory-001",
    "In-process execution minimizes latency for local AI agents.",
    metadata={"category": "architecture", "priority": 1},
    vector=[0.12, 0.88, 0.54],
)

# 3. Retrieve exact record by key
stored = db.get_memory("agent/main", "memory-001")

# 4. Hybrid Search (BM25 + Cosine Similarity fused via RRF)
hits = db.search_memory("agent/main", query_vector=[0.11, 0.89, 0.55], top_k=5)

# 5. Operational Telemetry & Safe Shutdown
caps = db.hardware_profile()
db.flush()
db.close()

print(record)
print(stored)
print(hits)
print(caps)

Open or create a DB

Zero configuration. Specify a path and an optional memory budget. The WAL initializes on first write.

Store a record

put() writes a UTF-8 payload, scalar metadata, and an optional vector under a namespace + key.

Retrieve by key

get() returns the exact canonical record — the source of truth, always consistent.

Hybrid search

search() runs BM25 and HNSW in parallel, fusing ranks via RRF. Pass a vector, get top_k hits.

Telemetry & shutdown

hardware_profile() reports process memory. flush() forces WAL sync. close() releases handles safely.

§03

Embedded CLI

For local development, debugging, or pipeline automation without Python. Once installed and on your PATH, use the global vanta-cli command.

cmdvanta-cli put

--db ./vanta_data --namespace agent/main --key mem-1 --payload "hello"

Store a memory record under a namespace + key.

cmdvanta-cli list

--db ./vanta_data --namespace agent/main

List all records within a namespace.

cmdvanta-cli export

--db ./vanta_data --namespace agent/main --out ./memory.jsonl

Export a namespace to JSONL for backup or migration.

cmdvanta-cli rebuild-index

--db ./vanta_data

Rebuild the ANN (HNSW) index from canonical records.

cmdvanta-cli audit-index

--db ./vanta_data --namespace agent/main --json --deep

Audit derived indexes against canonical records.

cmdvanta-cli repair-text-index

--db ./vanta_data

Repair stale or corrupted BM25 text indexes.

Tip: developing inside the repo? cargo run --bin vanta-cli -- <command> runs directly from source.

§04

Optional Server Mode

Run the standalone binary to wrap the embedded core for local development or network exposure. This is not the primary product identity — it's an optional wrapper.

Defaults

▸Data dir: creates vantadb_data/ in the cwd
▸Bind: 127.0.0.1:8080 (safe localhost)

Network exposure

export VANTADB_HOST=0.0.0.0
./vantadb-server-linux-amd64

Override the bind address to expose to the network

Windows SmartScreen: release binaries are unsigned — SmartScreen may warn “Unrecognized Publisher”. Only run binaries from official GitHub Releases.

Code Playground

Edit the code and hit Run. Each run opens a real VantaDB instance compiled to WebAssembly (vantadb-wasm) and executes your snippet against it — in your browser (sandboxed iframe).

playground.js21 lines

const rec = db.put({
  namespace: "agent/main",
  key: "mem-001",
  payload: "hello vanta",
  vector: [0.1, 0.9, 0.5],
});
console.log("stored", rec.key, "->", rec.payload);
 
const stored = db.get("agent/main", "mem-001");
console.log("get", stored.key, "->", stored.payload);
 
const hits = db.search({
  namespace: "agent/main",
  query_vector: [0.11, 0.89, 0.55],
  top_k: 5,
});
for (const hit of hits) {
  console.log(hit.record.key, "score=" + hit.score.toFixed(4));
}
 
db.flush();

output

// presioná Run para ejecutar

Note: Each Run opens a fresh in-memory VantaDB instance (wasm32 engine) inside a sandboxed iframe (allow-scripts). Data is not persisted between runs — for browser persistence use await VantaDB.connect_persistent(path).

§05

Full Documentation

The complete documentation set lives in the repository. Each doc covers a specific surface of the engine.

Architecture

Core engine, durability model, retrieval mechanisms, SDK boundary.

Mutation & Recovery Protocol

Canonical mutation order and WAL recovery behavior.

Text Index Design

BM25, phrase positions, derived index repair, Hybrid v1 boundaries.

Operations & Configuration

Runtime parameters and server wrapper configuration.

Memory Telemetry

Process-memory metrics contract and interpretation guidelines.

Python SDK Status

Stable boundary, current binding surface, distribution policy.

Reliability Gate

RSS stability, chaos injection, WAL durability policies.

CI Policy

Continuous integration strategy, profiles, certification gates.

See the numbers

Explore BENCH-01 and the SIFT1M Phase 2 speedups.