velesdb (Python)

Embedded vector + graph database for Python: local-first semantic search and explainable agent memory.

Licensed under the VelesDB Core License 1.0 (source-available). The compiled wheel embeds the VelesDB engine and is governed by the same license.

Objective

Vector search usually means running a server: a container, a port, a network hop on every query, and an ops story you did not ask for. VelesDB's Python SDK removes all of it — the engine is compiled into the wheel and runs inside your process, against a directory on disk. You get microsecond-scale similarity search, hybrid dense + sparse retrieval, graphs and VelesQL without a daemon, and — when you are building an agent — a memory layer that can explain why it returned what it returned.

If you already run a managed vector service and are happy with it, you do not have this problem and can stop here.

Use cases

A RAG prototype on a laptop that must survive pip install and nothing else — no Docker, no cloud account.
An AI agent that has to remember decisions across process restarts and justify them later (why()).
A desktop or CLI application shipping semantic search inside the app, with the index living next to the user's data.
A batch job that embeds a corpus once, writes a portable index directory, and searches it in-process.
An offline or air-gapped environment where sending embeddings to a hosted API is not an option.

Prerequisites

Requirement	Minimum version	Note
Python	3.9	`requires-python = ">=3.9"`; a single `cp39-abi3` wheel covers 3.9+
pip	any recent	prebuilt wheels, no compilation
NumPy	1.20	hard runtime dependency, installed automatically
Rust	1.90	only when building from the sdist / source checkout
Embedding model	—	not included: VelesDB stores and searches vectors, it does not generate them

Installation

pip install velesdb

Optional extras (all independent, install only what you use):

pip install "velesdb[embed-sentence-transformers]"  # local embedding adapter
pip install "velesdb[embed-openai]"                 # OpenAI-compatible adapter
pip install "velesdb[pandas]"                       # DataFrame ingestion
pip install "velesdb[polars]"                       # Polars ingestion

Building from a source checkout of this repository instead:

pip install maturin
cd crates/velesdb-python
maturin develop

First success in 60 seconds

# pip install velesdb
import velesdb

db = velesdb.Database("./hello_velesdb_data")                 # created if missing
docs = db.get_or_create_collection("docs", metric="cosine")   # dimension auto-detected

# 4-D vectors whose axes stand for four made-up topics: [tech, food, music, sport]
docs.upsert([
    {"id": 1, "vector": [1.0, 0.0, 0.0, 0.0], "payload": {"title": "Rust release notes"}},
    {"id": 2, "vector": [0.0, 1.0, 0.0, 0.0], "payload": {"title": "Best ramen in Tokyo"}},
    {"id": 3, "vector": [0.6, 0.0, 0.8, 0.0], "payload": {"title": "AI-generated jazz"}},
])

results = docs.search_request(velesdb.SearchOptions(vector=[1.0, 0.0, 0.0, 0.0], k=2))
for r in results:
    print(f"score={r['score']:.3f}  {r['payload']['title']}")

Expected output — the exact-match document scores 1.000, the partly-tech one 0.600:

score=1.000  Rust release notes
score=0.600  AI-generated jazz

Anything else is a failure: an empty output means the upsert did not land (check that ./hello_velesdb_data is writable), and a ModuleNotFoundError means the wheel is not installed in the interpreter you are running. The longer version of this script is examples/python/hello_velesdb.py.

Next step, the agent-memory wedge — the same package, no extra install:

from velesdb import MemoryService              # offline, deterministic, no API key

mem = MemoryService("./agent_memory")          # 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")])

mem.why("why the aisle seat on Robert's flight?")   # walks booking → reason

why() returns the best-matching memory plus the connected subgraph reached through typed links — context that shares no words with the question, which a plain vector recall cannot find. See PYTHON_AGENT_MEMORY.md.

Configuration

Database(path, config=...) accepts a typed VelesConfigOptions covering every engine section of the core VelesConfig. Build it in code or load it from a velesdb.toml (engine-only semantics: a shell-owned [server] / [logging] table in a shared file is ignored).

Section	Type	Controls
`limits`	`LimitsOptions`	collection and resource ceilings
`search`	`SearchConfigOptions`	default search mode, max results
`hnsw`	`HnswConfigOptions`	index build/search parameters
`storage`	`StorageOptions`	on-disk storage behaviour
`quantization`	`QuantizationOptions`	compression settings

from velesdb import Database, VelesConfigOptions, LimitsOptions, SearchConfigOptions

cfg = VelesConfigOptions(
    limits=LimitsOptions(max_collections=50),
    search=SearchConfigOptions(default_mode="accurate", max_results=100),
)
db = Database("./tenant1", config=cfg)

# Or from TOML (fail-fast: invalid TOML/values raise ValueError,
# a missing file raises FileNotFoundError):
cfg = VelesConfigOptions.from_toml_path("./velesdb.toml")
db = Database("./tenant1", config=cfg)

wal_batch is intentionally not exposed — the concurrent WAL writer is a VelesDB Enterprise feature (see WRITE_CONCURRENCY.md).

Examples

Runnable scripts, not snippets: examples/python/ (hello_velesdb.py, hybrid_queries.py, fusion_strategies.py, graph_traversal.py, graphrag_langchain.py, graphrag_llamaindex.py, multimodel_notebook.py) and the agent-memory demos in examples/agent_memory/.

API / commands

Signatures and docstrings ship inside the wheel as a typed stub (python/velesdb/__init__.pyi, with py.typed), so your IDE and mypy/pyright are the reference. Task-oriented guides:

Guide	What it covers
PYTHON_API_REFERENCE.md	`Database` / `Collection`, sparse + hybrid search, fusion strategies, distance metrics, storage modes, bulk loading, streaming ingestion
PYTHON_AGENT_MEMORY.md	`MemoryService` (`remember` / `recall` / `why` / `feedback`) and the semantic / episodic / procedural SDK
PYTHON_CONTEXT_COMPILER.md	`compile_context`, provenance handles, working contexts, LangChain and LlamaIndex wiring
PYTHON_GRAPH.md	persistent graph collections, `MATCH` queries, in-memory `GraphStore`
PYTHON_VELESQL.md	`VelesQL.parse()` / `ParsedStatement` introspection
PYTHON_RAG_PIPELINE.md	text → embeddings → results, built-in embedding adapters
PYTHON_PERFORMANCE.md	throughput tuning (numpy `f32`, `upsert_bulk_numpy`, batching)
PYTHON_ENGINE_BENCHMARKS.md	measured engine latency and recall figures
PYTHON_REMOTE_SERVER.md	talking to a running `velesdb-server` over HTTP

Known limits

No embedding generation. VelesDB stores and searches vectors; you bring the model (or use the optional adapters).
Embedded only. There is no Python client class for a remote server — use HTTP against velesdb-server.
One process per database directory. A second process opening the same path fails with DatabaseLockedError ([VELES-031]).
wal_batch / concurrent WAL writing is not exposed — Enterprise feature.
No GPU in the published wheels. The gpu Cargo feature exists but is not enabled by [tool.maturin]; it requires building from source.
Collection.search(...) is deprecated since v1.15 (emits DeprecationWarning); use search_request(SearchOptions(...)).
Collection.get_graph_store() returns a standalone in-memory graph that is not connected to the collection; use Database.create_graph_collection() for persistence.

Compatibility

Prebuilt wheels published to PyPI (single cp39-abi3 wheel per platform, so one wheel covers Python 3.9 and later):

Platform	Status	Note
Linux x86_64 (glibc)	Prebuilt wheel	manylinux2014 — glibc 2.17+
Linux aarch64 (glibc)	Prebuilt wheel	manylinux2014
Linux x86_64 (musl)	Prebuilt wheel	musllinux_1_2 — Alpine images
Linux aarch64 (musl)	Prebuilt wheel	musllinux_1_2
macOS arm64 + x86_64	Prebuilt wheel	single `universal2` wheel
Windows x64	Prebuilt wheel	MSVC
Windows arm64	Prebuilt wheel	`aarch64-pc-windows-msvc`
Anything else (PyPy, exotic arches, older glibc)	Source build	sdist fallback, needs Rust 1.90

Troubleshooting

Symptom	Cause	Fix
`ModuleNotFoundError: No module named 'velesdb'`	the compiled extension is not installed in the active interpreter (a source checkout is not importable as-is)	`pip install velesdb`, or `maturin develop` inside `crates/velesdb-python`
`DimensionMismatchError: ... expected 768 ... 512`	the vector length differs from the collection's dimension	re-embed with the model that matches the collection, or create the collection with `dimension=None` to auto-detect on first upsert
`DatabaseLockedError: [VELES-031] Database is already opened by another process`	another process (or a still-open handle, e.g. a notebook kernel) holds that directory	close the other handle, or give the second process its own directory
`RuntimeError` on `collection.stream_insert([...])`	streaming ingestion was never enabled	call `collection.enable_streaming(...)` first
`FileNotFoundError` from `VelesConfigOptions.from_toml_path(...)`	config loading is fail-fast by design	check the path; malformed TOML or invalid values raise `ValueError` instead

All typed exceptions (DimensionMismatchError, CollectionNotFoundError, CollectionExistsError, EdgeExistsError, DatabaseLockedError, VelesQLSyntaxError, VelesQLParameterError) derive from velesdb.VelesDBError, so except velesdb.VelesDBError is a safe catch-all.

velesdb-python v5.1.0 · Last updated: 2026-08-10 · Applies to: velesdb-core 5.1.0 · Report a docs error

Release files for velesdb 5.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for velesdb 5.1.0
File	Size	Uploaded
velesdb-5.1.0.tar.gz	3.5 MB	Aug 19, 2026	Details

Built distributions (wheels)

Table of built distributions (wheels) for velesdb 5.1.0
File	Interpreter	ABI	Platform	Reset
velesdb-5.1.0-cp39-abi3-win_arm64.whl 3.1 MB Aug 19, 2026	CPython 3.9	abi3	Windows ARM64	Details
velesdb-5.1.0-cp39-abi3-win_amd64.whl 3.3 MB Aug 19, 2026	CPython 3.9	abi3	Windows x86-64	Details
velesdb-5.1.0-cp39-abi3-musllinux_1_2_x86_64.whl 3.8 MB Aug 19, 2026	CPython 3.9	abi3	Linux musl 1.2+ x86-64	Details
velesdb-5.1.0-cp39-abi3-musllinux_1_2_aarch64.whl 3.5 MB Aug 19, 2026	CPython 3.9	abi3	Linux musl 1.2+ ARM64	Details
velesdb-5.1.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl 3.5 MB Aug 19, 2026	CPython 3.9	abi3	Linux glibc 2.17+ x86-64	Details
velesdb-5.1.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl 3.3 MB Aug 19, 2026	CPython 3.9	abi3	Linux glibc 2.17+ ARM64	Details
velesdb-5.1.0-cp39-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl 6.5 MB Aug 19, 2026	CPython 3.9	abi3	macOS 10.12+ x86-64, macOS 11.0+ ARM64, macOS 10.12+ universal2 (ARM64, x86-64)	Details

Total release size: 30.6 MB

Release files / velesdb-5.1.0.tar.gz

Download URL	velesdb-5.1.0.tar.gz
Size	3.5 MB
Tags	Source
SHA-256 checksum How to use checksums	`400f7f14606661bc9e5eab622c1932a8d1b4adab65f7a6aed7ff4725f683a39e`
BLAKE2b-256 checksum How to use checksums	`c54d228f7703603a864b0ab06211411ab5b2f043bb268f89372b7ecf14d62e4a`
Upload date	Aug 19, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / velesdb-5.1.0-cp39-abi3-win_arm64.whl

Download URL	velesdb-5.1.0-cp39-abi3-win_arm64.whl
Size	3.1 MB
Tags	CPython 3.9 Windows ARM64 abi3
SHA-256 checksum How to use checksums	`981b01cb3d404edc3cd2d497d7f2b411cca428cfa3727b142ebe9b3365bf5dc9`
BLAKE2b-256 checksum How to use checksums	`84d7090cb883628fc1d5a5397b3e28b2c9d8741a925be3c926813b995d93d1eb`
Upload date	Aug 19, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.9`

Release files / velesdb-5.1.0-cp39-abi3-win_amd64.whl

Download URL	velesdb-5.1.0-cp39-abi3-win_amd64.whl
Size	3.3 MB
Tags	CPython 3.9 Windows x86-64 abi3
SHA-256 checksum How to use checksums	`e0670745c57d82130075adeb30c1c2eeca15508f2cd190262f12eaae2c2cd1a2`
BLAKE2b-256 checksum How to use checksums	`62099b859dcbc6073e0b2b0073189fddda36c878b228b723550637474343c85b`
Upload date	Aug 19, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.9`

Release files / velesdb-5.1.0-cp39-abi3-musllinux_1_2_x86_64.whl

Download URL	velesdb-5.1.0-cp39-abi3-musllinux_1_2_x86_64.whl
Size	3.8 MB
Tags	CPython 3.9 Linux musl 1.2+ x86-64 abi3
SHA-256 checksum How to use checksums	`572fd4e07de75b9a56dd868a2c305f6366d007a2e62775ecb8e9a721b0d79f2e`
BLAKE2b-256 checksum How to use checksums	`c704b1240c4e4bd562427dfa22b266f470c0832b2b6b358a945c80925c346d82`
Upload date	Aug 19, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / velesdb-5.1.0-cp39-abi3-musllinux_1_2_aarch64.whl

Download URL	velesdb-5.1.0-cp39-abi3-musllinux_1_2_aarch64.whl
Size	3.5 MB
Tags	CPython 3.9 Linux musl 1.2+ ARM64 abi3
SHA-256 checksum How to use checksums	`54522ca9b313090c15e5282241fc31c6329696a95d12b2eb29b5fdebd00dda2c`
BLAKE2b-256 checksum How to use checksums	`0233c071cfc1820e72424d280fe8cb6396b6225fc4bb5d65ae78a8afac9a7d85`
Upload date	Aug 19, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / velesdb-5.1.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL	velesdb-5.1.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size	3.5 MB
Tags	CPython 3.9 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum How to use checksums	`29009a7fcb4cde922af14df6099e4f2ea96226e3bb53e7a13d68fd8f42a7c56a`
BLAKE2b-256 checksum How to use checksums	`fa77a51d4983ebecfc592ba7955c3b24d07c5fe0f31a19b8e86bd9b9fcacbd6c`
Upload date	Aug 19, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / velesdb-5.1.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL	velesdb-5.1.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Size	3.3 MB
Tags	CPython 3.9 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum How to use checksums	`0b3cf05f3ffa73a983982d83e2e1495c8ab8801a2b182f6486b1a5a584893bcd`
BLAKE2b-256 checksum How to use checksums	`2c8c3cfb3e8e04c8094b5875efdb37b03cbf5b0b21a4842c11e939cfe83b75ae`
Upload date	Aug 19, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / velesdb-5.1.0-cp39-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl

Download URL	velesdb-5.1.0-cp39-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl
Size	6.5 MB
Tags	CPython 3.9 abi3 macOS 10.12+ universal2 (ARM64, x86-64) macOS 10.12+ x86-64 macOS 11.0+ ARM64
SHA-256 checksum How to use checksums	`149daff5f5069a9062efef50ef6a0b53aa36545f0cf99683ad79c0e765e801a4`
BLAKE2b-256 checksum How to use checksums	`31effb4be09034b1d861df15a6367bae5d9cf3195631004e4b49d9690e50855e`
Upload date	Aug 19, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.9`