Your AI agents forget everything. VelesDB fixes that.

One ~9 MB binary. Three engines. One query language. Zero cloud dependency.
Vector + Graph + ColumnStore — unified under VelesQL

Download latest release • Quick Start • Architecture • Roadmap • Quality Bar • Documentation • DeepWiki

Every AI agent today stitches together 3 databases for memory — vectors for "what feels similar", a graph for "what is connected", and SQL for "what I know for sure". That's 3 deployments, 3 configs, 3 query languages, and a pile of glue code.

VelesDB replaces all of that with a single Rust binary — smaller than a single smartphone photo.

The Story Behind VelesDB

VelesDB was born in France out of a simple observation: EU data sovereignty is an architectural problem, not a legal one.

The US Cloud Act, FISA 702, and PATRIOT Act give US authorities multiple legal paths to reach data held by any US company — regardless of where the servers are. Hosting on AWS eu-west-1 is a latency decision, not a sovereignty decision. The EU's Data Privacy Framework has been invalidated twice (Schrems I, Schrems II), and a third challenge is pending.

For European developers building AI agents that handle health data, legal documents, or financial records, the typical 2026 stack sends embeddings to Pinecone (US), graphs to Neo4j Aura (US), and metadata to PostgreSQL on AWS (US provider). Every one of these is reachable by a FISA warrant.

VelesDB removes the US provider from the chain entirely. One Rust binary, local-first by design. No API key, no cloud account, no data processor. Your data stays in a directory you control — on your laptop, your server, your jurisdiction.

Read the full story: "I built a database in France because the Cloud Act makes EU data sovereignty impossible"

Why VelesDB?

¹ ColumnStore filtering API micro-benchmark, integer equality: 130x at 100K rows, 55x at 10K rows — see docs/BENCHMARKS.md § 6. SELECT ... WHERE metadata filtering uses secondary indexes when available, and an adaptive ColumnStore payload mirror for scan-heavy filters (see [2] below).

What is VelesDB?

VelesDB is a local-first database for AI agents that fuses three engines into a single ~9 MB binary [3]:

[1] Reproduce: python benchmarks/velesdb_benchmark.py --recall (Python SDK path, 10K/384D, WAL fsync on, i9-14900KF reference machine). See docs/BENCHMARKS.md and CHANGELOG v1.13.0. [2] Reproduce: cargo bench -p velesdb-core --bench column_filter_benchmark. See docs/BENCHMARKS.md § 6 — at 100K rows: ColumnStore 29.5 us vs JSON scan 3.84 ms (integer equality filter). Micro-benchmark of the ColumnStore filtering API, which now serves SELECT ... WHERE metadata filtering through a per-collection payload mirror (built adaptively for scan-heavy workloads) and backs JOIN execution; secondary indexes are used first when they cover the filter. [3] Binary size: velesdb-server, stripped release build (9.1 MB stripped local build on Apple Silicon; the published v1.18.0 release artifact is 9.4 MB). Across platforms and binaries (CLI / server / migrate), v1.18.0 release artifacts span 6–13 MB.

All three are queried through VelesQL — a single SQL-like language with vector, graph, and columnar extensions:

MATCH (doc:Document)-[:AUTHORED_BY]->(author:Person)
WHERE similarity(doc.embedding, $question) > 0.8
  AND author.department = 'Engineering'
RETURN author.name, doc.title
ORDER BY similarity() DESC LIMIT 5

Built-in Agent Memory SDK provides semantic, episodic, and procedural memory for AI agents — no external services needed.

One binary. No cloud. No glue code. Runs on server, browser, mobile, and desktop.

Agent Memory SDK

Built-in memory for AI agents — semantic, episodic, and procedural. No external services needed.

from velesdb import Database, AgentMemory

db = Database("./agent_data")
memory = AgentMemory(db, dimension=384)

memory.semantic.store(1, "Paris is the capital of France", embedding)
memory.episodic.record(1, "User asked about geography", timestamp, embedding)
memory.procedural.learn(1, "answer_geography", steps, embedding, confidence=0.8)

And because memories live in the same engine as the graph and the ColumnStore, one VelesQL statement recalls by similarity, graph context, and session — in a single query (tested end-to-end):

SELECT memory.*, similarity() FROM agent_memory AS memory
WHERE vector NEAR $embedding
  AND MATCH (ctx)-[:RELATES_TO]->(fact)
  AND session_id = $current_session
ORDER BY similarity() DESC LIMIT 10

Full guide: docs/guides/AGENT_MEMORY.md | Source code

Quick Comparison

Competitor latencies are typical ranges from public benchmarks and vendor documentation. Direct comparison is approximate — architectures differ (embedded vs client-server, durable vs in-memory, recall levels). Run your own benchmarks for accurate comparison.

VelesDB's sweet spot: When you need vector + graph + structured filtering in a single engine, local-first deployment, or a lightweight binary that runs anywhere.

Not the best fit (yet): If you need a managed cloud service with a multi-node distributed cluster.

Known Limitations

VelesDB is honest about its boundaries. The following are current scope limits of the open-source Community Edition — each is either a deliberate design trade-off or a feature tracked for a separate Enterprise edition. We list them here so you can make an informed technical choice.

None of the above is a correctness gap — the Community Edition is production-ready for single-node, local-first deployments. The items above are feature-scope boundaries, not bugs.

For internal technical limitations (query-planner approximations, plan cache semantics around ANALYZE, CBO integration status), see docs/reference/KNOWN_LIMITATIONS.md — each entry is tracked by a GitHub issue or documented as an explicit approximation with regression tests.

Getting Started in 60 Seconds

The fastest path is Python — under 5 seconds median, measured. (timing methodology)

pip install velesdb
curl -O https://raw.githubusercontent.com/cyberlife-coder/VelesDB/main/examples/python/hello_velesdb.py
python hello_velesdb.py

Expected output:

Query: "tech"
  score=1.000  Rust 1.89 release notes
  score=0.600  AI-generated jazz: the new wave
  score=0.000  Best ramen in Tokyo

Query: "tech + music"
  score=0.990  AI-generated jazz: the new wave
  score=0.707  Rust 1.89 release notes
  score=0.707  Miles Davis discography

That's it — no server, no JSON, no embedding model. Read the 25-line script to see what happened. From here, the Agent Memory guide and the VelesQL spec are the natural next stops.

cargo install velesdb-server velesdb-cli

# Build the image locally
git clone https://github.com/cyberlife-coder/VelesDB.git && cd VelesDB
docker build -t velesdb .

# Run with persistent data (named volume)
docker run -d -p 8080:8080 -v velesdb_data:/data --name velesdb velesdb

# Verify it's running
curl http://localhost:8080/health

git clone https://github.com/cyberlife-coder/VelesDB.git && cd VelesDB
docker-compose up -d

npm install @wiscale/velesdb-wasm

curl -fsSL https://raw.githubusercontent.com/cyberlife-coder/VelesDB/main/scripts/install.sh | bash

irm https://raw.githubusercontent.com/cyberlife-coder/VelesDB/main/scripts/install.ps1 | iex

curl -X POST http://localhost:8080/collections \
  -d '{"name": "docs", "dimension": 4, "metric": "cosine"}' -H "Content-Type: application/json"

curl -X POST http://localhost:8080/collections/docs/points \
  -d '{"points": [
    {"id": 1, "vector": [1.0, 0.0, 0.0, 0.0], "payload": {"title": "AI Intro", "category": "tech"}},
    {"id": 2, "vector": [0.0, 1.0, 0.0, 0.0], "payload": {"title": "ML Basics", "category": "tech"}},
    {"id": 3, "vector": [0.0, 0.0, 1.0, 0.0], "payload": {"title": "History of Computing", "category": "history"}}
  ]}' -H "Content-Type: application/json"

curl -X POST http://localhost:8080/collections/docs/search \
  -d '{"vector": [0.9, 0.1, 0.0, 0.0], "top_k": 2}' -H "Content-Type: application/json"
# {"results":[{"id":"1","score":0.994,"payload":{"title":"AI Intro","category":"tech"}}, ...]}
# Results are wrapped in {"results":[...]} and point ids serialize as strings.
# (The unified POST /query endpoint instead returns projected rows with integer ids.)

Full installation guide: docs/guides/INSTALLATION.md

Vector Engine

Native HNSW index with SIMD-accelerated distance kernels. Sub-millisecond search on modern x86_64 hardware.

End-to-end search latency (canonical)

³ Query-path compression comes from PQ and RaBitQ — both are wired end-to-end into the collection search path, restarts included. The collection-level SQ8/Binary modes maintain caches that no search path reads yet (search stays full-precision f32 — SQ8 as a collection mode therefore adds* memory); their quantization primitives remain available programmatically. See docs/guides/QUANTIZATION.md.

Provenance of the canonical figures above: Intel Core i9-14900KF (x86_64, AVX2), velesdb_benchmark.py. "End-to-end / p50" = the full production path (VelesQL → HNSW → WAL ON → payload hydration), median over the query set. "Index-only" figures (in the details below) exclude WAL and payload and run on a hot cache — they are not comparable to the end-to-end number. Per-machine figures vary; fresh Apple-Silicon measurements are given below.

5 search quality modes (Fast → Perfect), adaptive two-phase ef, AutoTune.

Distance Metrics

5 metrics with SIMD acceleration (AVX-512, AVX2, NEON; WASM currently uses the scalar fallback — SIMD128 kernels are planned):

² 768D vectors, AVX2 hot cache (matches the table column header), see promise-contract.json for the policed claim

-- Choose metric at collection creation
CREATE COLLECTION docs (dimension = 768, metric = 'cosine');
CREATE COLLECTION images (dimension = 512, metric = 'euclidean');
CREATE COLLECTION fingerprints (dimension = 256, metric = 'hamming');

SELECT * FROM docs WHERE vector NEAR $v AND category = 'tech' LIMIT 5

• SIFT1M standardized ANN benchmark — measured on the de-facto-standard INRIA TEXMEX dataset (1M × 128D vectors, L2 metric). See docs/BENCHMARKS.md § 11 for methodology, dataset provenance, and how to reproduce.

Full benchmarks and methodology: docs/BENCHMARKS.md | velesdb-benchmarks repo | Quantization guide: docs/guides/QUANTIZATION.md

Graph Engine

Property graph with BFS/DFS traversal, edge labels, and Cypher-inspired MATCH queries — integrated with vector search.

-- Vector + Graph fusion in ONE statement
MATCH (doc:Document)-[:AUTHORED_BY]->(author:Person)
WHERE similarity(doc.embedding, $question) > 0.8
RETURN author.name, doc.title
ORDER BY similarity() DESC LIMIT 5

Cross-collection MATCH with @collection annotation — traversal runs on the primary collection's edge store; @collection enriches the matched node's payload from another collection (it is not a distributed cross-graph traversal):

MATCH (p:Product@products)-[:STORED_IN]->(inv:Inventory@inventory)
RETURN p.name, inv.price, inv.stock
LIMIT 20

Graph patterns guide: docs/guides/GRAPH_PATTERNS.md

ColumnStore Engine

Typed columnar storage — the same approach DuckDB and ClickHouse use. Its filtering API is 130x faster than JSON scanning at 100K rows (micro-benchmark: cargo bench -p velesdb-core --bench column_filter_benchmark).

JSON scan: 3.84 ms @ 100K    →    ColumnStore: 29.5 us @ 100K (130x faster)

The ColumnStore engine backs JOIN execution and serves SELECT ... WHERE metadata filtering through a per-collection payload mirror: top-level scalar payload fields are mirrored into typed columns, and filters compile to RoaringBitmap scans. The mirror is built adaptively — only after sequential scans have cost more than one full pass — so point lookups keep their fast path; secondary indexes are still consulted first when they cover the filter:

SELECT * FROM products
WHERE vector NEAR $query AND in_stock = true AND price < 50.0
LIMIT 10

Use Cases

AI Agent Memory

Your agent needs to remember conversations, learn from mistakes, and recall relevant knowledge. VelesDB provides all three memory types in a single embedded database — no Redis, no Pinecone, no Neo4j.

memory = AgentMemory(db, dimension=384)
memory.semantic.store(1, "User prefers dark mode", embedding)
memory.episodic.record(2, "User asked about billing", timestamp, embedding)
memory.procedural.learn(3, "handle_refund", steps, embedding, confidence=0.9)

RAG with Metadata Filtering

Vector search alone returns noise. VelesDB combines vector search with metadata filters (secondary indexes + planner-chosen pre/post-filtering) to eliminate irrelevant results.

SELECT * FROM docs
WHERE vector NEAR $query AND department = 'engineering' AND updated_at > NOW() - INTERVAL '30 days'
LIMIT 10

E-commerce: Vector + Graph + Filters in One Query

Find products similar to a query, filter by price/stock, and traverse co-purchase relationships — all in a single VelesQL statement.

MATCH (product)-[:BOUGHT_TOGETHER]->(related)
WHERE similarity(product.embedding, $query) > 0.7
  AND related.price < 200 AND related.in_stock = true
RETURN related.name, related.price
ORDER BY similarity() DESC LIMIT 20

Desktop & Mobile AI

Ship AI features without a server. VelesDB embeds directly into Tauri, iOS, and Android apps.

Roadmap

VelesDB Core is open-source. Enterprise features (distributed replication, managed cloud, RBAC) are available separately via VelesDB Premium.

We ship weekly. Full changelog | Contributing guide

Full Ecosystem

Python RAG framework parity: VelesDB ships a first-party connector for the three major Python RAG frameworks — LangChain (VectorStore), LlamaIndex (VectorStoreIndex), and Haystack 2.x (DocumentStore) — so you can swap VelesDB into any existing RAG pipeline with a single dependency change.

How VelesDB Works

INSERT                      INDEX                       SEARCH
┌──────────┐  upsert   ┌──────────────┐  build   ┌──────────────┐
│ Your App │──────────> │ WAL (append) │────────> │  HNSW Graph  │
│          │           │ + mmap store │         │  (in-memory) │
└──────────┘           └──────┬───────┘         └──────┬───────┘
                              │                        │
                       ┌──────▼───────┐                │ search
                       │  ColumnStore  │  filter   ┌────▼─────────┐
                       │ (typed cols)  │────────> │ SIMD Distance│
                       └──────────────┘          │(AVX-512/NEON)│
                        RESULT                    └──────┬───────┘
┌──────────┐  top-k    ┌──────────────┐  rank           │
│ Your App │<──────────│   Payload    │<────────────────┘
│          │           │  Hydration   │
└──────────┘           └──────────────┘

Key design choices:

• Local-first: In-process or single binary — no network hops, no cloud dependency
• Memory-mapped storage: OS manages paging between RAM and disk
• WAL durability: Every write is journaled. Crash-safe by default (fsync mode). Deferred sync during bulk insert for throughput
• ColumnStore: Typed columns with string interning, RoaringBitmap tombstones, PostgreSQL-inspired auto-vacuum

# Build and run locally
docker build -t velesdb .
docker run -d -p 8080:8080 -v velesdb_data:/data --name velesdb velesdb
curl http://localhost:8080/health

# Or with docker-compose (builds + auto-restart)
docker-compose up -d

Demos & Examples

cd examples/ecommerce_recommendation && cargo run --release

Contributing

git clone https://github.com/cyberlife-coder/VelesDB.git && cd VelesDB
cargo test --workspace --features persistence,gpu,update-check --exclude velesdb-python -- --test-threads=1

Looking for a place to start? Check out issues labeled good first issue.

Powered by VelesDB

Using VelesDB in production? Open a GitHub Discussion or email [email protected] to get featured. Your feedback shapes the roadmap.

License

VelesDB Core License 1.0 (based on ELv2). Free for production use, including commercial applications. Two restrictions: no offering VelesDB as a hosted/managed database service, and no building a competing database product. Read the full license.

VelesDB — The Local Knowledge Engine for AI Agents
velesdb.com • GitHub