LlamaIndex VelesDB Integration

VelesDB vector store integration for LlamaIndex — the vector-recall face of VelesDB, the explainable, local-first memory engine for AI agents. For the connected why() recall trail across typed links, see velesdb-memory and the LangGraph integration.

Features

• 🚀 Sub-millisecond search — SIMD-optimized vector retrieval
• 📦 Self-contained — Single VelesDB binary, no external services required
• 🔒 Local-first — All data stays on your machine
• 🧠 RAG-ready — Built for Retrieval-Augmented Generation
• 🔀 Multi-Query Fusion — Native MQG support with RRF/Weighted strategies
• 🌊 Streaming inserts — Backpressure-aware streaming ingestion through VelesDB's bounded-channel API

Installation

pip install llama-index-vector-stores-velesdb

Quick Start

from llama_index.core import SimpleDirectoryReader, StorageContext, VectorStoreIndex
from llamaindex_velesdb import VelesDBVectorStore

# Create vector store
vector_store = VelesDBVectorStore(
    path="./velesdb_data",
    collection_name="my_docs",
    metric="cosine",
)

# Wrap it in a StorageContext. This step is required: from_documents()
# ignores a bare vector_store= keyword and would silently index into an
# in-memory store, leaving the VelesDB collection empty.
storage_context = StorageContext.from_defaults(vector_store=vector_store)

# Load and index documents — chunks are written to VelesDB
documents = SimpleDirectoryReader("./data").load_data()
index = VectorStoreIndex.from_documents(
    documents,
    storage_context=storage_context,
)

# Query
query_engine = index.as_query_engine()
response = query_engine.query("What is VelesDB?")
print(response)

Usage with Existing Index

from llama_index.core import VectorStoreIndex
from llamaindex_velesdb import VelesDBVectorStore

# Connect to existing data
vector_store = VelesDBVectorStore(path="./existing_data")
index = VectorStoreIndex.from_vector_store(vector_store)

# Query
query_engine = index.as_query_engine()
response = query_engine.query("Summarize the key points")

API Reference

VelesDBVectorStore

VelesDBVectorStore(
    path: str = "./velesdb_data",      # Database directory
    collection_name: str = "llamaindex", # Collection name
    metric: str = "cosine",             # Distance metric
    storage_mode: str = "full",         # Storage / quantization mode
    search_quality: str = None,         # Quality preset (see below)
)

Parameters:

Methods:

Advanced Features

Multi-Query Fusion (MQG)

Search with multiple query embeddings and fuse results using various strategies. Perfect for RAG pipelines using Multiple Query Generation (MQG).

from llamaindex_velesdb import VelesDBVectorStore

vector_store = VelesDBVectorStore(path="./velesdb_data")

# Basic usage with RRF (Reciprocal Rank Fusion)
results = vector_store.multi_query_search(
    query_embeddings=[emb1, emb2, emb3],  # Multiple query reformulations
    similarity_top_k=10,
    fusion="rrf",
    fusion_params={"k": 60}
)

# With weighted fusion (like SearchXP's scoring)
results = vector_store.multi_query_search(
    query_embeddings=[emb1, emb2],
    similarity_top_k=10,
    fusion="weighted",
    fusion_params={
        "avg_weight": 0.6,   # Average score weight
        "max_weight": 0.3,   # Maximum score weight  
        "hit_weight": 0.1,   # Hit ratio weight
    }
)

for node in results.nodes:
    print(f"{node.metadata}: {node.text[:50]}...")

Fusion Strategies:

• "rrf" - Reciprocal Rank Fusion (default, robust to score scale differences)
• "average" - Mean score across all queries
• "maximum" - Maximum score from any query
• "weighted" - Custom combination of avg, max, and hit ratio
• "relative_score" - Linear blend of dense and sparse scores

# Relative Score Fusion
results = vector_store.multi_query_search(
    query_embeddings=[emb1, emb2],
    similarity_top_k=10,
    fusion="relative_score",
    fusion_params={"dense_weight": 0.7, "sparse_weight": 0.3}
)

Advanced Search

search_quality — Quality Presets

Control the recall/latency trade-off for all queries with a single parameter set at construction time or overridden per-call via query() kwargs.

# Set once on the store — applies to every query() call
vector_store = VelesDBVectorStore(
    path="./velesdb_data",
    search_quality="accurate",   # higher recall at the cost of latency
)

q = VectorStoreQuery(query_embedding=embedding, similarity_top_k=10)
results = vector_store.query(q)

# Override per-call via kwargs
results = vector_store.query(q, search_quality="fast")

Accepted values:

query_with_ef(query_embedding, ef_search, top_k)

Search with an explicit HNSW ef_search parameter to trade query latency for recall.

# Higher ef_search = better recall, slower query
results = vector_store.query_with_ef(
    query_embedding=embedding,
    ef_search=256,
    top_k=10
)

query_ids(query_embedding, top_k)

Search returning only node IDs — no payloads transferred. Faster than query() when only IDs are needed (e.g., for post-processing pipelines).

ids = vector_store.query_ids(query_embedding=embedding, top_k=50)
# ["abc", "def", ...]  -- flat list of node-id strings, ordered by descending similarity

Hybrid Search (Vector + BM25)

from llamaindex_velesdb import VelesDBVectorStore

vector_store = VelesDBVectorStore(path="./velesdb_data")

# Hybrid search combining semantic and keyword matching
results = vector_store.hybrid_query(
    query_str="machine learning optimization",
    query_embedding=embedding_model.get_query_embedding("machine learning optimization"),
    similarity_top_k=10,
    vector_weight=0.7  # 70% vector, 30% BM25
)
for node in results.nodes:
    print(node.text)

Full-Text Search (BM25)

# Pure keyword-based search without embeddings
results = vector_store.text_query(
    query_str="VelesDB performance",
    similarity_top_k=5
)

Cross-Collection MATCH

The velesql() method runs single-collection VelesQL/MATCH queries against the vector store's own collection:

results = vector_store.velesql(
    "MATCH (p:Product)-[:STORED_IN]->(w:Warehouse) RETURN p.name, w.city LIMIT 20"
)
for row in results:
    print(row["p.name"], row["w.city"])

Cross-collection @collection MATCH is not available through the LlamaIndex integration. velesql() delegates to a single velesdb.Collection, which cannot resolve @collection-annotated nodes from other collections — that requires Database-level routing. For cross-collection MATCH, use the core velesdb.Database API or the REST server directly. (Tracked in docs/reference/ECOSYSTEM_PARITY.md, action item #7.)

Graph Retrieval

Three graph helpers ship with the package: GraphLoader (build a knowledge graph over stored nodes), GraphRetriever (vector seed + graph expansion) and GraphQARetriever (adds depth-based re-ranking). Native mode talks to the VelesDB graph layer directly — no server required. Create the graph collection once with the core API, then link the VelesDB point IDs of stored nodes (the hash of each LlamaIndex node id, via velesdb_common.ids.stable_hash_id):

from llamaindex_velesdb import VelesDBVectorStore, GraphLoader

vector_store = VelesDBVectorStore(path="./velesdb_data", collection_name="docs")
vector_store._get_db().create_graph_collection("kg")  # once

loader = GraphLoader(vector_store, graph_collection_name="kg")
loader.add_edge(edge_id=1, source=source_id, target=target_id, label="RELATES_TO")
edges = loader.get_edges(label="RELATES_TO")

GraphRetriever finds seed nodes by vector search, then expands the context through the graph:

from llama_index.core import VectorStoreIndex
from llamaindex_velesdb import GraphRetriever

index = VectorStoreIndex.from_vector_store(vector_store)
retriever = GraphRetriever(
    index=index,
    mode="native",
    graph_collection_name="kg",
    seed_k=3,        # initial vector hits
    expand_k=10,     # max nodes after expansion
    max_depth=2,     # BFS traversal depth
)
nodes = retriever.retrieve("What is VelesDB?")

GraphQARetriever re-ranks results by graph depth (seeds first) for Q&A:

from llamaindex_velesdb import GraphQARetriever

retriever = GraphQARetriever(
    index=index,
    mode="native",
    graph_collection_name="kg",
    rerank_by_depth=True,
)
nodes = retriever.retrieve("How are these concepts related?")

Pass low_latency=True to either retriever to skip graph expansion and return vector-only seeds (no graph collection required).

Performance

Measured on CI runners (ubuntu-latest, 2-core). Local hardware will be faster. Source: benchmarks/baseline.json.

Agent Memory (optional)

llama-index-vector-stores-velesdb re-exports three agent-memory wrappers around VelesDB's native memory subsystems. They are imported lazily — if the underlying velesdb native extension isn't installed, the import becomes a no-op and the symbols are exposed as None.

from llamaindex_velesdb import (
    VelesDBSemanticMemory,       # long-term knowledge store
    VelesDBEpisodicMemory,       # time-sequenced event recall
    VelesDBProceduralMemory,     # learned procedures with reinforcement
)

See llamaindex_velesdb/memory.py for the full per-class API. The companion GraphLoader, GraphRetriever, and GraphQARetriever exports (top of the public namespace) are documented in the Graph Retrieval section above.

Comparison with Other Stores

License

MIT License (this integration)

VelesDB Core and Server are licensed under VelesDB Core License 1.0 (source-available). See the root LICENSE for details.