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

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

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:

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

Troubleshooting

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 v8.1.0 · Last updated: 2026-10-29 · Applies to: velesdb-core 8.1.0 · Report a docs error