Skip to main content

velesdb (Python)

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

PyPI Python License

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. Recall runs at the collection's own search quality unless you pick one: MemoryService(path, search_quality="accurate") (any REST/VelesQL mode name; an explicit value wins over VELESDB_MEMORY_SEARCH_QUALITY, an unknown one raises ValueError). 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)

There is no wal_batch section: the engine removed that never-wired table in 7.0.0, and the concurrent WAL writer is a VelesDB Enterprise feature (see WRITE_CONCURRENCY.md). A velesdb.toml written for 6.x that still sets [wal_batch] or [storage]'s data_dir / mmap_cache_mb / vector_alignment keeps loading: those keys are ignored, and the engine logs a warning naming them. StorageOptions no longer accepts them (TypeError).

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]).
  • 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(vector, top_k=...) is the keyword shorthand over search_request(SearchOptions(...)), which adds fusion, include_vectors and the read-gate options.
  • Graph persistence goes through Database.create_graph_collection(); Collection.get_graph_store() (a standalone in-memory graph) was removed in 8.0.0.

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

The typed collection exceptions (DimensionMismatchError, CollectionNotFoundError, CollectionExistsError, EdgeExistsError, DatabaseLockedError) derive from velesdb.VelesDBError. The VelesQL parse exceptions (VelesQLSyntaxError, VelesQLParameterError) do not — they derive from Exception directly, so a catch-all needs except (velesdb.VelesDBError, velesdb.VelesQLSyntaxError, velesdb.VelesQLParameterError) or plain except Exception.


velesdb-python v8.2.0 · Last updated: 2026-10-29 · Applies to: velesdb-core 8.2.0 · Report a docs error

Metadata

Release files for velesdb 8.2.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 8.2.0
File Size Uploaded Provenance Actions
velesdb-8.2.0.tar.gz 4.2 MB Without provenance Details for velesdb-8.2.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for velesdb 8.2.0
File Actions
velesdb-8.2.0-cp39-abi3-win_arm64.whl CPython 3.9 abi3 Windows ARM64 Details for velesdb-8.2.0-cp39-abi3-win_arm64.whl
velesdb-8.2.0-cp39-abi3-win_amd64.whl CPython 3.9 abi3 Windows x86-64 Details for velesdb-8.2.0-cp39-abi3-win_amd64.whl
velesdb-8.2.0-cp39-abi3-musllinux_1_2_x86_64.whl CPython 3.9 abi3 Linux musl 1.2+ x86-64 Details for velesdb-8.2.0-cp39-abi3-musllinux_1_2_x86_64.whl
velesdb-8.2.0-cp39-abi3-musllinux_1_2_aarch64.whl CPython 3.9 abi3 Linux musl 1.2+ ARM64 Details for velesdb-8.2.0-cp39-abi3-musllinux_1_2_aarch64.whl
velesdb-8.2.0-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl CPython 3.9 abi3 Linux glibc 2.17+ x86-64 Details for velesdb-8.2.0-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
velesdb-8.2.0-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl CPython 3.9 abi3 Linux glibc 2.17+ ARM64 Details for velesdb-8.2.0-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
velesdb-8.2.0-cp39-abi3-macosx_10_12_universal2.macosx_10_12_x86_64.macosx_11_0_arm64.whl CPython 3.9 abi3 macOS 11.0+ ARM64, macOS 10.12+ x86-64, macOS 10.12+ universal2 (ARM64, x86-64) Details for velesdb-8.2.0-cp39-abi3-macosx_10_12_universal2.macosx_10_12_x86_64.macosx_11_0_arm64.whl

Total release size: 37.7 MB

Release files / velesdb-8.2.0.tar.gz

Download URL velesdb-8.2.0.tar.gz
Size 4.2 MB
Tags Source
SHA-256 checksum
How to use checksums
5268a678335abe9605dc1650601031a3a5703060b3aad50cc19413ac980b4faa
BLAKE2b-256 checksum
How to use checksums
226058461be2df7c75bac1830a78fc830c548e32f87a4a5b5181f3c0cc9acf60
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

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

Download URL velesdb-8.2.0-cp39-abi3-win_arm64.whl
Size 3.8 MB
Tags CPython 3.9 Windows ARM64 abi3
SHA-256 checksum
How to use checksums
8a8888a63ccbc4c7dbbfda13a4efcd926034f9533cc2641fd67aa2b85606f91b
BLAKE2b-256 checksum
How to use checksums
758116caed5f7b8587ce221d83c419372beb8a2f46ea96119bcc2c2de08af88c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.9

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

Download URL velesdb-8.2.0-cp39-abi3-win_amd64.whl
Size 4.2 MB
Tags CPython 3.9 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
a5a11edc13a476fa4e7425a4c650bf9faa616c709d1d02a7adbcc5c3a4380b23
BLAKE2b-256 checksum
How to use checksums
0c4acbeec4d49b36dd952dc41a4d00525af19dae94c7902365e4fdff2cd8a90c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.9

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

Download URL velesdb-8.2.0-cp39-abi3-musllinux_1_2_x86_64.whl
Size 4.7 MB
Tags CPython 3.9 Linux musl 1.2+ x86-64 abi3
SHA-256 checksum
How to use checksums
6f5da1de7de711ddef59ddad5ba39c57cba74b026fa5c5f87e76d01a0a7a6127
BLAKE2b-256 checksum
How to use checksums
8052c40a4d85d69e907653078a8e4181b190198baac8d1270edae2a5c4930848
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

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

Download URL velesdb-8.2.0-cp39-abi3-musllinux_1_2_aarch64.whl
Size 4.3 MB
Tags CPython 3.9 Linux musl 1.2+ ARM64 abi3
SHA-256 checksum
How to use checksums
1c2f8df52aa669ee03a80de3e9a03c3de97b83dec703d354a9bfc5524660ba32
BLAKE2b-256 checksum
How to use checksums
b4ec1caaa90a0ee223d143f017504f127006d4ab20db7c4f5f4a5b2771d986fc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

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

Download URL velesdb-8.2.0-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Size 4.4 MB
Tags CPython 3.9 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
81f66330c1ba73c373232392f9a9639773e0882c190c1c8afaebf43e7c76ebc1
BLAKE2b-256 checksum
How to use checksums
86b59958497e5f7d68fc8e70e0a1cad0d484cae4ab931187214377fcac0e7635
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

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

Download URL velesdb-8.2.0-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
Size 4.1 MB
Tags CPython 3.9 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
c5c57219d79683cd516d2f54b1170d70815e9bb69213ceec210ab9b6b0578814
BLAKE2b-256 checksum
How to use checksums
5ef866091ba4956d81e4faf2165afe7b5c05a831e9f5555ba3492344556e389f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

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

Download URL velesdb-8.2.0-cp39-abi3-macosx_10_12_universal2.macosx_10_12_x86_64.macosx_11_0_arm64.whl
Size 8.0 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
969de457aef964414d45b5687b93a90fadfe96c344cc283f967570e7fe061cd1
BLAKE2b-256 checksum
How to use checksums
c984e21fdf5703ccb4404745b284fae9a74177b8cc6b4e6eefb7670ca89aad16
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.9

Security for velesdb 8.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

8.2.0 This release

8 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page