📚 VelesDB Documentation

August 17, 2026 · View on GitHub

VelesDB — the explainable, local-first memory engine for AI agents. One ~10 MB binary fuses vector + graph + columnar under VelesQL; why() returns the evidence path behind every recall. Zero cloud.

Welcome to the VelesDB documentation. This guide will help you get started and make the most of VelesDB.

📖 User Guides

Detailed guides for using VelesDB features. Full guides index → (all guides, including migration notes and tutorials).

GuideDescription
InstallationAll installation methods (cargo, binaries, Docker)
Installation optionsDecision aid: which install path to pick for core vs. agent memory
Configurationvelesdb.toml configuration reference
Search ModesUnderstanding Fast/Balanced/Accurate/Perfect modes
CLI reference / REPLCommand-line interface and interactive shell
QuantizationVector compression (SQ8, PQ, Binary, RaBitQ)
Tuning GuideHNSW parameter tuning and performance optimization
Agent MemoryAI agent memory: semantic, episodic, procedural, TTL, snapshots
MCP server setupvelesdb-memory: install, client config, shared HTTPS daemon, embedding/extraction backends
Context compilerDeterministic prompt compression: budgets, preservation rules, risk, the PostToolUse hook
Graph PatternsGraph modeling and MATCH pattern recipes
Multi-Model QueriesCombining vector, graph, and structured data in one VelesQL query
Server SecurityAPI keys, TLS, CORS, and operations hardening
Business ScenariosEnd-to-end business problems solved with single queries
Python PerformanceThroughput tuning for the Python binding
Concurrency & LockingConcurrent access and file-locking behavior
Write ConcurrencySingle-writer-per-collection model, batching patterns, Enterprise tier
Use CasesCommon use cases and recommended configurations
Migration v3.3.0Error codes, REST statuses and query results that changed in 3.3.0.
Migration v4.0.0The 4.0.0 breaking changes — start with the WASM weighted reordering, which is silent.
TroubleshootingSolutions for common issues new users encounter

API reference, per binding

Each binding has its own reference guide; the full guides index groups every guide by surface.

BindingReference
Cross-surfaceAPI correspondence
Rust (velesdb-core)Public API map · VelesQL
PythonAPI reference
WASM (browser)JavaScript API
Node.jsAddon reference
Mobile (Swift / Kotlin)Mobile API
Server (REST)REST tour
Tauri pluginPlugin reference
Data migrationvelesdb-migrate CLI

📐 Technical Reference

In-depth technical documentation. Full reference index → (all reference docs, plus the machine-readable promise contract).

ReferenceDescription
ArchitectureSystem design and internals
VelesQL SpecificationQuery language grammar and syntax (v3.10.0, canonical)
VelesQL Cheat SheetOne-page quick reference: search, filter, graph MATCH, fusion, sparse, EXPLAIN
VelesQL ContractCanonical REST contract (/query, /match, error model)
VelesQL ConformanceCross-ecosystem conformance matrix
MCP Tool Referencevelesdb-memory: every MCP tool, one section each — parameters, returns, limits, error model
Performance SLOCI-enforced performance objectives and budget gates
REST APIHTTP API endpoints
SIMD PerformanceSIMD optimizations and benchmarks

🎓 Tutorials

Step-by-step tutorials:

TutorialDescription
Tauri RAG AppBuild a desktop RAG application with Tauri

🤝 Contributing

For contributors and developers:

GuideDescription
Coding RulesCode style, conventions and the TDD workflow
Benchmarking GuideHow to run and interpret benchmarks
Code SigningRelease signing process
Project StructureCodebase organization

🌐 Ecosystem

VelesDB provides a complete ecosystem of SDKs and integrations:

ComponentTypeDescription
Ecosystem Sync ReportOverviewFeature parity matrix across all components
velesdb-coreCoreRust core library
velesdb-serverServerREST API server
velesdb-cliCLICommand-line interface & REPL
velesdb-wasmSDKWebAssembly for browsers
velesdb-pythonSDKPython bindings (PyO3)
velesdb-mobileSDKiOS/Android (UniFFI)
TypeScript SDKSDKTypeScript/JavaScript client
velesdb-memoryServerMCP agent-memory server (why() wedge)
velesdb-nodeSDKNode.js agent-memory binding (napi-rs)
tauri-plugin-velesdbPluginTauri desktop integration
LangChainIntegrationLangChain VectorStore
LlamaIndexIntegrationLlamaIndex VectorStore

📦 Crate Documentation

Each crate has its own README with specific documentation:

CrateDescription
velesdb-coreCore library
velesdb-serverREST API server
velesdb-cliCommand-line interface
velesdb-mobileiOS/Android bindings
velesdb-migrateMigration tools

🔬 Design, Internals & Reference

Background documents: how the engine is built, what it guarantees, and where the remaining debt is. Read these when you need the why behind a behaviour.

DocumentDescription
Tech-debt registryDeferred architectural decisions and known open items.
Concurrency modelWhich operations run in parallel, and the locks that make that safe.
Storage formatThe on-disk layout and its compatibility rules.
SoundnessThe invariants the engine relies on, and why they hold.
FuzzingThe fuzz targets and how to run them locally.
GPU accelerationWhat the gpu feature accelerates, and what it does not.
ANN state-of-the-art auditHow the index compares to published ANN work.
Core wiring debtKnown gaps between what core exposes and what the surfaces use.
Core / Premium splitWhere the open-core boundary sits, and the contract both repos read identically.
DecisionsOne decision per file: what was decided, why, and the code, PR or CI job that proves it.

📄 Project & Licensing

DocumentDescription
FAQThe questions newcomers actually ask.
LicensingThe VelesDB Core License, in practical terms.
Business modelWhat is open, what is premium, and why the line sits there.

🔗 External Resources

VelesDB — the explainable, local-first memory engine for AI agents. (Microsecond vector search is the proof, not the pitch.)

Last updated: 2026-08-08 · Applies to: velesdb-core 5.1.0