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.

Three things no competitor counters

Related MCP server: verifiable-memory

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 (several backing services plus AI-model calls — cloud by default — on every memory write), this is one local binary — fully offline, zero AI calls to store a memory, and an auditable why() evidence trail. On the standard LoCoMo memory test, our fully-local setup answers 56% of the answerable questions (the benchmark's unanswerable "adversarial" category is excluded, as is standard practice — every configuration detail is disclosed) and 55–61% of time-related questions ("when did X happen?") — spanning both configurations the leading vendor's own paper reports for itself in that category, on powerful cloud AI models, while we run on a model on your own machine. Scores from different labs can't be fairly compared (the same product's score can swing ~21 points with the test setup alone), so instead of a bar chart we publish the full sourced landscape, method, and statistics. 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), as a local MCP server, and — in-memory only, no disk access under WASM — in the TypeScript SDK (npm i @wiscale/velesdb-sdk), running entirely in the browser or Node.js with no 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.

The context compiler: why() for your token bill

Agents burn most of their budget re-reading redundant context. The memory layer now ships a deterministic context compiler (compile_context over MCP and Node, ContextCompiler in Rust): no LLM, no cloud — duplicates drop, repeated log lines collapse with counts, code / URLs / numbers / negative constraints survive verbatim, and over-budget content becomes a recoverable ctx://source/ handle instead of a silent loss. Every decision carries a stable rule id, a reason, and a risk level (explain_compilation answers "why was this dropped?"), and the same request always compiles to the same bytes. On a committed 12-turn agent-session benchmark this measures 82.5 % real (cl100k) input-token savings with sub-millisecond stateless compiles, and 75–82 % estimated savings on the static corpus in ~2 ms (examples/context_savings, figures are local estimates, not billed tokens). The velesdb-context-optimizer skill packages the workflow — including when not to compress. See Why VelesDB.

Compiler surfaces today: MCP server, Node, Rust. Python binding: in progress — Python agents reach compile_context through the MCP server for now.

Quickstart (3 steps):

# 1. Install the MCP server binary
cargo install velesdb-memory

# 2. Point your MCP client at it (Claude Code example)
claude mcp add velesdb-memory -- ~/.cargo/bin/velesdb-memory

// 3. Call compile_context — query + token_budget + fragments
compile_context { "query": "state of the canary deploy", "token_budget": 500,
                  "fragments": [
                    { "content": "The canary is green: 2% traffic, zero errors in the last 10 minutes." },
                    { "content": "Rollback runbook: kubectl rollout undo deployment/canary." } ] }
→ { "content": "…both fragments packed…", "risk": "low",
    "decisions": […one auditable entry per fragment…] }

No Rust toolchain? Use npm instead: @wiscale/velesdb-memory-node.

Not a transparent proxy, and no automatic indexing. The compiler only compresses what your agent explicitly hands it as fragments (logs, retrieved docs, history) — never the harness's system prompt or tool schemas, and it's the skill above that teaches an agent when/what to route through it. Every compiled fragment is content-addressed to disk under the store path so retrieve_context_source can always recover it, and aggregate savings stats are recorded — but nothing enters recallable memory (what recall / memory_scope can surface) without an explicit remember / relate / remember_extracted call. Local-first — nothing leaves the machine. Details: crates/velesdb-memory/README.md § How it works.

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):

# Run the published image (multi-arch: linux/amd64 + linux/arm64)
docker run -d -p 8080:8080 -v velesdb_data:/data --name velesdb \
  ghcr.io/cyberlife-coder/velesdb:latest

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

Pin a specific version with ghcr.io/cyberlife-coder/velesdb:3.12 (or a full 3.12.0). To build the image yourself instead: git clone the repo and docker build -t velesdb ..

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.

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"

Roadmap

We ship weekly. This is the arc; the committed, dated plan lives in ROADMAP.md and the GitHub Milestones.

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.

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

# Run the published multi-arch image
docker run -d -p 8080:8080 -v velesdb_data:/data --name velesdb \
  ghcr.io/cyberlife-coder/velesdb:latest
curl http://localhost:8080/health

# Or build locally / use docker-compose (builds + auto-restart)
docker build -t velesdb . && 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.