langchain-velesdb

LangChain VectorStore for VelesDB — the explainable, local-first memory engine for AI agents. Vector recall here; for the connected why() recall trail across typed links, see velesdb-memory and the LangGraph integration.

Installation

pip install langchain-velesdb

Quick Start

from langchain_velesdb import VelesDBVectorStore
from langchain_openai import OpenAIEmbeddings

# Initialize vector store
vectorstore = VelesDBVectorStore(
    path="./my_vectors",
    collection_name="documents",
    embedding=OpenAIEmbeddings()
)

# Add documents
vectorstore.add_texts([
    "VelesDB is a high-performance vector database",
    "Built entirely in Rust for speed and safety",
    "Perfect for RAG applications and semantic search"
])

# Search
results = vectorstore.similarity_search("fast database", k=2)
for doc in results:
    print(doc.page_content)

Usage with RAG

from langchain_velesdb import VelesDBVectorStore
from langchain_openai import ChatOpenAI, OpenAIEmbeddings
from langchain.chains import RetrievalQA

# Create vector store with documents
vectorstore = VelesDBVectorStore.from_texts(
    texts=["Document 1 content", "Document 2 content"],
    embedding=OpenAIEmbeddings(),
    path="./rag_data",
    collection_name="knowledge_base"
)

# Create RAG chain
retriever = vectorstore.as_retriever(search_kwargs={"k": 3})
qa_chain = RetrievalQA.from_chain_type(
    llm=ChatOpenAI(),
    chain_type="stuff",
    retriever=retriever
)

# Ask questions
answer = qa_chain.run("What is VelesDB?")
print(answer)

API Reference

VelesDBVectorStore

VelesDBVectorStore(
    embedding: Embeddings,
    path: str = "./velesdb_data",
    collection_name: str = "langchain",
    metric: str = "cosine",         # "cosine", "euclidean", "dot" (aliases: "dotproduct", "inner", "ip"), "hamming", "jaccard"
    storage_mode: str = "full",     # "full"/"f32", "sq8"/"int8" (4× compression), "binary"/"bit" (32× compression), "pq" (2 × dim / m compression), "rabitq" (32× with scalar correction)
    search_quality: str = None,     # "fast", "balanced", "accurate", "perfect", "autotune", "custom:N", "adaptive:MIN:MAX"
)

Methods

Core Operations:

• add_texts(texts, metadatas=None, ids=None) - Add texts to the store
• add_texts_bulk(texts, metadatas=None, ids=None) - Bulk insert (2-3x faster for large batches)
• add_texts_streaming(texts, metadatas=None, ids=None, ...) - Stream-insert via the bounded-channel ingestion pipeline (returns the list of inserted IDs)
• delete(ids) - Delete documents by ID
• get_by_ids(ids) - Retrieve documents by their IDs
• flush() - Flush pending changes to disk

Search:

• similarity_search(query, k=4) - Search for similar documents
• similarity_search_with_score(query, k=4) - Search with raw scores (cosine scores normalized to [0, 1]; a raw distance, lower is closer, under euclidean and hamming)
• similarity_search_with_relevance_scores(query, k=4, score_threshold=None) - Search with relevance scores, higher-is-closer under every metric: a euclidean/hamming distance d becomes 1 / (1 + d), so score_threshold (and as_retriever(search_type="similarity_score_threshold")) keeps the closest documents
• similarity_search_by_vector(embedding, k=4, filter=None) - Search with a pre-computed query vector
• max_marginal_relevance_search(query, k=4, fetch_k=20, lambda_mult=0.5) - MMR search balancing relevance and diversity
• max_marginal_relevance_search_by_vector(embedding, k=4, fetch_k=20, lambda_mult=0.5) - MMR search with a pre-computed query vector
• similarity_search_with_filter(query, k=4, filter=None) - Search with metadata filtering
• batch_search(queries, k=4) - Batch search multiple queries in parallel
• batch_search_with_score(queries, k=4) - Batch search with scores
• multi_query_search(queries, k=4, fusion="rrf", ...) - Multi-query fusion search
• multi_query_search_with_score(queries, k=4, ...) - Multi-query search with fused scores
• hybrid_search(query, k=4, vector_weight=0.5, filter=None) - Hybrid vector+BM25 search
• text_search(query, k=4, filter=None) - Full-text BM25 search
• query(query_str, params=None) - Execute VelesQL query

Utilities:

• as_retriever(**kwargs) - Convert to LangChain retriever
• from_texts(texts, embedding, ...) - Create store from texts (class method)
• get_collection_info() - Get collection metadata (name, dimension, point_count)
• is_empty() - Check if collection is empty
• scroll(batch_size=100, filter=None) - Iterate over all points in stable batches without a query vector

Advanced Features

Multi-Query Fusion (MQG)

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

# Basic usage with RRF (Reciprocal Rank Fusion)
results = vectorstore.multi_query_search(
    queries=["travel to Greece", "Greek vacation", "Athens trip"],
    k=10,
)

# With weighted fusion (like SearchXP's scoring)
results = vectorstore.multi_query_search(
    queries=["travel Greece", "vacation Mediterranean"],
    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
    }
)

# Get fused scores
results_with_scores = vectorstore.multi_query_search_with_score(
    queries=["query1", "query2", "query3"],
    k=5,
    fusion="rrf",
    fusion_params={"k": 60}  # RRF parameter
)
for doc, score in results_with_scores:
    print(f"{score:.3f}: {doc.page_content}")

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 — explicit control over dense vs sparse weight
results = vectorstore.multi_query_search(
    queries=["semantic search", "keyword retrieval"],
    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 similarity searches with a single parameter set at construction time or overridden per-call.

# Set once on the store — applies to every similarity_search call
vectorstore = VelesDBVectorStore(
    embedding=OpenAIEmbeddings(),
    path="./data",
    search_quality="accurate",   # higher recall at the cost of latency
)

results = vectorstore.similarity_search("machine learning", k=10)

# Override per-call via kwargs
results = vectorstore.similarity_search_with_score(
    "machine learning", k=10, search_quality="fast",
)

Accepted values:

similarity_search_with_ef(query, ef_search, k)

Search with an explicit HNSW ef_search parameter to trade query latency for recall. Higher ef_search increases recall at the cost of slower search.

# Use a high ef_search for maximum recall at query time
results = vectorstore.similarity_search_with_ef(
    query="machine learning",
    ef_search=256,
    k=10
)

Limitation: ef_search cannot be combined with filter. The VelesDB binding's search_with_ef has no filter argument, so similarity_search_with_ef raises ValueError whenever a filter is passed (ef_search always has a value there, default 64). For a filtered search use similarity_search_with_filter, which runs at the engine's default ef_search. Tracked in #2302.

vectorstore.similarity_search_with_ef("machine learning", ef_search=256, filter=flt)
# ValueError: ef_search cannot be combined with filter: ...

Hybrid Search (Vector + BM25)

# Combine vector similarity with keyword matching
results = vectorstore.hybrid_search(
    query="machine learning performance",
    k=5,
    vector_weight=0.7  # 70% vector, 30% BM25
)
for doc, score in results:
    print(f"{score:.3f}: {doc.page_content}")

Full-Text Search (BM25)

# Pure keyword-based search
results = vectorstore.text_search("VelesDB Rust", k=5)
for doc, score in results:
    print(f"{score:.3f}: {doc.page_content}")

Metadata Filtering

# Search with filters
results = vectorstore.similarity_search_with_filter(
    query="database",
    k=5,
    filter={"condition": {"type": "eq", "field": "category", "value": "tech"}}
)

Cross-Collection MATCH

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

results = vectorstore.query(
    "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 LangChain integration. vectorstore.query() 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

GraphRetriever finds seed documents by vector search, then expands the context through a VelesDB graph collection whose node ids are the documents' VelesDB point IDs (metadata["_int_id"]). Native mode reuses the vector store's database, so create the graph collection there first:

from langchain_velesdb import GraphRetriever

vector_store._get_db().create_graph_collection("kg")  # once, then add nodes and edges
retriever = GraphRetriever(
    vector_store=vector_store,
    mode="native",
    graph_collection_name="kg",
    seed_k=3,      # vector hits the graph is expanded from
    expand_k=10,   # max documents returned, seeds included
    max_depth=2,   # BFS traversal depth
)
docs = retriever.invoke("What is VelesDB?")

The result holds the seed_k vector hits first, best score first, then the documents the graph reaches from them, seed by seed in traversal order, until expand_k documents in all. A document already returned, or one the vector store cannot return, is skipped and takes no slot. Seeds carry graph_depth=0; a neighbour carries its hops from the nearest seed as graph_depth, and no relevance_score: it was reached through the graph, not scored. low_latency=True returns the seeds only.

Features

• High Performance: VelesDB's Rust backend delivers sub-millisecond latencies
• SIMD Optimized: Hardware-accelerated vector operations
• Multi-Query Fusion: Native support for MQG pipelines with RRF/Weighted fusion
• Hybrid Search: Combine vector similarity with BM25 text matching
• Full-Text Search: BM25 ranking for keyword queries
• Metadata Filtering: Filter results by document attributes
• Simple Setup: Self-contained single binary, no external services required
• LangChain VectorStore API: implements add_texts, add_documents, similarity_search, similarity_search_with_score, similarity_search_with_relevance_scores, similarity_search_by_vector, max_marginal_relevance_search (+ _by_vector), get_by_ids, delete, from_texts, and as_retriever (including search_type="mmr"), so it plugs into standard retriever-based chains and agents. Async (a*) methods fall back to LangChain's default thread-pool wrappers.

Agent Memory (optional)

langchain-velesdb also re-exports three agent-memory wrappers around VelesDB's native memory subsystems. They are imported lazily — if the underlying langchain extras aren't installed, the import becomes a no-op and the symbols are exposed as None.

from langchain_velesdb import (
    VelesDBChatMemory,           # short-term conversational buffer
    VelesDBSemanticMemory,       # long-term knowledge store
    VelesDBProceduralMemory,     # learned action patterns with reinforcement
)

See langchain_velesdb/memory.py for the full per-class API (chat history buffer with optional embedding, semantic recall with score, procedural reinforcement). Tests under integrations/langchain/tests/ exercise each.

License

MIT License (this integration). See LICENSE for details.

VelesDB Core itself is licensed under the VelesDB Core License 1.0 (based on ELv2).