io.github.cyberlife-coder/velesdb-memory

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. Re-verified on v3.3.0 (2026-06-24): p50 ≈ 360 µs (356–366 µs across two clean isolated runs), recall@10 0.986–0.989 on Apple Silicon — report (latency is hardware-specific; the canonical 450 µs is the i9-14900KF figure). [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.3 MB on Apple Silicon for v3.3.0 (the v1.18.0 release artifact was 9.4 MB). Across platforms and binaries (CLI / server / migrate), release artifacts span 6–13 MB. Enforced in CI: scripts/check_binary_size.py (workflow binary-size.yml) fails the build if a binary exceeds its ceiling.

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.

The wedge: why() — connected memory that survives restarts

Most "agent memory" is vector recall: it finds text that looks like your query. VelesDB's high-level MemoryService adds the part that's missing — it connects memories with typed links, so it can answer why something happened by walking the graph to context that shares no words with your question. The store is on disk, so it works across sessions. Offline, deterministic, no API key, no model download:

Where Mem0 and Zep are cloud-coupled orchestrators (a service mesh over Qdrant + Postgres, with a cloud LLM in the loop), this is one local binary — same tier as Mem0 on LoCoMo QA (~57-58% vs ~55%, neutral basis), ahead of Zep, but fully offline with an auditable why() evidence path. Pick it when your data can't leave the box.

from velesdb import MemoryService            # pip install velesdb

mem = MemoryService("./agent_memory")        # a real on-disk store; survives restarts
reason = mem.remember("Robert is recovering from knee surgery")
mem.remember("Booked the aisle seat on Robert's flight", links=[(reason, "because")])

# A *new* process, weeks later, reopens the same store and asks why:
mem.why("why the aisle seat on Robert's flight?")   # walks booking → reason — recall() can't

Memories are permanent by default; forget(id) deletes one, and remember(…, ttl_seconds=…) (or a server-wide VELESDB_MEMORY_DEFAULT_TTL) gives a fact a durable, restart-surviving expiry.

The same wedge ships in Python (pip install velesdb), Node (npm i @wiscale/velesdb-memory-node), and as a local MCP server.

Four runnable ways to see it — each shows what plain vector recall misses and why() recovers:

Not a weak-embedder trick. In each retrieval demo, recall stays blind to the reason even under a real semantic embedder (ollama / all-minilm), not just the offline hash default — the reason is connected by a decision, not by surface similarity, which is exactly what a vector store cannot follow.

For the lower-level building blocks (episodic, procedural, TTL, snapshots):

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 source-available 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 (Rust + REST server):

cargo install velesdb-server velesdb-cli

Docker (REST server):

# 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

Data is stored in /data inside the container; the named volume velesdb_data persists across restarts.

Docker Compose:

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

WASM (Browser):

npm install @wiscale/velesdb-wasm

Install script (Linux/macOS):

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

Install script (Windows PowerShell):

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

First search against the REST server (once velesdb-server is running on :8080):

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.

HNSW index-only micro-benchmark (lab-grade)

The number below is the index-only micro-benchmark (no WAL, no metadata fetch, hot cache). For the production-path number, see "End-to-end search latency (canonical)" above — 450µs p50 at 10K/384D, recall ≥ 96%.

Cross-checked on Apple M5 Pro (ARM64 / NEON, 18-core) — measured 2026-05-31, v1.16.0

Fresh figures on Apple Silicon (single-thread, run in isolation). They confirm the engine profile and make the scope of each number explicit; they are not a substitute for the x86_64/AVX2 reference figures above.

All cargo bench commands below are run as cargo bench -p velesdb-core --bench <NAME>.

The recall figures above are recall_benchmark's internal ef sweep (96/160/512) — distinct from the product "Modes" table below (Fast/Balanced/Accurate use ef 64/128/512). On this machine the PyO3/NumPy binding overhead is negligible: end-to-end ≈ index-only ≈ 55 µs. The 450 µs canonical figure is the i9-14900KF reference under WAL-on production conditions; per-machine results vary. Recall uses a real exact-kNN ground truth, not approximate self-comparison.

Measurements sourced from benchmarks/results/pr363_365_comparison.md (i9-14900KF, 64 GB DDR5, Windows 11, --release, target-cpu=native). Windows micro-benchmarks carry 5-10% noise — expect a range, not a single point.

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 source-available (readable, modifiable, redistributable under the VelesDB Core License 1.0 — not an OSI-approved license; see docs/LICENSING.md). 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

The container runs as a non-root velesdb user. Data persists via the named volume velesdb_data. A built-in health check (GET /health) is configured with a 30-second interval.

Full API reference: docs/reference/api-reference.md | OpenAPI spec: docs/openapi.yaml

• API Key Authentication — Bearer token auth via VELESDB_API_KEYS env var
• TLS (HTTPS) — Built-in via rustls (VELESDB_TLS_CERT / VELESDB_TLS_KEY)
• Graceful Shutdown — SIGTERM triggers connection drain + WAL flush. Zero data loss
• Health Endpoints — GET /health and GET /ready always public

docs/guides/SERVER_SECURITY.md

Demos & Examples

cd examples/ecommerce_recommendation && cargo run --release

VelesDB's performance is built on peer-reviewed research — five of the six techniques below are implemented and production-active in the engine; Dual-Precision (VSAG) ships as a public API with a benchmark harness, with engine integration tracked.

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 contact@wiscale.fr 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.