DEV Community: Julien L

Building a Real-Time Recommendation Engine with VelesDB

Julien L — Tue, 07 Apr 2026 19:55:45 +0000

A visitor lands on the Elden Ring product page. They have never signed up, just browsing. Next to the buy button, a snippet appears: "Players also explored: Dark Souls III, God of War, Cyberpunk 2077." They click God of War. They buy both.

Two days later, Alice, a returning customer who already owns Elden Ring and Dark Souls III, visits the same page. Her snippet reads differently: "Based on your library: The Witcher 3, Cyberpunk 2077, Blasphemous." The engine knows her taste.

Same product page. Two completely different snippets. No external API call. No cloud ML pipeline. Just a 3MB binary running on your server, embedded directly in your application process.

This is what we are going to build in this article.

The problem with most recommendation systems

Classic approaches fall into two traps. Either they call an external service (AWS Personalize, Google Recommendations AI) which introduces latency, cost, and a hard dependency on connectivity. Or they pre-compute nightly batch recommendations that are stale the moment a user's behavior changes.

What I wanted for VelesDB was something different: no external service, the recommendation engine lives inside your deployment, and it reacts to the current session in real time with no nightly batch. It also needs to handle two distinct cases, anonymous prospects and authenticated customers, cleanly.

VelesDB® fits this use case naturally. It is a local-first vector + graph + columnar database, written in Rust (about 3MB binary). For recommendations, we will use two of its three pillars: a vector collection to store product embeddings and find semantically similar games, and a graph collection to store user behavior (purchases, views) and traverse purchase history.

Content-based filtering recommends items similar to what the user is currently looking at, based on item attributes alone, no knowledge of other users is needed. Collaborative filtering recommends items based on the behavior of other users who share similar tastes ("people who bought X also bought Y"). Both approaches complement each other and we will implement all three strategies below.

Architecture overview

                 +--------------------------------------+
                 |           VelesDB (3MB, local)        |
                 |                                       |
  Product page   |  +--------------+  +--------------+  |
  request   ---> |  |   products   |  | user_behavior |  |
                 |  |  collection  |  |    graph      |  |
                 |  | (384D cosine)|  | (edges+nodes) |  |
                 |  +------+-------+  +------+--------+  |
                 |         |                 |           |
                 |         v                 v           |
                 |   vector search    graph traversal    |
                 |   (all users)      (customers only)   |
                 |         |                 |           |
                 |         +---------+-------+           |
                 |                   v                   |
                 |        fused recommendations          |
                 +--------------------------------------+
                                    |
                                    v
                          product snippet (HTML/JSON)

The logic branches on authentication state:

Visitor type	Strategy	Data source
Prospect (anonymous)	Content-based filtering	products collection
Customer (authenticated)	Graph history + vector fusion	behavior graph + products

Step 1 - Storing your product catalog

Install VelesDB first:

pip install velesdb

Each product becomes a vector (also called an embedding) in the products collection.

What is a vector embedding? An embedding is a list of floating-point numbers, for example [0.12, -0.87, 0.45, ...], that positions a piece of content in a multi-dimensional space. Two games that share genre, tags, and gameplay style will end up close to each other in that space; two games that have nothing in common will end up far apart. A text embedding model like sentence-transformers/all-MiniLM-L6-v2 produces vectors of 384 numbers (384 dimensions) for any string you feed it. The more dimensions, the more nuance the model can encode, but also the more memory each vector takes.

In production you would use sentence-transformers/all-MiniLM-L6-v2 (384 dimensions). For local testing without GPU, a deterministic function based on product metadata works fine.

import velesdb
from sentence_transformers import SentenceTransformer

db = velesdb.Database("./gamestore_db")

# 384-dimensional collection, cosine similarity
products = db.get_or_create_collection("products", 384, metric="cosine")

# Initialize the embedding model once at startup
encoder = SentenceTransformer("all-MiniLM-L6-v2")

def embed_game(game: dict) -> list[float]:
    """Turn game metadata into a dense vector."""
    text = f"{game['title']} {game['genre']} {game.get('description', '')} {' '.join(game['tags'])}"
    return encoder.encode(text).tolist()

catalog = [
    {
        "title": "Elden Ring",
        "genre": "RPG",
        "publisher": "FromSoftware",
        "price": 59.99,
        "description": "A vast open-world action RPG set in the Lands Between. Brutal combat, cryptic lore, and interconnected dungeons designed by Hidetaka Miyazaki and George R.R. Martin.",
        "tags": ["soulslike", "open-world", "fantasy", "difficult"],
    },
    {
        "title": "Dark Souls III",
        "genre": "RPG",
        "publisher": "FromSoftware",
        "price": 39.99,
        "description": "The final chapter of the Dark Souls trilogy. Punishing yet rewarding combat, intricate level design, and a dark gothic world on the verge of collapse.",
        "tags": ["soulslike", "fantasy", "hardcore", "gothic"],
    },
    {
        "title": "God of War",
        "genre": "Action-RPG",
        "publisher": "Sony",
        "price": 44.99,
        "description": "Kratos and his son Atreus journey through Norse mythology. A cinematic action RPG combining visceral combat with an emotional story of fatherhood and identity.",
        "tags": ["mythology", "action", "story-rich", "combat"],
    },
    {
        "title": "The Witcher 3",
        "genre": "RPG",
        "publisher": "CD Projekt Red",
        "price": 29.99,
        "description": "An open-world RPG following Geralt of Rivia, a monster hunter for hire. Morally complex quests, a living world, and one of the richest narratives in gaming.",
        "tags": ["open-world", "fantasy", "story-rich", "narrative"],
    },
    {
        "title": "Cyberpunk 2077",
        "genre": "RPG",
        "publisher": "CD Projekt Red",
        "price": 49.99,
        "description": "A first-person open-world RPG set in Night City, a megacity obsessed with power and body modification. Deep story branching, cybernetic upgrades, and a neon-drenched dystopia.",
        "tags": ["sci-fi", "open-world", "story-rich", "action"],
    },
    {
        "title": "FIFA 25",
        "genre": "Sports",
        "publisher": "EA",
        "price": 49.99,
        "description": "The most popular football simulation game. Real teams, real players, Ultimate Team card collecting, and competitive online multiplayer.",
        "tags": ["football", "multiplayer", "simulation"],
    },
    {
        "title": "NBA 2K25",
        "genre": "Sports",
        "publisher": "2K",
        "price": 44.99,
        "description": "The definitive basketball simulation. Authentic player animations, MyCareer story mode, and deep franchise management across all NBA teams.",
        "tags": ["basketball", "multiplayer", "simulation"],
    },
    {
        "title": "Minecraft",
        "genre": "Sandbox",
        "publisher": "Mojang",
        "price": 26.99,
        "description": "A procedurally generated world where you gather resources, build structures, and survive the night. Limitless creativity in survival or creative mode.",
        "tags": ["building", "survival", "creativity", "multiplayer"],
    },
    {
        "title": "Stardew Valley",
        "genre": "Simulation",
        "publisher": "ConcernedApe",
        "price": 13.99,
        "description": "Inherit your grandfather's old farm and build it into something great. Grow crops, raise animals, mine for resources, and build relationships with the villagers.",
        "tags": ["farming", "relaxing", "indie", "rpg-elements"],
    },
    {
        "title": "Hollow Knight",
        "genre": "Metroidvania",
        "publisher": "Team Cherry",
        "price": 14.99,
        "description": "A challenging 2D action adventure set in a vast underground kingdom of insects. Precise combat, hundreds of rooms to explore, and a haunting hand-drawn art style.",
        "tags": ["platformer", "difficult", "exploration", "indie"],
    },
]

# Assign stable integer IDs (database requires int IDs, not strings)
points = []
for i, game in enumerate(catalog, start=1):
    vector = embed_game(game)
    points.append({
        "id": i,
        "vector": vector,
        "payload": {
            "title": game["title"],
            "genre": game["genre"],
            "publisher": game["publisher"],
            "price": game["price"],
            "description": game["description"],
            "tags": game["tags"],
        },
    })

count = products.upsert(points)
print(f"Catalog indexed: {count} games")
# -> Catalog indexed: 10 games

Each game lives as a dense float32 vector alongside its full metadata payload.

Dense vs sparse vector: a dense vector has a non-zero value at almost every position. The 384 floats produced by a language model are all meaningful. A sparse vector, by contrast, has mostly zeros (think TF-IDF word counts). Dense vectors capture semantic meaning; sparse vectors capture exact keyword matches. VelesDB supports both, but for recommendations based on genre and mood, dense embeddings are the right tool.

HNSW (Hierarchical Navigable Small World): the index VelesDB builds automatically on top of your vectors. It organizes vectors into a multi-layer graph so that nearest-neighbor search runs in O(log n) rather than scanning every vector. In practice this means sub-millisecond queries even at catalog scale (hundreds of thousands of products).

Updating the catalog is just another upsert. VelesDB will overwrite the vector and payload for that ID in-place:

# Price drop on Hollow Knight
products.upsert([{
    "id": 10,
    "vector": embed_game(catalog[9]),  # vector unchanged
    "payload": {**catalog[9], "price": 9.99},
}])

Step 2 - Storing user behavior as a graph

User interactions, purchases, views, wishlist additions, live in a graph collection. Each user is a node. Each interaction is a labeled edge pointing to a product node (by product ID).

# Graph collection for behavioral data (no vectors needed here)
behavior = db.create_graph_collection("user_behavior")

Registering a customer

def register_customer(user_id: int, name: str, email: str) -> None:
    """Store customer profile as a graph node payload."""
    behavior.store_node_payload(user_id, {
        "name": name,
        "email": email,
        "type": "customer",
        "member_since": "2024-01-01",
    })

Recording interactions during a session

import time

EDGE_COUNTER = 1000  # simple auto-increment for edge IDs

def record_purchase(user_id: int, product_id: int, price: float) -> None:
    global EDGE_COUNTER
    behavior.add_edge({
        "id": EDGE_COUNTER,
        "source": user_id,
        "target": product_id,
        "label": "purchased",
        "properties": {
            "price_paid": price,
            "timestamp": int(time.time()),
        },
    })
    EDGE_COUNTER += 1

def record_view(user_id: int, product_id: int, duration_s: int) -> None:
    global EDGE_COUNTER
    behavior.add_edge({
        "id": EDGE_COUNTER,
        "source": user_id,
        "target": product_id,
        "label": "viewed",
        "properties": {
            "duration_s": duration_s,
            "timestamp": int(time.time()),
        },
    })
    EDGE_COUNTER += 1

Example: Alice and Bob's histories

# Alice, RPG fan, registered customer
register_customer(1001, "Alice", "alice@example.com")
record_purchase(1001, product_id=1, price=59.99)  # Elden Ring
record_purchase(1001, product_id=2, price=39.99)  # Dark Souls III
record_view(1001, product_id=5, duration_s=12)    # FIFA 25 (glanced at)

# Bob, Sports fan
register_customer(1002, "Bob", "bob@example.com")
record_purchase(1002, product_id=6, price=49.99)  # FIFA 25
record_purchase(1002, product_id=7, price=44.99)  # NBA 2K25

The graph is a persistent adjacency structure.

Graph terminology: a node is an entity (a user, a product). An edge is a directed relationship between two nodes, with a label that describes the relationship type (purchased, viewed, wishlisted). Edges can carry additional data as properties (price paid, timestamp, session duration). get_outgoing(user_id) returns all edges that leave a node, what the user did. get_incoming(product_id) returns all edges that arrive at a node, who interacted with that product. Both run in constant time O(degree), meaning the lookup time depends only on how many edges that node has, not on the total size of the graph.

Step 3 - Generating recommendations

Now the interesting part. Two strategies, one clean branch point.

Strategy A: Prospect, content-based filtering

The visitor is anonymous. We have exactly one signal: the product they are looking at. We use the product's vector to find the closest neighbors in the catalog.

def recommend_for_prospect(
    current_product_id: int,
    top_k: int = 4,
) -> list[dict]:
    """Return games similar to the one being viewed.

    Uses vector similarity search, no user history needed.
    """
    # Retrieve the current product's vector
    points = products.get([current_product_id])
    if not points or points[0] is None:
        return []

    current_vector = points[0]["vector"]

    # Find the nearest neighbors (excluding the product itself)
    results = products.search(vector=current_vector, top_k=top_k + 1)
    return [r for r in results if r["id"] != current_product_id][:top_k]

Usage:

# Visitor is on the Elden Ring page
recs = recommend_for_prospect(current_product_id=1, top_k=4)

print("You might also like:")
for r in recs:
    p = r["payload"]
    print(f"  [{r['score']:.2f}] {p['title']} ({p['genre']}) - EUR {p['price']:.2f}")

You might also like:
  [0.98] Dark Souls III (RPG) - EUR 39.99
  [0.95] God of War (Action-RPG) - EUR 44.99
  [0.91] Hollow Knight (Metroidvania) - EUR 14.99
  [0.87] The Witcher 3 (RPG) - EUR 29.99

The score field is the cosine similarity between the two embedding vectors.

Cosine similarity measures the angle between two vectors, not their distance. If A and B are two embedding vectors:
cosine_similarity(A, B) = (A . B) / (|A| x |B|)
Where A . B is the dot product (sum of element-wise products) and |A| is the norm (length) of the vector. The result is always between -1 and 1. Two vectors pointing in the same direction score 1.0 (identical semantic content). Two vectors at a 90-degree angle score 0.0 (nothing in common). Negative scores mean semantic opposition, rare in practice for game embeddings.

Cosine similarity ignores the magnitude of vectors and only looks at direction, which makes it robust to texts of different lengths. That is why VelesDB uses metric="cosine" by default for text embeddings.

A score of 0.98 means Dark Souls III and Elden Ring point in almost exactly the same direction in the 384-dimensional embedding space. They share soulslike mechanics, FromSoftware aesthetics, and difficulty-focused tags.

Strategy B: Customer, graph traversal + multi-query fusion

Alice is logged in. We know she bought Elden Ring and Dark Souls III. She is now on the God of War page. Rather than ignoring her history, we combine it with the current product to produce a truly personalized snippet.

The approach has three steps. First, traverse the graph to retrieve Alice's purchased product IDs. Then fetch the vectors of those products from the catalog. Finally, run a multi-query search using all those vectors together (including the current product), fused via Reciprocal Rank Fusion (RRF).

def recommend_for_customer(
    user_id: int,
    current_product_id: int,
    top_k: int = 4,
) -> list[dict]:
    """Return personalized recommendations fusing purchase history + current context.

    Falls back to content-based filtering if the user has no purchase history.
    """
    # Check the user exists in the graph
    user_profile = behavior.get_node_payload(user_id)
    if user_profile is None:
        return recommend_for_prospect(current_product_id, top_k)

    # Retrieve purchase history via graph traversal
    outgoing_edges = behavior.get_outgoing(user_id)
    purchased_ids = [
        edge["target"]
        for edge in outgoing_edges
        if edge["label"] == "purchased"
    ]

    if not purchased_ids:
        return recommend_for_prospect(current_product_id, top_k)

    # Fetch vectors for purchased products + current product
    all_ids = purchased_ids + [current_product_id]
    points = products.get(all_ids)
    query_vectors = [p["vector"] for p in points if p is not None]

    # Multi-query search with Reciprocal Rank Fusion (RRF)
    # RRF promotes candidates that rank consistently well across all queries,
    # not just the one with the highest single-query score.
    strategy = velesdb.FusionStrategy.rrf(k=60)  # k=60 is the standard smoothing constant
    results = products.multi_query_search(
        query_vectors,
        top_k=top_k + len(purchased_ids) + 1,
        fusion=strategy,
    )

    # Filter out products already owned and the current product
    exclude_ids = set(purchased_ids) | {current_product_id}
    filtered = [r for r in results if r["id"] not in exclude_ids]
    return filtered[:top_k]

Usage:

# Alice is on the God of War page
recs = recommend_for_customer(user_id=1001, current_product_id=3, top_k=4)

print("Based on your library:")
for r in recs:
    p = r["payload"]
    print(f"  {p['title']} ({p['genre']}) - EUR {p['price']:.2f}")

Based on your library:
  The Witcher 3 (RPG) - EUR 29.99
  Cyberpunk 2077 (RPG) - EUR 49.99
  Hollow Knight (Metroidvania) - EUR 14.99
  Stardew Valley (Simulation) - EUR 13.99

Alice gets story-rich RPGs that her purchase history points to, blended with the God of War context. The Sports games never appear, they are too far in vector space from anything in her history.

How RRF works: instead of averaging raw similarity scores (which are on different scales across queries), RRF combines ranks. For each candidate product, it computes:
RRF_score(product) = sum of  1 / (k + rank_i(product))
                    for each query i
Where rank_i(product) is the position of that product in the result list of query i (1 = best), and k is a smoothing constant (60 by default, from the original 2009 Cormack et al. paper). The sum is taken over all n query vectors (Alice's two purchases + the current product = 3 queries here).

Why k=60? It dampens the advantage of the very top position. Without it, a product ranked 1st in a single query would dominate even if it ranked last in all other queries. With k=60, the difference between rank 1 (score: 1/61 = 0.016) and rank 5 (score: 1/65 = 0.015) is small, rewarding products that appear consistently in the top 10 across all queries rather than explosively first in just one.

Why not average scores directly? Because the raw cosine similarity from query A (say 0.95 for Dark Souls vs Elden Ring) is not comparable to the cosine similarity from query B (say 0.62 for Witcher 3 vs Dark Souls). Rank-based fusion is scale-invariant and works reliably regardless of how concentrated or spread out the individual score distributions are.

Bob, visiting the Minecraft page, gets a completely different result:

recs = recommend_for_customer(user_id=1002, current_product_id=8, top_k=4)
print("Based on your library:")
for r in recs:
    print(f"  {r['payload']['title']} ({r['payload']['genre']})")

Based on your library:
  Stardew Valley (Simulation)
  Terraria (Sandbox)
  NBA 2K25 (Sports)
  FIFA 25 (Sports)

His Sports purchases anchor the recommendations, and Minecraft's sandbox-creative vector pulls in Stardew Valley and Terraria as close neighbors.

Strategy C: Also-bought, collaborative filtering via graph

This one is optional, but the question naturally arises: can we surface products that other users with similar taste have bought? Yes, and the graph makes it straightforward.

The idea: for the product currently being viewed, find everyone who bought it, then aggregate what else they bought. Products that appear frequently across multiple buyers rise to the top.

from collections import Counter

def recommend_collaborative(
    current_product_id: int,
    exclude_ids: set[int] | None = None,
    top_k: int = 4,
) -> list[dict]:
    """Surface products co-purchased by users who also bought the current product.

    This works without any vector math, pure graph traversal.
    """
    if exclude_ids is None:
        exclude_ids = set()
    exclude_ids = exclude_ids | {current_product_id}

    # Who bought this product?
    buyer_edges = behavior.get_incoming(current_product_id)
    buyer_ids = [e["source"] for e in buyer_edges if e["label"] == "purchased"]

    if not buyer_ids:
        return []

    # What else did each buyer purchase?
    co_purchase_counts: Counter = Counter()
    for buyer_id in buyer_ids:
        their_edges = behavior.get_outgoing(buyer_id)
        for edge in their_edges:
            if edge["label"] == "purchased" and edge["target"] not in exclude_ids:
                co_purchase_counts[edge["target"]] += 1

    # Rank by frequency, most co-purchased first
    top_ids = [pid for pid, _ in co_purchase_counts.most_common(top_k)]

    # Fetch full product data
    pts = products.get(top_ids)
    results = [p for p in pts if p is not None]
    for r in results:
        r["co_purchase_count"] = co_purchase_counts[r["id"]]
    return results

Usage, works for both prospects and customers:

# Anyone on the Elden Ring page: what did other buyers also buy?
collab = recommend_collaborative(current_product_id=1, top_k=3)

print("Others who bought this also bought:")
for r in collab:
    p = r["payload"]
    print(f"  [{r['co_purchase_count']} buyers] {p['title']} - EUR {p['price']:.2f}")

Others who bought this also bought:
  [2 buyers] Dark Souls III - EUR 39.99
  [1 buyers] The Witcher 3 - EUR 29.99
  [1 buyers] Hollow Knight - EUR 14.99

For authenticated customers, combine it with the personal list and deduplicate:

def recommend_combined(
    user_id: int,
    current_product_id: int,
    top_k: int = 4,
) -> list[dict]:
    """Merge personalized + collaborative signals, deduplicated."""
    # Get the user's purchase history to exclude
    outgoing = behavior.get_outgoing(user_id)
    owned_ids = {e["target"] for e in outgoing if e["label"] == "purchased"}
    exclude = owned_ids | {current_product_id}

    personal = recommend_for_customer(user_id, current_product_id, top_k=top_k)
    collab = recommend_collaborative(current_product_id, exclude_ids=exclude, top_k=top_k)

    seen_ids: set[int] = set()
    merged: list[dict] = []
    for r in collab + personal:
        if r["id"] not in seen_ids and r["id"] not in exclude:
            seen_ids.add(r["id"])
            merged.append(r)
    return merged[:top_k]

The collaborative signal is particularly valuable for top-selling products (many buyers = rich signal) and for prospects who have no personal history yet. For niche titles with few buyers, fall back gracefully to content-based.## Step 4 - Pushing the recommendation snippet

Now that we have results, we need to push them to the product page. The pattern depends on your stack.

Option A: REST API endpoint (FastAPI example)

from fastapi import FastAPI, Request

app = FastAPI()
db = velesdb.Database("./gamestore_db")
products = db.get_or_create_collection("products", 384, metric="cosine")
behavior = db.get_graph_collection("user_behavior")

@app.get("/api/recommendations/{product_id}")
async def get_recommendations(product_id: int, request: Request) -> dict:
    """Return product recommendations for a given product page.

    Reads 'X-User-Id' header to distinguish prospects from customers.
    """
    user_id_header = request.headers.get("X-User-Id")

    if user_id_header is None:
        # Anonymous visitor, content-based
        recs = recommend_for_prospect(product_id, top_k=4)
        label = "Players also explored"
    else:
        # Authenticated customer, personalized
        user_id = int(user_id_header)
        recs = recommend_for_customer(user_id, product_id, top_k=4)
        label = "Based on your library"

    return {
        "label": label,
        "items": [
            {
                "id": r["id"],
                "title": r["payload"]["title"],
                "genre": r["payload"]["genre"],
                "price": r["payload"]["price"],
                "score": round(r["score"], 3),
            }
            for r in recs
        ],
    }

A frontend call then becomes straightforward:

// On the product page (React/Vue/vanilla JS)
async function loadRecommendations(productId) {
  const headers = userId ? { "X-User-Id": userId } : {};
  const res = await fetch(`/api/recommendations/${productId}`, { headers });
  const data = await res.json();

  renderSnippet(data.label, data.items);
}

Option B: Synchronous Python (Django, Flask, server-rendered)

If your stack renders HTML server-side, call the recommendation functions directly in your view and inject the results into the template context. VelesDB queries are synchronous and fast enough to inline:

# Django view (simplified)
def product_detail(request, product_id):
    user_id = request.user.id if request.user.is_authenticated else None

    if user_id:
        recs = recommend_for_customer(user_id, product_id, top_k=4)
        rec_label = "Based on your library"
    else:
        recs = recommend_for_prospect(product_id, top_k=4)
        rec_label = "Players also explored"

    return render(request, "product.html", {
        "product": get_product(product_id),
        "recommendations": recs,
        "rec_label": rec_label,
    })

The typical latency for a cold vector search on a catalog of 50,000 products is under 5ms on a standard developer machine. The graph traversal (get_outgoing) is O(degree), so the lookup time is proportional only to the number of edges that user has, not to the total number of users in the graph. For a customer with 50 purchases, it is effectively instant.

Keeping data fresh

A recommendation engine is only as good as its data freshness. Two operations keep it current.

Adding a new product to the catalog:

def add_product(product_id: int, game_metadata: dict) -> None:
    vector = embed_game(game_metadata)
    products.upsert([{
        "id": product_id,
        "vector": vector,
        "payload": game_metadata,
    }])
    print(f"Product {game_metadata['title']} indexed.")

Recording a purchase after checkout:

def on_purchase_complete(user_id: int, product_id: int, price: float) -> None:
    """Hook called by the order confirmation handler."""
    record_purchase(user_id, product_id, price)
    # The next recommendation call for this user will immediately
    # reflect this purchase, no nightly batch needed.

Because the graph is persistent (VelesDB writes to disk on each edge insertion), restarting the server does not lose behavioral data. The product collection is also durable, it survives restarts and only needs to be re-indexed when the catalog changes.

Deployment options

"Local-first" does not mean running on the end-user's laptop. For a web store, it means VelesDB lives inside your infrastructure, no third-party ML service involved. Three deployment modes are available depending on your stack.

Mode 1: Embedded (what this article uses)

VelesDB runs in the same process as your Python backend. The pip install velesdb package compiles the engine to a native extension that is imported directly:

[Browser] --> HTTP --> [FastAPI / Django process]
                           |__ velesdb (in-process, no network hop)
                                 |__ products collection
                                 |__ user_behavior graph

Concurrency: the Python GIL (Global Interpreter Lock) is held during search() and upsert() calls. This means a single Python process serializes concurrent VelesDB calls. Parallel threads do not speed up vector search. Each search on a 50k-product catalog takes roughly 0.5ms; at that speed a single process can still handle a few hundred recommendations per second. But for real production concurrency, the correct deployment is multiple worker processes:

# Each worker is a separate OS process with its own VelesDB instance
# Python's GIL does not apply across processes
uvicorn main:app --workers 4 --host 0.0.0.0 --port 8000

Each worker loads the database independently. Writes (new purchases) need to reach all workers, use a message queue (Redis pub/sub, Kafka) to fan out behavioral events, or switch to Mode 2 below.

Best for: Python shops (FastAPI, Django, Flask) with moderate traffic. Multi-worker setup handles hundreds to low thousands of concurrent recommendation requests.

Mode 2: Standalone server (velesdb-server)

VelesDB ships a separate Rust binary that exposes a REST API. You run it as a sidecar container and call it over HTTP from any language.

# Docker
docker run -p 8080:8080 -v velesdb_data:/data ghcr.io/cyberlife-coder/velesdb

# From cargo
cargo install velesdb-server && velesdb-server --port 8080 --data-dir ./data

[Browser] --> HTTP --> [Node.js / Java / Ruby backend]
                           |__ HTTP --> [velesdb-server :8080]
                                           |__ products collection
                                           |__ user_behavior graph

Then the recommendation call from any language becomes a plain HTTP POST:

# Search for similar products (replaces products.search() in Python)
curl -X POST http://localhost:8080/collections/products/search \
  -H "Content-Type: application/json" \
  -d '{"vector": [0.12, -0.87, ...], "top_k": 5}'

Best for: polyglot stacks, microservices, or when multiple backend instances need to share the same vector index.

Mode 3: WebAssembly (client-side)

VelesDB compiles to WASM via the @wiscale/velesdb-wasm npm package. The search runs entirely in the browser. The product catalog is shipped once and queried locally in the session, with no server round-trip at all.

npm install @wiscale/velesdb-wasm

import init, { VectorStore } from '@wiscale/velesdb-wasm';

await init();
const store = new VectorStore(384, 'cosine');

// Catalog loaded once on page init (from your CDN or API)
store.insert(1n, new Float32Array(eldenRingEmbedding));
store.insert(2n, new Float32Array(darkSoulsEmbedding));
// ...

// Search runs in the browser, zero server call
const results = store.search(new Float32Array(currentProductEmbedding), 4);

[Browser]
  |__ velesdb-wasm (in-browser, SIMD-optimized)
        |__ products loaded from CDN on first visit
        |__ search() runs in < 1ms client-side

Best for: progressive enhancement (instant recommendations even before the API responds), offline-capable PWAs, or privacy-first architectures where user profile vectors never leave the device.

Mode	Language	Extra infra	Latency	Use case
Embedded	Python only	None	~1ms in-process	FastAPI/Django monolith
Server	Any	One container	~2-5ms + network	Polyglot / microservices
WASM	JavaScript	None	< 1ms in browser	Offline, privacy-first

For the rest of this article we use the embedded mode (Python bindings), but the recommendation logic is identical regardless of which mode you choose. Only the transport layer changes.

Practical limits to keep in mind

This approach shines for catalogs up to roughly 500,000 products on a single machine (HNSW index fits in RAM). Beyond that, you would need to shard by genre cluster or move to a distributed setup, which is outside the current VelesDB scope.

The quality of the recommendations depends directly on the quality of the embeddings. With generic tag concatenation and a small model like all-MiniLM-L6-v2, you get reasonable clusters. With a domain-specific model fine-tuned on game reviews, results improve significantly. The VelesDB API stays the same regardless of the embedding model you choose.

The behavioral graph is in-memory within a graph collection and persists to disk via flush(). For very high-traffic stores (millions of edge writes per hour), you would want to batch write events and call flush() periodically rather than on every edge insertion.

The complete flow in one diagram

User visits product page
        |
        +-- always ---------> collaborative signal
        |                      behavior.get_incoming(product_id)  [who bought it?]
        |                      behavior.get_outgoing(buyer_id)    [what else they bought?]
        |                      rank by co-purchase frequency
        |
        +-- anonymous? ------> content-based search
        |                      products.search(current_vector, top_k=4)
        |                              |
        +-- authenticated? --> graph traversal + vector fusion
                               behavior.get_outgoing(user_id)    [history]
                               products.get(purchased_ids)       [history vectors]
                               products.multi_query_search(
                                   [*history_vecs, current_vec],
                                   fusion=FusionStrategy.rrf()
                               )
                                       |
                               filter out already-owned
                                       |
                               merge(collab + personal), deduplicate
                                       |
                               return top_k as JSON/HTML snippet

What this architecture leaves out: price as a signal

One thing worth noticing: price is stored in every product's payload, but it plays no role in the recommendations above. That is a deliberate simplification. In practice, a EUR 14.99 indie game and a EUR 59.99 AAA title occupy the same vector space if their descriptions are similar enough, and nothing in the current setup prevents recommending a EUR 60 game to a customer who has only ever bought EUR 10 titles.

There are a few ways to bring price into the picture, depending on the tradeoffs you are willing to make. The simplest is a post-filter: after the vector search returns its top candidates, discard anything outside the customer's observed price range. No change to the index, no change to the embedding, just a filter on the payload. A more ambitious approach would encode price as an additional embedding dimension, either by appending a normalized price feature to the raw text embedding before indexing, or by building a separate "price-tier" collection and fusing its results with the semantic results via RRF. The latter keeps concerns separate and lets you tune the weight of price vs. semantic similarity independently.

Neither of these is hard to add on top of what we have built here. The VelesDB API stays the same either way. Worth thinking about before you go live.

Complete runnable example

Copy and run. Requires only pip install velesdb. For real semantic embeddings, also install sentence-transformers and flip the flag at the top.

"""
Complete demo: recommendation engine with VelesDB 1.12.0
  pip install velesdb
  pip install sentence-transformers  # optional, for real embeddings
"""

import shutil
import hashlib
import time
from collections import Counter

import numpy as np
import velesdb

# Set True if sentence-transformers is installed
USE_REAL_EMBEDDINGS = False
EMBED_DIM = 384
DB_PATH = "./demo_gamestore_db"

if USE_REAL_EMBEDDINGS:
    from sentence_transformers import SentenceTransformer
    encoder = SentenceTransformer("all-MiniLM-L6-v2")

    def embed_game(game: dict) -> list[float]:
        text = f"{game['title']} {game['genre']} {game.get('description', '')} {' '.join(game['tags'])}"
        return encoder.encode(text).tolist()
else:
    def embed_game(game: dict) -> list[float]:
        text = f"{game['title']} {game['genre']} {game.get('description', '')} {' '.join(game['tags'])}"
        seed = int(hashlib.sha256(text.encode()).hexdigest()[:8], 16)
        rng = np.random.default_rng(seed)
        v = rng.standard_normal(EMBED_DIM).astype(np.float32)
        return (v / np.linalg.norm(v)).tolist()

catalog = [
    {"title": "Elden Ring", "genre": "RPG", "publisher": "FromSoftware", "price": 59.99,
     "description": "A vast open-world action RPG set in the Lands Between. Brutal combat, cryptic lore, and interconnected dungeons designed by Hidetaka Miyazaki and George R.R. Martin.",
     "tags": ["soulslike", "open-world", "fantasy", "difficult"]},
    {"title": "Dark Souls III", "genre": "RPG", "publisher": "FromSoftware", "price": 39.99,
     "description": "The final chapter of the Dark Souls trilogy. Punishing yet rewarding combat, intricate level design, and a dark gothic world on the verge of collapse.",
     "tags": ["soulslike", "fantasy", "hardcore", "gothic"]},
    {"title": "God of War", "genre": "Action-RPG", "publisher": "Sony", "price": 44.99,
     "description": "Kratos and his son Atreus journey through Norse mythology. A cinematic action RPG combining visceral combat with an emotional story of fatherhood and identity.",
     "tags": ["mythology", "action", "story-rich", "combat"]},
    {"title": "The Witcher 3", "genre": "RPG", "publisher": "CD Projekt Red", "price": 29.99,
     "description": "An open-world RPG following Geralt of Rivia, a monster hunter for hire. Morally complex quests, a living world, and one of the richest narratives in gaming.",
     "tags": ["open-world", "fantasy", "story-rich", "narrative"]},
    {"title": "Cyberpunk 2077", "genre": "RPG", "publisher": "CD Projekt Red", "price": 49.99,
     "description": "A first-person open-world RPG set in Night City, a megacity obsessed with power and body modification. Deep story branching, cybernetic upgrades, and a neon-drenched dystopia.",
     "tags": ["sci-fi", "open-world", "story-rich", "action"]},
    {"title": "FIFA 25", "genre": "Sports", "publisher": "EA", "price": 49.99,
     "description": "The most popular football simulation game. Real teams, real players, Ultimate Team card collecting, and competitive online multiplayer.",
     "tags": ["football", "multiplayer", "simulation"]},
    {"title": "NBA 2K25", "genre": "Sports", "publisher": "2K", "price": 44.99,
     "description": "The definitive basketball simulation. Authentic player animations, MyCareer story mode, and deep franchise management across all NBA teams.",
     "tags": ["basketball", "multiplayer", "simulation"]},
    {"title": "Minecraft", "genre": "Sandbox", "publisher": "Mojang", "price": 26.99,
     "description": "A procedurally generated world where you gather resources, build structures, and survive the night. Limitless creativity in survival or creative mode.",
     "tags": ["building", "survival", "creativity", "multiplayer"]},
    {"title": "Stardew Valley", "genre": "Simulation", "publisher": "ConcernedApe", "price": 13.99,
     "description": "Inherit your grandfather's old farm and build it into something great. Grow crops, raise animals, mine for resources, and build relationships with the villagers.",
     "tags": ["farming", "relaxing", "indie", "rpg-elements"]},
    {"title": "Hollow Knight", "genre": "Metroidvania", "publisher": "Team Cherry", "price": 14.99,
     "description": "A challenging 2D action adventure set in a vast underground kingdom of insects. Precise combat, hundreds of rooms to explore, and a haunting hand-drawn art style.",
     "tags": ["platformer", "difficult", "exploration", "indie"]},
]

shutil.rmtree(DB_PATH, ignore_errors=True)
db = velesdb.Database(DB_PATH)
products = db.get_or_create_collection("products", EMBED_DIM, metric="cosine")
behavior = db.create_graph_collection("user_behavior")

points = []
for i, game in enumerate(catalog, start=1):
    points.append({
        "id": i,
        "vector": embed_game(game),
        "payload": {k: game[k] for k in ("title", "genre", "publisher", "price", "description", "tags")},
    })
print(f"Catalog indexed: {products.upsert(points)} games")

behavior.store_node_payload(1001, {"name": "Alice"})
behavior.add_edge({"id": 1, "source": 1001, "target": 1, "label": "purchased", "properties": {"price_paid": 59.99, "timestamp": int(time.time())}})
behavior.add_edge({"id": 2, "source": 1001, "target": 2, "label": "purchased", "properties": {"price_paid": 39.99, "timestamp": int(time.time())}})

behavior.store_node_payload(1002, {"name": "Bob"})
behavior.add_edge({"id": 3, "source": 1002, "target": 6, "label": "purchased", "properties": {"price_paid": 49.99, "timestamp": int(time.time())}})
behavior.add_edge({"id": 4, "source": 1002, "target": 7, "label": "purchased", "properties": {"price_paid": 44.99, "timestamp": int(time.time())}})


def recommend_for_prospect(current_product_id: int, top_k: int = 4) -> list[dict]:
    pts = products.get([current_product_id])
    if not pts or pts[0] is None:
        return []
    results = products.search(vector=pts[0]["vector"], top_k=top_k + 1)
    return [r for r in results if r["id"] != current_product_id][:top_k]


def recommend_for_customer(user_id: int, current_product_id: int, top_k: int = 4) -> list[dict]:
    user_profile = behavior.get_node_payload(user_id)
    if user_profile is None:
        return recommend_for_prospect(current_product_id, top_k)
    outgoing_edges = behavior.get_outgoing(user_id)
    purchased_ids = [e["target"] for e in outgoing_edges if e["label"] == "purchased"]
    if not purchased_ids:
        return recommend_for_prospect(current_product_id, top_k)
    all_ids = purchased_ids + [current_product_id]
    query_vectors = [p["vector"] for p in products.get(all_ids) if p is not None]
    strategy = velesdb.FusionStrategy.rrf(k=60)
    results = products.multi_query_search(query_vectors, top_k=top_k + len(purchased_ids) + 1, fusion=strategy)
    exclude_ids = set(purchased_ids) | {current_product_id}
    return [r for r in results if r["id"] not in exclude_ids][:top_k]


def recommend_collaborative(current_product_id: int, exclude_ids: set = None, top_k: int = 4) -> list[dict]:
    if exclude_ids is None:
        exclude_ids = set()
    exclude_ids = exclude_ids | {current_product_id}
    buyer_ids = [e["source"] for e in behavior.get_incoming(current_product_id) if e["label"] == "purchased"]
    if not buyer_ids:
        return []
    counts: Counter = Counter()
    for bid in buyer_ids:
        for e in behavior.get_outgoing(bid):
            if e["label"] == "purchased" and e["target"] not in exclude_ids:
                counts[e["target"]] += 1
    pts = products.get([pid for pid, _ in counts.most_common(top_k)])
    results = [p for p in pts if p is not None]
    for r in results:
        r["co_purchase_count"] = counts[r["id"]]
    return results


def show(label, recs):
    print(f"\n  {label}:")
    for r in recs:
        p = r["payload"]
        score = f"score={r['score']:.3f}" if "score" in r else f"buyers={r.get('co_purchase_count')}"
        print(f"    [{score}] {p['title']} ({p['genre']}) - EUR {p['price']:.2f}")


print("\nStrategy A: Prospect on Elden Ring page")
show("Players also explored", recommend_for_prospect(1))

print("\nStrategy B: Alice on God of War page (owns Elden Ring + Dark Souls III)")
show("Based on your library", recommend_for_customer(1001, 3))

print("\nStrategy B: Bob on Minecraft page (owns FIFA 25 + NBA 2K25)")
show("Based on your library", recommend_for_customer(1002, 8))

print("\nStrategy C: Collaborative filtering on Elden Ring page")
show("Others who bought this also bought", recommend_collaborative(1))

shutil.rmtree(DB_PATH, ignore_errors=True)

With USE_REAL_EMBEDDINGS = False the vectors are deterministic (no model required, scores stay low). Flip it to True after pip install sentence-transformers to get scores above 0.85 and semantically meaningful clusters.

Getting started

VelesDB on GitHub, about 3MB binary, source-available under the VelesDB Core License 1.0 (based on ELv2)
Documentation and examples

The project is still young. A star on GitHub helps other developers discover it, and I am always looking for partners and contributors who want to build on local-first AI data infrastructure. Details on velesdb.com.

What recommendation strategy are you running in production today, pure content-based, collaborative filtering, or something hybrid? Drop a comment below.

Find duplicate photos on your machine in 0.3ms - no cloud, no GPU

Julien L — Sun, 05 Apr 2026 00:47:22 +0000

You have 10,000 photos on your laptop.

Some are duplicates. Some are resized. Some are cropped versions of the same scene.

Your brain instantly knows they're related.

Your computer? It thinks they're completely different files.

That's the problem we're fixing today.

The usual approach is wrong

Most image search systems do this:

"Just use embeddings + cosine similarity"

It works... until it doesn't.

Because you're mixing two completely different problems:

"Is this the same image?" (pixel-level)
"Is this the same scene?" (semantic-level)

Those are not the same question.
And one metric can't answer both well.

The fix: stop using one metric

I split the problem in two.

A two-pass pipeline:

⚡ Pass 1 - fast filter (Hamming distance)
🧠 Pass 2 - semantic re-rank (CLIP + Euclidean)

Think of it like this:

The Bouncer and the Detective

Imagine a nightclub with very strict entry rules.

🕶️ The Bouncer (Hamming distance)

He looks at you for one second. Decides: "close enough" or "no way." Super fast, but shallow. He catches obvious fakes instantly, but a good disguise fools him.

This is perceptual hashing (dHash): turns images into 256-bit fingerprints and compares them by counting differing bits. Runs in microseconds.

🔍 The Detective (CLIP + Euclidean)

For the few people the bouncer let through, the detective runs a thorough investigation. He understands what's really going on. Slower, but almost never wrong.

This is CLIP: maps images into a 512-dimensional semantic space and compares meaning using Euclidean distance.

Query image
     |
     v
[ Bouncer: Hamming ]  ← 0.04ms
     |
 shortlist (top 8)
     |
     v
[ Detective: CLIP ]   ← 0.27ms
     |
     v
Final ranking          Total: 0.31ms

Why this works (and single-metric systems fail)

Take a beach photo. Create two variants: a resize and a crop.

Variant	Hamming (pixels)	CLIP (meaning)	Reality
Resized copy	3 (nearly identical)	0.44 (noticeable gap)	"Same image, just smaller"
Square crop	71 (very different)	0.15 (nearly identical)	"Same beach, different framing"

What happens?

Hamming says: resized = same ✅ / cropped = different ❌
CLIP says: resized = kinda close / cropped = almost identical ✅

👉 Alone, both are wrong.
👉 Together, they're right.

What's actually happening under the hood

The Bouncer's trick: turning photos into barcodes

dHash turns any image into a binary barcode in three steps:

Shrink the image to a 16x16 grayscale grid (256 squares)
Compare each square to its right neighbor: "Is it darker?" Yes = 1, No = 0
Read the answers: [1, 0, 1, 1, 0, 0, 1, ...] (256 bits)

Why is this brilliant? When you resize a photo, the dark squares stay darker than their neighbors. The barcode barely changes. Even JPEG compression or brightness tweaks leave it almost identical.

Comparing two barcodes = counting differing bits = Hamming distance.

This is insanely fast because CPUs have a dedicated instruction for it: popcount.

Score 0 → identical image
Score ~10 → near-duplicate
Score ~128 → random / unrelated

The Detective's map: CLIP as an "Idea Machine"

CLIP maps images into a semantic space. Think of it as a geographic map of meaning:

Photos of beaches cluster in the North
Photos of cities cluster in the South
Photos of dogs cluster in the East

Two photos close on the map "mean" the same thing, even if one is a drawing and the other a photograph.

We normalize vectors and use Euclidean distance.

Yes, cosine would work too. But Euclidean is: (1) easier to interpret (0 to 2 scale), and (2) SIMD-friendly via fma instructions, making it slightly faster in VelesDB®'s HNSW index.

Score 0 → identical meaning
Score < 0.5 → strong semantic match
Score > 1.0 → different content

Setup (local-first, no cloud)

pip install velesdb imagehash open-clip-torch Pillow

No Docker. No API keys. No external calls.

pip install velesdb downloads a pre-built wheel with the compiled Rust binary included. Nothing else to install.

Everything runs locally. Your photos never leave your machine.

Step 1: give the Bouncer his barcodes

import os
import time
import imagehash
from PIL import Image
import velesdb

PHOTO_DIR = "./my_photos"
HASH_SIZE = 16  # 16x16 grid = 256-bit barcode

db = velesdb.Database("./image_search_db")

def compute_barcode(img_path, hash_size=HASH_SIZE):
    """Turn an image into a binary barcode for the Bouncer."""
    img = Image.open(img_path)
    h = imagehash.dhash(img, hash_size=hash_size)
    return [float(b) for b in h.hash.flatten()]

bouncer = db.get_or_create_collection(
    "perceptual_hashes",
    dimension=HASH_SIZE * HASH_SIZE,  # 256
    metric="hamming"
)

photos = sorted(
    f for f in os.listdir(PHOTO_DIR)
    if f.lower().endswith((".jpg", ".jpeg", ".png", ".webp"))
)

t0 = time.time()
for i, filename in enumerate(photos):
    path = os.path.join(PHOTO_DIR, filename)
    bouncer.upsert(
        i + 1,
        vector=compute_barcode(path),
        payload={"filename": filename, "path": path}
    )
print(f"Indexed {len(photos)} barcodes in {(time.time()-t0)*1000:.1f}ms")

The key line: metric="hamming".

This tells VelesDB the vectors are binary and should be compared with popcount, accelerated by SIMD instructions (AVX-512, AVX2, or NEON depending on your CPU).

Step 2: give the Detective his map

import open_clip
import torch

model, _, preprocess = open_clip.create_model_and_transforms(
    "ViT-B-32", pretrained="laion2b_s34b_b79k"
)
model.eval()

def compute_meaning(img_path):
    """Place an image on the Detective's map of meaning."""
    img = Image.open(img_path).convert("RGB")
    with torch.no_grad():
        tensor = preprocess(img).unsqueeze(0)
        features = model.encode_image(tensor)
        features /= features.norm(dim=-1, keepdim=True)
        return features.squeeze().numpy().tolist()

detective = db.get_or_create_collection(
    "clip_features",
    dimension=512,
    metric="euclidean"
)

t0 = time.time()
for i, filename in enumerate(photos):
    path = os.path.join(PHOTO_DIR, filename)
    detective.upsert(
        i + 1,
        vector=compute_meaning(path),
        payload={"filename": filename, "path": path}
    )
print(f"Indexed {len(photos)} meanings in {time.time()-t0:.1f}s")

Same database, different metric, different index. VelesDB handles the routing internally.

CLIP indexing is slower (~91ms/image on CPU) because it runs a vision transformer. But this is a one-time cost. Once indexed, searches are sub-millisecond.

Step 3: the two-pass search

This is the part most people get wrong.

Most implementations do this ❌:

Run CLIP on the entire library, or
Run one CLIP query per candidate (O(n) searches)

That kills performance.

The correct pattern ✅: one CLIP query, then join the scores.

def find_similar(query_path, shortlist_k=8, final_k=5):
    """Two-pass search: Bouncer filters, Detective re-ranks."""

    # --- Pass 1: The Bouncer (instant) ---
    query_barcode = compute_barcode(query_path)
    t0 = time.time()
    fast_candidates = bouncer.search(vector=query_barcode, top_k=shortlist_k)
    bouncer_ms = (time.time() - t0) * 1000

    # --- Pass 2: The Detective (thorough) ---
    # ONE single CLIP query. Not N. This is what makes it scale.
    query_meaning = compute_meaning(query_path)
    t0 = time.time()
    all_meanings = detective.search(
        vector=query_meaning, top_k=shortlist_k * 2
    )
    meaning_scores = {r["id"]: r["score"] for r in all_meanings}

    # Re-rank the Bouncer's shortlist with the Detective's scores
    reranked = []
    for c in fast_candidates:
        reranked.append({
            "filename": c["payload"]["filename"],
            "bouncer": c["score"],
            "detective": meaning_scores.get(c["id"], float("inf")),
        })
    reranked.sort(key=lambda x: x["detective"])
    detective_ms = (time.time() - t0) * 1000

    print(f"Bouncer: {bouncer_ms:.2f}ms | Detective: {detective_ms:.2f}ms | "
          f"Total: {bouncer_ms + detective_ms:.2f}ms")
    return reranked[:final_k]

results = find_similar("./my_photos/beach_1.jpg")

Output:

Bouncer: 0.04ms | Detective: 0.27ms | Total: 0.31ms

Reading the scores

Image	Bouncer	Detective	Human verdict
`beach_1.jpg`	0	0.0000	"That IS the original."
`beach_1_square.jpg`	71	0.1459	"Same beach, different crop."
`beach_1_small.jpg`	3	0.4418	"Same photo, just shrunk."
`city_2.jpg`	113	0.5636	"Different photo entirely."
`flowers_1.jpg`	106	0.9495	"Not even the same subject."

Look at the re-ordering. With the Bouncer alone, beach_1_small would be #2 (only 3 bits different). But the Detective promotes beach_1_square to #2, because semantically, that cropped beach is much closer to the original.

The Bouncer catches the easy cases. The Detective catches the hard ones.

Performance at scale

Indexing has two very different costs:

Library size	Bouncer (dHash)	Detective (CLIP, CPU)	Detective (CLIP, GPU)	Search
1,000 images	< 1s	~90s	~5s	< 1ms
10,000 images	~3s	~15min	~50s	~1ms
100,000 images	~30s	~2.5h	~8min	~2ms

The Bouncer is nearly free. The Detective (CLIP ViT-B-32) is the bottleneck: ~91ms/image on CPU, ~5ms/image on a mid-range GPU.

Searches stay sub-millisecond regardless of library size, thanks to VelesDB's HNSW index with SIMD acceleration.

Pro tip: You don't have to index everything with CLIP upfront. Index only barcodes (instant), search with the Bouncer (< 0.1ms), then compute CLIP only for the 8-10 shortlisted candidates. Total cost: one neural network call instead of N. This is how you scale to millions of images without a GPU.

The real insight: this applies everywhere

This is not just about images.

It's a general pattern: fast approximate filter + slow precise ranking.

You can reuse it everywhere:

Code - MinHash (Jaccard) + embeddings
Documents - SimHash + semantic search
Audio - fingerprints + audio embeddings
Recommendations - rules + dense vectors

VelesDB supports hamming, jaccard, euclidean, cosine, and dot as distance metrics. Mix them in the same database.

Privacy: nothing leaves your machine

This is not a cloud service. VelesDB runs as a ~3MB local binary. Your photos are indexed locally, searched locally, and never uploaded anywhere. No API keys, no external calls, no tracking.

Your photo library is nobody's business but yours.

Getting started

VelesDB® on GitHub - source-available under Elastic License 2.0
Code from the article

A star on the repo helps other developers find the project.

TL;DR

Hamming = fast, pixel-level
CLIP = slower, semantic
Combine both = best of both worlds
0.3ms search, local-first, better results than cosine alone

👉 Stop asking: "What's the best similarity metric?"
👉 Start asking: "What combination of metrics solves my problem?"

What combination would you try? Hamming + Cosine for text? Jaccard + Euclidean for recommendations? Drop a comment below.

I built a database in France because the Cloud Act makes EU data sovereignty impossible

Julien L — Sat, 04 Apr 2026 15:19:53 +0000

In January 2025, the US administration fired three members of the Privacy and Civil Liberties Oversight Board (PCLOB), the independent agency responsible for overseeing US mass surveillance. The European Commission had cited this board 31 times in its adequacy decision for EU-US data transfers. Without a quorum, PCLOB can no longer function.

That same month, an executive order launched a review of all Biden-era national security decisions, including Executive Order 14086, the legal foundation of the EU-US Data Privacy Framework.

If you are a European developer storing user data on AWS, Azure, or GCP, these are not abstract policy events. They affect the legal basis of your data processing.

This is the story of why I built VelesDB®, and why I think the answer to the sovereignty problem is architectural, not legal.

Who is this for?

If you recognize yourself in one of these profiles, this article is for you:

Regulated SaaS builders (healthtech, legaltech, fintech): you process sensitive EU data and your DPO keeps asking where the vectors live.
AI/ML engineers at European companies: you are building RAG pipelines or agent memory and your current stack sends embeddings to three US services.
CTOs and architects evaluating sovereign infrastructure: you need a data layer that satisfies GDPR, the EU Data Act, and upcoming AI Act requirements without stitching together five vendors.
Edge and on-premise developers: you deploy AI on devices, in hospitals, on classified networks, or in locations with no reliable internet.

If none of these apply and you just want to understand why EU data sovereignty is harder than "pick an EU region," keep reading anyway.

Three US laws, one problem

TL;DR: The PATRIOT Act, Cloud Act, and FISA 702 give US authorities three independent legal paths to your data on any US provider, anywhere in the world.

Most developers have heard of the Cloud Act. Fewer realize it is just one piece of a layered legal framework that gives US authorities broad access to data held by US companies, anywhere in the world.

The PATRIOT Act (2001) started this. Section 215 allows the FBI to request "any tangible things" - including electronic business records - for terrorism or intelligence investigations. It was reauthorized through the USA Freedom Act with essentially the same powers. If your cloud provider is a US entity, your data falls under its scope.

The Cloud Act (2018) went further. It requires US companies to hand over data to US authorities when served with a warrant, regardless of where that data is physically stored. If your data sits in AWS Frankfurt or Azure Amsterdam, it does not matter. The obligation follows the provider, not the location. Unlike the PATRIOT Act, the Cloud Act explicitly addresses the extraterritorial question: US jurisdiction follows the company, not the server.

FISA Section 702 is the broadest of the three. Reauthorized in April 2024 with an expanded scope, it now covers any entity "with access to equipment that is or can be used to transmit or store wired or electronic communications." That language is wide enough to include virtually any cloud service, data center operator, or SaaS platform under US jurisdiction. FISA 702 runs through April 2026, and renewal pressure is already building.

Together, these three laws create a layered system where US authorities have multiple legal paths to reach data stored by US providers, regardless of geography.

The collision with European law

TL;DR: GDPR says foreign warrants need a treaty. US surveillance laws bypass treaties. No compliant path exists for US providers in the EU.

On the other side of the Atlantic, the legal framework says the opposite.

GDPR Article 48 states that court orders from third countries are only enforceable in the EU if based on an international agreement such as a Mutual Legal Assistance Treaty (MLAT). The Cloud Act and FISA 702 both bypass MLATs entirely.

The European Data Protection Board has been clear: service providers subject to EU law cannot legally base data transfers to the US solely on Cloud Act requests.

This creates a situation where US cloud providers operating in Europe face two contradictory legal obligations. Comply with a US warrant, and you violate GDPR. Refuse the warrant, and you face US legal penalties. There is no compliant path.

For years, the industry relied on legal patches: Safe Harbor (invalidated by Schrems I in 2015), Privacy Shield (invalidated by Schrems II in 2020), and now the Data Privacy Framework (survived its first legal challenge in September 2025, but an appeal is pending before the CJEU since October 2025). Each patch addresses symptoms. None resolves the structural conflict between US surveillance law and EU privacy law.

Europe is building its defenses. The EU Data Act, applicable since September 12, 2025, now requires cloud providers operating in the EU to implement measures that prevent unlawful third-country government access to data. Providers must challenge conflicting foreign orders and publish the jurisdiction of their infrastructure. The EU AI Act, fully applicable from August 2026, adds data governance and documentation requirements for AI systems, including mandatory registration of high-risk systems in an EU database. These regulations make data sovereignty a compliance requirement, not just a preference.

Why "EU region" does not solve the problem

TL;DR: Cloud Act and FISA 702 follow provider control, not server location. AWS eu-west-1 is a latency decision, not a sovereignty decision.

This is the part that surprises most developers. You might think: "I host on AWS eu-west-1, my data is in Ireland, problem solved."

It is not. The Cloud Act and FISA 702 follow provider control, not data location. If the provider is a US company, US authorities can compel access to any data that company controls, wherever it is stored. Hosting in an EU region is a latency decision, not a sovereignty decision.

Standard Contractual Clauses and Data Processing Agreements help with compliance documentation, but they do not change the fundamental power dynamic: a US court order can reach data stored on US-controlled infrastructure, anywhere in the world.

What this means for AI developers

TL;DR: A typical 2026 AI stack sends embeddings, vectors, graphs, and metadata to four US-controlled services. Every one of them is reachable by a FISA warrant.

Now apply this to the AI stack. A typical AI application in 2026 might look like this:

Embeddings    -> OpenAI API (US company, subject to FISA 702)
Vector store  -> Pinecone (US) or Weaviate Cloud (US)
Graph store   -> Neo4j Aura (US)
Metadata      -> PostgreSQL on AWS eu-west-1 (US provider, Cloud Act applies)

Your AI agent's memory, your users' embeddings, your knowledge graph of business relationships: all of it lives on infrastructure where a foreign government has multiple legal paths to compel access.

For a European SaaS handling health data, legal documents, or financial records, this is not a theoretical risk. With the EU AI Act requiring data governance documentation and the EU Data Act mandating resistance to unlawful foreign access, it is becoming a compliance gap that no amount of contractual paperwork can fully close.

How the alternatives compare

Before building VelesDB, I evaluated the obvious options. Here is what I found:

	VelesDB	Postgres + pgvector	Qdrant (local)	Neo4j (on-prem)	SQLite + extensions
EU sovereignty	Full (no US dependency)	Full (self-hosted)	Full (self-hosted)	Full (self-hosted)	Full (self-hosted)
Vector search	Built-in	Via pgvector extension	Native	Via plugin	Via sqlite-vss
Graph traversal	Built-in (BFS/DFS + MATCH)	Recursive CTEs (limited)	No	Native (Cypher)	No
Agent memory	Built-in SDK	Manual implementation	Manual implementation	Manual implementation	Manual implementation
Single query language	VelesQL (SQL + NEAR + MATCH)	SQL only	REST API only	Cypher only	SQL only
Install complexity	`pip install velesdb`	Server + extension setup	Docker or binary	JVM + server setup	pip + compile extensions
Binary size	~3 MB	~200 MB+	~50 MB	~500 MB+	~5 MB + extensions
License	Elastic License 2.0	PostgreSQL License	Apache 2.0	GPL / commercial	Public domain

Every alternative can achieve sovereignty if self-hosted. The difference is what you get in a single engine versus how many pieces you need to assemble. If you only need vectors, Qdrant is excellent. If you only need graphs, Neo4j is the reference. If you need vectors, graphs, structured queries, and agent memory in one place without running four services, that is the gap VelesDB fills.

Why I built VelesDB

I am based in France. I spent years working with cloud databases, and I kept running into the same problem: every time I needed vectors, graphs, and structured data in a single application, the answer was "stitch together three cloud services from two jurisdictions."

I started building VelesDB because of four convictions:

1. I wanted to stop depending on infrastructure I do not control. Not because US providers build bad technology. They often build the best. But depending on a single country's legal framework for your data infrastructure is a form of technical debt that no amount of engineering can repay if the legal ground shifts. And with FISA 702 up for renewal in 2026 and a potential Schrems III decision looming, the ground is shifting.

2. I wanted my data under my hand, on my own infrastructure. Not behind an API, not on someone else's server, not subject to terms of service I cannot negotiate. Whether it is a local file on my laptop or a database on my company's own server, I want to encrypt it, back it up, audit it, and delete it on my terms. No foreign warrant can reach it because there is no foreign provider in the chain.

3. I wanted one database for the full AI data layer. Vectors for semantic search. Graphs for entity relationships. Structured metadata for queries. Agent memory for conversational intelligence. All in a single engine with a single query language, instead of four services with four APIs and four bills.

4. I wanted to show that deep tech can come from Europe too. France has world-class engineers, strong data protection laws, and a growing AI ecosystem. There is no reason the tools we build our AI systems on should all come from the same two zip codes in California.

The architectural solution: local-first by design

TL;DR: Remove the US provider from the chain entirely. No Cloud Act, no FISA 702, no compliance gap.

VelesDB is a database engine written in Rust. Today it runs embedded inside your process, stores everything in a local directory, and never makes a network call. No account, no API key, no data processor.

pip install velesdb

import velesdb
import numpy as np

# Everything lives in this directory, on your machine
db = velesdb.Database("./my_sovereign_data")

# Vector collection for document embeddings
docs = db.get_or_create_collection("documents", dimension=384)

# Graph store for entity relationships
graph = docs.get_graph_store()

# Agent memory for conversation intelligence
memory = db.agent_memory(384)

Three capabilities in four lines of Python. The entire database is in ./my_sovereign_data, on your machine or your own server. You can encrypt it with your OS tools. You can delete it with rm -rf. No API call required. No Cloud Act applies because there is no cloud. No FISA 702 applies because there is no US provider in the chain.

Working example: a GDPR-compliant document store

Imagine you are building an AI assistant that handles EU regulatory documents. With the EU AI Act requiring documentation of data governance, you need to know exactly where your data is and how it flows:

import numpy as np
import velesdb

db = velesdb.Database("./sovereign_demo")
docs = db.get_or_create_collection("documents", dimension=384)

def mock_embedding(text: str) -> list[float]:
    """Deterministic mock embedding for reproducibility."""
    rng = np.random.RandomState(hash(text) % 2**31)
    vec = rng.randn(384).astype(np.float32)
    vec = vec / np.linalg.norm(vec)
    return vec.tolist()

# Index regulatory documents (VelesDB uses integer IDs)
documents = [
    {"id": 1, "text": "The data subject shall have the right to obtain from the controller the erasure of personal data concerning him or her without undue delay.", "label": "GDPR Art.17"},
    {"id": 2, "text": "The data subject shall have the right to receive the personal data concerning him or her in a structured, commonly used and machine-readable format.", "label": "GDPR Art.20"},
    {"id": 3, "text": "All customer embeddings must be stored within EU jurisdiction and deleted within 30 days of account closure.", "label": "Internal Policy"},
]

for doc in documents:
    embedding = mock_embedding(doc["text"])
    docs.upsert(doc["id"], vector=embedding, payload={"text": doc["text"], "label": doc["label"]})

print(f"Indexed {docs.count()} documents")

# Search by semantic similarity
query_vec = mock_embedding("How do I delete user data?")
results = docs.search(vector=query_vec, top_k=2)

for r in results:
    print(f"  [id={r['id']}] {r['payload']['label']} - score={r['score']:.4f}")
    print(f"    {r['payload']['text'][:80]}...")

At no point did any data leave your machine. If a user exercises their right to erasure under GDPR Article 17, you have exactly one place to look. If an auditor asks you to document your data flows for EU AI Act compliance, the answer fits in one sentence: "It is in a local directory on our server."

Knowledge graph without a cloud dependency

Your AI agent needs to understand relationships, not just text similarity. VelesDB's GraphStore lets you model entity graphs in the same database:

# Continuing from above
graph = docs.get_graph_store()

# Model organizational relationships (edge IDs are integers)
graph.add_edge(100, source=1, target=2, label="REPORTS_TO",
               properties={"since": "2024-01"})
graph.add_edge(101, source=2, target=3, label="MANAGES",
               properties={"department": "engineering"})
graph.add_edge(102, source=1, target=3, label="WORKS_IN",
               properties={"role": "senior_developer"})

# Traverse the graph from node 1
path = graph.traverse_bfs(source=1, max_depth=2)
print(f"Found {len(path)} connections from node 1")
for step in path:
    print(f"  {step.source} --[{step.label}]--> {step.target} (depth={step.depth})")

Same database directory. Same sovereignty guarantees. No Neo4j Aura, no connection string pointing to a US-controlled service.

Agent memory that stays under your roof

When your AI agent builds memory about users, that data is the most sensitive in your stack. Preferences, conversation history, learned procedures: this is exactly the kind of intelligence data that FISA 702's expanded scope was designed to reach.

import time

memory = db.agent_memory(384)

# Semantic memory: facts the agent knows
memory.semantic.store(
    1001,
    "User prefers dark mode and French language",
    mock_embedding("User prefers dark mode and French language")
)

# Episodic memory: events that happened
memory.episodic.record(
    2001,
    "User asked about GDPR compliance for their SaaS product",
    timestamp=int(time.time())
)

# Procedural memory: skills the agent has learned
memory.procedural.learn(
    3001,
    "Handle GDPR deletion request",
    steps=["Identify all user data stores", "Execute deletion in each store", "Generate compliance certificate", "Notify user within 72 hours"],
    confidence=0.9
)

# Query semantic memory
results = memory.semantic.query(
    mock_embedding("What does the user prefer?"),
    top_k=3
)
print(f"Semantic results: {len(results)}")

# Recall recent episodes
recent = memory.episodic.recent(limit=5)
print(f"Recent episodes: {len(recent)}")

# List learned procedures
procedures = memory.procedural.list_all()
print(f"Learned procedures: {len(procedures)}")

When a user exercises their right to be forgotten, you delete one directory. Not four services with four different deletion APIs, four different retention policies, and four different legal jurisdictions.

Querying with VelesQL

VelesDB includes VelesQL, a query language that extends SQL with semantic search (NEAR) and graph traversal (MATCH). You can query your collections with familiar SQL syntax:

# Query all indexed documents using VelesQL
results = db.execute_query("SELECT id, payload FROM documents LIMIT 10")

for r in results:
    print(f"  [id={r['id']}] {r['payload']['label']}")

VelesQL also supports NEAR for vector proximity search and MATCH for graph pattern matching, letting you combine structured queries, semantic search, and graph traversal in a single language. One query language. One database. One jurisdiction.

The bigger picture

The Cloud Act is not going away. FISA 702 is up for renewal. The PATRIOT Act's surveillance provisions remain active. On the EU side, the Data Privacy Framework might survive Schrems III, or it might not. The EU Data Act and AI Act are raising the bar for data governance, not lowering it.

I am not suggesting that every European company should stop using AWS tomorrow. That would be unrealistic and, for many use cases, unnecessary. But for the data layer that gives your AI agents their intelligence - the layer that stores user embeddings, conversation history, and business knowledge - there should be an option that does not require trusting a foreign legal framework that has been invalidated twice in ten years.

VelesDB is that option for developers who want it. A single engine written in Rust, source-available under Elastic License 2.0, that you can read, audit, and deploy on your own infrastructure. Today it runs as an embedded database, local-first by design. Tomorrow, on-premise deployments will extend the same sovereignty guarantees to team and enterprise workloads. The principle stays the same: your data, your servers, your jurisdiction.

It is not designed for multi-node clusters at web scale. It is designed for the use case where sovereignty matters more than horizontal scaling: edge devices, local AI agents, on-premise enterprise systems, regulated applications, and any system where the answer to "where is my data?" should be "right here, on infrastructure I control."

Diversity in infrastructure matters for the same reason biodiversity matters in nature: monocultures are fragile. Europe needs its own tools, not out of protectionism, but because resilience requires alternatives.

Try it in 10 minutes

You do not need to read a whitepaper or schedule a demo. Copy this into a terminal:

pip install velesdb
python3 -c "
import velesdb, numpy as np
db = velesdb.Database('./quickstart')
docs = db.get_or_create_collection('demo', dimension=384)
docs.upsert(1, vector=np.random.randn(384).tolist(), payload={'text': 'hello sovereign world'})
print('Stored:', docs.count(), 'document(s)')
print('Data location: ./quickstart (your machine, your jurisdiction)')
"

Three lines. No Docker, no API key, no account. Your data is in ./quickstart, on your machine.

Want to go further? The quickstart guide on GitHub walks you through vectors, graphs, agent memory, and VelesQL in a single script.

Getting started

VelesDB® on GitHub - source-available under modified Elastic License 2.0 (VelesDB core 1.0 License)
Documentation and examples

A star on the repo helps other developers find the project. We are looking for partners and contributors building sovereign AI infrastructure in Europe - check velesdb.com for details.

Where does your AI agent store its memory today? If a FISA warrant reached your cloud provider tomorrow, would you even be notified? Drop a comment below.

What if SQL could search by meaning? Meet VelesQL

Julien L — Thu, 02 Apr 2026 17:54:41 +0000

You know SQL. You have been writing SELECT, WHERE, and JOIN for years. But the moment you need to search by meaning, traverse a knowledge graph, or rank results by relevance, SQL cannot help you. You reach for a proprietary API, a different client, a different mental model.

What if you did not have to?

VelesQL is a query language that starts where SQL stops. It keeps the syntax you already know and adds three things SQL never had: vector similarity search (NEAR), graph pattern matching (MATCH), and full-text BM25 ranking. One language. One query. One result set.

This article walks through VelesQL from the ground up, with working Python code you can run right now.

Key concepts in 60 seconds

If you have worked with embeddings before, skip ahead. Otherwise, here is what the jargon means:

Vector embedding - a list of numbers (e.g. 384 floats) that captures the meaning of a piece of text. Two sentences that mean similar things will have vectors that are close together in space. The sentence "How to train a dog" and "Puppy obedience tips" produce vectors that are almost identical, even though they share no words.

Cosine similarity - measures the angle between two vectors. A score of 1.0 means identical direction (same meaning), 0.0 means unrelated. This is how VelesDB® decides which documents are "closest" to your query.

HNSW (Hierarchical Navigable Small World) - instead of comparing your query vector against every single vector in the database (which would be slow), HNSW builds a multi-layer navigation graph at insert time. At query time, it hops through this graph to find approximate nearest neighbors in O(log n) instead of O(n). This is the index structure behind NEAR queries.

BM25 (Best Match 25) - the classic text ranking algorithm used by Elasticsearch and Lucene. It scores a document based on how often your search terms appear in it, weighted by how rare each term is across all documents. A document matching a rare term like "HNSW" scores higher than one matching a common term like "data".

RRF (Reciprocal Rank Fusion) - when you combine vector search and text search, you get two independent ranked lists with incompatible scores. RRF merges them by assigning each result a score of 1 / (k + rank) from each list, then summing. No score normalization needed. The k parameter (default: 60) controls how much weight goes to top-ranked results versus the long tail.

The problem with multi-model queries

A typical AI application needs three types of search:

1. Vector search    → "Find documents similar to this embedding"
2. Graph traversal  → "Walk relationships between entities"
3. Full-text search → "Rank documents containing these keywords"

Today, most developers use three separate systems for this. A vector database for embeddings, a graph database for relationships, and Elasticsearch or similar for text. That means three clients, three query languages, three result formats, and a stitching layer to merge everything.

Your app
   → Pinecone client  (proprietary API)
   → Neo4j client     (Cypher)
   → Elasticsearch    (JSON DSL)
   → custom code to merge results

VelesQL replaces this with a single query interface:

Your app
   → VelesDB + VelesQL  (one language, one result set)

Setup

pip install velesdb numpy

import velesdb
import numpy as np

db = velesdb.Database("./velesql_demo")

That is it. No Docker, no server process, no API key. VelesDB runs as a library. The database is a folder on disk.

Creating collections with DDL

VelesQL supports full DDL. You create collections the same way you create tables in SQL:

# Create a vector collection
db.execute_query("CREATE COLLECTION articles (dimension = 384, metric = 'cosine')")

# Create a graph collection with schema
db.execute_query("""
    CREATE GRAPH COLLECTION knowledge (dimension = 384, metric = 'cosine') SCHEMALESS
""")

# Inspect what we have
results = db.execute_query("SHOW COLLECTIONS")
for r in results:
    print(f"  {r['payload']['name']} ({r['payload']['type']})")

Output:

  articles (vector)
  knowledge (graph)

You can also describe a collection to see its configuration:

info = db.execute_query("DESCRIBE COLLECTION articles")
print(info[0]['payload'])
# {'name': 'articles', 'type': 'vector', 'dimension': 384, 'metric': 'Cosine', 'point_count': 0}

Inserting data: what a record actually looks like

Before writing any code, let's understand what VelesDB stores. Each record (called a point) has three parts:

Point {
  id:      1                                            -- unique integer
  vector:  [0.052, 0.014, -0.025, ..., 0.009]          -- 384 floats (the "meaning")
  payload: {                                            -- JSON metadata (filterable)
    "title":    "Vector databases for AI applications",
    "category": "tutorial"
  }
}

The vector is the key difference with a SQL row. It is a list of numbers that encodes the semantic meaning of the record. In production, you generate it with an embedding model:

# In production:
# from sentence_transformers import SentenceTransformer
# model = SentenceTransformer("all-MiniLM-L6-v2")   # 384 dimensions
# vector = model.encode("Vector databases for AI applications").tolist()
# → [0.052, 0.014, -0.025, ..., 0.009]
#
# For this tutorial, we use random vectors to skip the 90MB model download.

Now let's insert data using plain SQL syntax:

def make_vector():
    """Generate a random 384-dim vector for demonstration."""
    v = np.random.rand(384).astype(np.float32)
    return (v / np.linalg.norm(v)).tolist()

np.random.seed(42)

documents = [
    (1, "Vector databases for AI applications", "tutorial"),
    (2, "Graph neural networks explained", "guide"),
    (3, "Building RAG pipelines with Python", "tutorial"),
    (4, "Knowledge graphs in healthcare", "research"),
    (5, "Hybrid search strategies for production", "tutorial"),
]

for doc_id, title, category in documents:
    v = make_vector()
    db.execute_query(
        "INSERT INTO articles (id, vector, title, category) VALUES ($id, $v, $title, $cat)",
        {"id": doc_id, "v": v, "title": title, "cat": category}
    )

print(f"Inserted {len(documents)} documents")

Let's peek at what VelesDB actually stored:

result = db.execute_query("SELECT * FROM articles WHERE category = 'tutorial' LIMIT 1")
import json
print(json.dumps(result[0], indent=2))

{
  "id": 1,
  "score": 1.0,
  "payload": {
    "title": "Vector databases for AI applications",
    "category": "tutorial"
  },
  "vector_score": 1.0,
  "graph_score": null,
  "fused_score": 1.0,
  "bindings": {
    "title": "Vector databases for AI applications",
    "category": "tutorial"
  }
}

This is the anatomy of every VelesDB result. payload holds your metadata (title, category, any JSON field you inserted). bindings mirrors the same data for use in LET expressions. vector_score is the cosine similarity when you use NEAR, graph_score activates with MATCH graph patterns, and fused_score combines both when you use USING FUSION. The vector itself is stored internally and never returned in results - it is only used for similarity computation.

Multi-row INSERT is also supported:

db.execute_query(
    """INSERT INTO articles (id, vector, title, category) VALUES
       ($id1, $v1, 'Sparse embeddings 101', 'tutorial'),
       ($id2, $v2, 'Local-first AI architectures', 'guide')""",
    {"id1": 6, "v1": make_vector(), "id2": 7, "v2": make_vector()}
)

Vector search with NEAR

Here is where VelesQL diverges from SQL. The NEAR keyword performs approximate nearest neighbor search on dense vectors:

query_vector = make_vector()

results = db.execute_query(
    """SELECT id, title, similarity() AS score
       FROM articles
       WHERE vector NEAR $q
       ORDER BY similarity() DESC
       LIMIT 3""",
    {"q": query_vector}
)

for r in results:
    print(f"  [{r['score']:.3f}] {r['payload']['title']}")

Output:

  [0.821] Vector databases for AI applications
  [0.779] Building RAG pipelines with Python
  [0.752] Hybrid search strategies for production

The similarity() function returns the pre-computed search score. You can use it in SELECT, ORDER BY, and even in LET bindings (more on that below).

Combining vector search with metadata filters

Just add AND conditions like you would in SQL:

results = db.execute_query(
    """SELECT id, title, similarity() AS score
       FROM articles
       WHERE vector NEAR $q AND category = 'tutorial'
       ORDER BY similarity() DESC
       LIMIT 5""",
    {"q": query_vector}
)

for r in results:
    print(f"  [{r['score']:.3f}] {r['payload']['title']}")

Only tutorials are returned. The metadata filter runs alongside the vector search, not as a post-filter.

Advanced WHERE: IN, BETWEEN, ILIKE, IS NULL

VelesQL supports the full range of SQL filtering operators. If you know SQL, you already know how to filter in VelesQL:

# IN: filter by a set of values
results = db.execute_query(
    "SELECT id, title FROM articles WHERE category IN ('tutorial', 'research') LIMIT 10"
)

# BETWEEN: range filtering
results = db.execute_query(
    "SELECT id, title FROM articles WHERE price BETWEEN 10 AND 100 LIMIT 10"
)

# ILIKE: case-insensitive pattern matching
results = db.execute_query(
    "SELECT id, title FROM articles WHERE title ILIKE '%ai%' LIMIT 10"
)

# IS NULL / IS NOT NULL
results = db.execute_query(
    "SELECT id, title FROM articles WHERE category IS NOT NULL LIMIT 10"
)

# NOT + compound conditions
results = db.execute_query(
    "SELECT id, title FROM articles WHERE NOT (category = 'draft') AND price > 50 LIMIT 10"
)

ILIKE is particularly useful: it matches case-insensitively, so '%ai%' finds both "AI-Powered Search" and "ai portfolio optimizer". LIKE does the same but case-sensitive.

Full-text search with MATCH

The MATCH keyword performs BM25 full-text search. Remember BM25 from the key concepts section: it ranks documents by term frequency, adjusted by how rare each term is. So MATCH 'graph' will rank "Graph neural networks explained" higher than a document that mentions "graph" once among hundreds of other words.

results = db.execute_query(
    "SELECT id, title FROM articles WHERE title MATCH 'graph' LIMIT 5"
)

for r in results:
    print(f"  {r['payload']['title']}")

Hybrid search: NEAR + MATCH

When you combine NEAR and MATCH in the same WHERE clause, you get two independent ranked lists: one from vector similarity, one from BM25 text scoring. These scores are on completely different scales, so you cannot just add them.

VelesQL solves this with RRF (Reciprocal Rank Fusion). Each result gets a score of 1 / (k + rank) from each list, and the scores are summed. A document ranked #1 by vector and #3 by BM25 gets 1/61 + 1/63 = 0.032. A document ranked #2 by both gets 1/62 + 1/62 = 0.032. RRF naturally rewards documents that appear in both lists, without needing to normalize the raw scores.

results = db.execute_query(
    """SELECT id, title, similarity() AS score
       FROM articles
       WHERE vector NEAR $q AND title MATCH 'AI'
       ORDER BY similarity() DESC
       LIMIT 5""",
    {"q": query_vector}
)

for r in results:
    print(f"  [{r['score']:.3f}] {r['payload']['title']}")

You can also control the fusion strategy explicitly:

results = db.execute_query(
    """SELECT id, title, similarity() AS score
       FROM articles
       WHERE vector NEAR $q AND title MATCH 'AI'
       LIMIT 5
       USING FUSION(strategy = 'rrf', k = 60)""",
    {"q": query_vector}
)

Four fusion strategies are available:

Strategy	Best for	Key parameter
`rrf`	General-purpose (default)	`k` (default: 60)
`weighted`	Custom importance	`weights = [0.7, 0.3]`
`rsf`	Dense + sparse blending	`dense_weight`, `sparse_weight`
`maximum`	Conservative precision	(none)

LET bindings: named scores

VelesQL 3.2 introduced LET bindings. Define a score expression once, use it everywhere:

results = db.execute_query(
    """LET relevance = similarity()
       SELECT id, title, relevance AS score
       FROM articles
       WHERE vector NEAR $q
       ORDER BY relevance DESC
       LIMIT 3""",
    {"q": query_vector}
)

for r in results:
    print(f"  [{r['score']:.3f}] {r['payload']['title']}")

LET bindings shine in hybrid queries where you want to weight multiple score components:

results = db.execute_query(
    """LET hybrid = 0.7 * vector_score + 0.3 * bm25_score
       SELECT id, title, hybrid AS score
       FROM articles
       WHERE vector NEAR $q AND title MATCH 'search'
       ORDER BY hybrid DESC
       LIMIT 5""",
    {"q": query_vector}
)

Bindings can reference earlier bindings, so you can build complex scoring pipelines:

LET base = 0.6 * vector_score + 0.4 * bm25_score
LET boosted = base * 1.5
SELECT *, boosted AS final_score
FROM docs
WHERE vector NEAR $v AND content MATCH 'AI'
ORDER BY boosted DESC
LIMIT 10

Graph queries with MATCH patterns

VelesQL borrows Cypher-style graph patterns. Here is a complete example that builds a knowledge graph and queries it:

import json

# Insert nodes with _labels (required for MATCH pattern matching)
db.execute_query(
    "INSERT NODE INTO knowledge (id = 1, payload = '%s')" %
    json.dumps({"name": "Alice", "role": "engineer", "_labels": ["Person"]})
)
db.execute_query(
    "INSERT NODE INTO knowledge (id = 2, payload = '%s')" %
    json.dumps({"name": "Bob", "role": "researcher", "_labels": ["Person"]})
)
db.execute_query(
    "INSERT NODE INTO knowledge (id = 3, payload = '%s')" %
    json.dumps({"name": "Acme Corp", "industry": "tech", "_labels": ["Company"]})
)

# Add vectors to nodes (needed for combined vector + graph queries)
coll = db.get_collection("knowledge")
coll.upsert(1, vector=make_vector(), payload={"name": "Alice", "role": "engineer", "_labels": ["Person"]})
coll.upsert(2, vector=make_vector(), payload={"name": "Bob", "role": "researcher", "_labels": ["Person"]})
coll.upsert(3, vector=make_vector(), payload={"name": "Acme Corp", "industry": "tech", "_labels": ["Company"]})

# Insert edges
db.execute_query("INSERT EDGE INTO knowledge (source = 1, target = 2, label = 'KNOWS')")
db.execute_query("INSERT EDGE INTO knowledge (source = 1, target = 3, label = 'WORKS_AT')")
db.execute_query("INSERT EDGE INTO knowledge (source = 2, target = 3, label = 'WORKS_AT')")

Cypher-style MATCH in WHERE

Now query the graph using MATCH patterns inside a WHERE clause:

# Find people who know other people
results = db.execute_query(
    "SELECT * FROM knowledge WHERE MATCH (a:Person)-[:KNOWS]->(b) LIMIT 10"
)
for r in results:
    print(f"  {r['payload']['name']} ({r['payload']['role']})")

Output:

  Alice (engineer)

# Find everyone who works at a company
results = db.execute_query(
    "SELECT * FROM knowledge WHERE MATCH (p:Person)-[:WORKS_AT]->(c:Company) LIMIT 10"
)
for r in results:
    print(f"  {r['payload']['name']}")

Output:

  Bob
  Alice

Combining graph + metadata + vector search

This is where VelesQL shines. A single query that walks a graph, filters by metadata, and ranks by vector similarity:

# Find people who work at a company AND are similar to a query vector
results = db.execute_query(
    """SELECT * FROM knowledge
       WHERE vector NEAR $v AND MATCH (p:Person)-[:WORKS_AT]->(c:Company)
       LIMIT 5""",
    {"q": query_vector}
)

# Graph pattern + scalar filter
results = db.execute_query(
    """SELECT * FROM knowledge
       WHERE MATCH (a:Person)-[:WORKS_AT]->(b) AND role = 'engineer'
       LIMIT 10"""
)
for r in results:
    print(f"  {r['payload']['name']} - {r['payload']['role']}")

Edge queries and properties

Query edges directly with SELECT EDGES:

edges = db.execute_query("SELECT EDGES FROM knowledge WHERE source = 1")
for e in edges:
    print(f"  {e['payload']['label']}: {e['payload']['source']} -> {e['payload']['target']}")

Output:

  KNOWS: 1 -> 2
  WORKS_AT: 1 -> 3

Edges can also carry properties:

db.execute_query(
    """INSERT EDGE INTO knowledge (source = 1, target = 2, label = 'COLLABORATES')
       WITH PROPERTIES (project = 'VelesDB', since = 2024)"""
)

Search quality tuning with WITH

Every vector search query can be fine-tuned with a WITH clause:

# Fast search (autocomplete, suggestions)
results = db.execute_query(
    "SELECT id, title FROM articles WHERE vector NEAR $q LIMIT 5 WITH (mode = 'fast')",
    {"q": query_vector}
)

# Accurate search (production queries)
results = db.execute_query(
    "SELECT id, title FROM articles WHERE vector NEAR $q LIMIT 5 WITH (mode = 'accurate')",
    {"q": query_vector}
)

# Custom HNSW parameters
results = db.execute_query(
    """SELECT id, title FROM articles
       WHERE vector NEAR $q LIMIT 5
       WITH (ef_search = 256, rerank = true)""",
    {"q": query_vector}
)

Five quality presets are available:

Mode	ef_search	Best for
`fast`	32	Autocomplete, real-time suggestions
`balanced`	64	Default, good accuracy/speed tradeoff
`accurate`	256	Production search, quality matters
`perfect`	512	Benchmarks, maximum recall
`autotune`	auto	Adapts based on collection size

UPDATE, DELETE, and other DML

VelesQL supports the full CRUD lifecycle:

# Update a field
db.execute_query("UPDATE articles SET category = 'advanced' WHERE id = 2")

# Delete a row (WHERE is mandatory for safety)
db.execute_query("DELETE FROM articles WHERE id = 7")

# Upsert (insert or update)
db.execute_query(
    "UPSERT INTO articles (id, vector, title, category) VALUES ($id, $v, 'Updated article', 'guide')",
    {"id": 2, "v": make_vector()}
)

Set operations: UNION, INTERSECT, EXCEPT

Combine results from multiple queries, just like in SQL:

# UNION: combine tech and finance products, remove duplicates
results = db.execute_query("""
    SELECT id, title FROM articles WHERE category = 'tutorial'
    UNION
    SELECT id, title FROM articles WHERE category = 'guide'
""")

# INTERSECT: find items in both result sets
results = db.execute_query("""
    SELECT id, title FROM articles WHERE category = 'tutorial'
    INTERSECT
    SELECT id, title FROM articles WHERE vector NEAR $q LIMIT 10
""", {"q": query_vector})

# EXCEPT: items in first set but not in second
results = db.execute_query("""
    SELECT id FROM articles WHERE category = 'tutorial'
    EXCEPT
    SELECT id FROM articles WHERE title MATCH 'graph'
""")

N-ary chaining works too: A UNION B UNION C evaluates left to right.

DISTINCT: deduplicate results

# Unique categories
results = db.execute_query("SELECT DISTINCT category FROM articles")

# DISTINCT with vector search (dedup by payload value after search)
results = db.execute_query(
    "SELECT DISTINCT category FROM articles WHERE vector NEAR $q LIMIT 20",
    {"q": query_vector}
)

Temporal queries

Filter by time without converting timestamps manually:

import time

# Insert an event with a timestamp
now = int(time.time())
db.execute_query(
    "INSERT INTO articles (id, vector, title, created_at) VALUES ($id, $v, 'Fresh article', $ts)",
    {"id": 100, "v": make_vector(), "ts": now}
)

# Query using NOW() and INTERVAL
results = db.execute_query(
    "SELECT id, title FROM articles WHERE created_at > NOW() - INTERVAL '24 hours' LIMIT 10"
)

NOW() returns the current Unix timestamp. INTERVAL supports seconds, minutes, hours, days, weeks, and months.

Query introspection with EXPLAIN

Before optimizing, understand what the query planner is doing:

plan = db.execute_query(
    "EXPLAIN SELECT * FROM articles WHERE vector NEAR $q LIMIT 5",
    {"q": query_vector}
)

print(plan[0]['payload']['tree'])

Output:

Query Plan:
├─ VectorSearch
│  ├─ Collection: articles
│  ├─ ef_search: 100
│  └─ Candidates: 5
└─ Limit: 5

Estimated cost: 0.101ms
Index used: HNSW

Index management

Create secondary indexes on metadata fields for faster filtering:

# Create an index on category
db.execute_query("CREATE INDEX ON articles (category)")

# Analyze collection statistics for the query optimizer
db.execute_query("ANALYZE articles")

Agent Memory collections

If you use VelesDB's Agent Memory SDK, the three memory subsystems (semantic, episodic, procedural) are queryable via VelesQL:

memory = db.agent_memory(384)

# Store some facts via the SDK
memory.semantic.store(1, "User prefers Python", make_vector())
memory.semantic.store(2, "User works in healthcare", make_vector())

# Query them with VelesQL
results = db.execute_query(
    """SELECT * FROM _semantic_memory
       WHERE vector NEAR $q
       LIMIT 5 WITH (mode = 'accurate')""",
    {"q": make_vector()}
)

for r in results:
    print(f"  {r['payload']['content']}")

The same works for _episodic_memory (with timestamp filtering) and _procedural_memory (with confidence sorting).

VelesQL vs. the alternatives

Feature	VelesQL	Raw Python API	Pinecone	pgvector (SQL)
Vector NEAR search	Yes	Yes	Yes	Yes (with extensions)
Graph MATCH traversal	Yes	Partial	No	No
Full-text MATCH (BM25)	Yes	No	No	Yes (tsvector)
Hybrid fusion (RRF, weighted)	Yes	Manual	No	No
LET score bindings	Yes	No	No	No
DDL (CREATE, DROP, ALTER)	Yes	Method calls	Dashboard	Yes
EXPLAIN query plan	Yes	No	No	Yes
Temporal (NOW, INTERVAL)	Yes	Manual	No	Yes
Runs locally, no server	Yes	Yes	No	No

The point is not that VelesQL replaces SQL everywhere. It fills a gap: the space where you need vector search, graph queries, and text ranking in one place, without running three separate systems.

VelesDB is still young. JOIN is fully supported for INNER JOIN, but LEFT/RIGHT/FULL JOIN are parsed and produce explicit runtime errors rather than silent failures. MATCH in hybrid mode boosts rather than strictly filters. These are documented tradeoffs, not bugs, and the query planner tells you exactly what it will do via EXPLAIN.

The full VelesQL feature set at a glance

Category	Features
Queries	SELECT, FROM, WHERE, JOIN (INNER), GROUP BY, HAVING, ORDER BY, LIMIT, OFFSET, DISTINCT
Vector	NEAR, SPARSE_NEAR, NEAR_FUSED, similarity(), WITH (quality modes)
Text	MATCH (BM25 full-text search)
Graph	MATCH patterns, variable-length paths, INSERT NODE, INSERT EDGE, SELECT EDGES
Fusion	USING FUSION (rrf, weighted, rsf, maximum)
Scoring	LET bindings, arithmetic ORDER BY, vector_score, bm25_score, graph_score
DML	INSERT, multi-row INSERT, UPSERT, UPDATE, DELETE
DDL	CREATE/DROP COLLECTION, CREATE/DROP INDEX, ALTER COLLECTION, TRUNCATE
Admin	SHOW COLLECTIONS, DESCRIBE, EXPLAIN, ANALYZE, FLUSH
Temporal	NOW(), INTERVAL, temporal arithmetic
Types	Strings, integers, floats, booleans, NULL, vectors, sparse vectors, parameters

The complete specification is on GitHub.

Getting started

VelesDB® on GitHub (~3MB binary, source-available under Elastic License 2.0)
Documentation and examples
VelesQL Specification

If you find the project useful, a star on the repo helps other developers discover it. We are actively looking for partners and contributors who have use cases for hybrid search, check velesdb.com for details.

What query would you write first with VelesQL? I am curious whether the hybrid NEAR + MATCH pattern or the graph traversal feels more useful to your projects. Drop a comment below.

Run your AI assistant fully offline: a local-first architecture

Julien L — Wed, 01 Apr 2026 07:13:25 +0000

What if your AI assistant worked on an airplane? In a hospital? On a classified network?

Most AI stacks fall apart without internet. They depend on OpenAI for inference, Pinecone for vectors, and half a dozen cloud APIs for everything in between. Kill the connection, kill the assistant.

This article builds a complete AI assistant that works offline. Not "mostly offline." Fully offline. After initial setup, you can unplug the ethernet cable and everything still runs.

The cloud dependency problem

Here is a typical AI assistant stack:

User query
   → OpenAI API (inference)          ← needs internet
   → Pinecone/Weaviate (vectors)     ← needs internet
   → Redis (session state)           ← needs server
   → PostgreSQL (structured data)    ← needs server

Four network dependencies. Four points of failure. Four things that do not work on a plane, in a hospital server room, or inside a SCIF.

The local-first stack

Here is the same assistant, rebuilt to run entirely on your machine:

User query
   → Ollama (local LLM)                  ← runs on your CPU/GPU
   → sentence-transformers (embeddings)   ← runs on your CPU
   → VelesDB® (vectors + memory)          ← a file on disk

Three components. Zero network calls. Everything fits on a laptop.

Component	Cloud version	Local version	Size
LLM	OpenAI GPT-4	Ollama + Llama 3	~4GB model
Embeddings	OpenAI ada-002	all-MiniLM-L6-v2	~80MB model
Vector DB	Pinecone	VelesDB	~3MB binary
Memory	Redis + Postgres	VelesDB Agent Memory	included

Setup (the only part that needs internet)

Download everything once. Then go dark.

# 1. Install Ollama (local LLM runtime)
curl -fsSL https://ollama.com/install.sh | sh
ollama pull llama3

# 2. Install Python dependencies
pip install velesdb sentence-transformers requests

# 3. Download the embedding model (first run caches it locally)
python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('all-MiniLM-L6-v2')"

After this, disconnect. Everything below runs without internet.

Step 1: Local embeddings

The embedding model runs entirely on your CPU. No API key. No network call.

from sentence_transformers import SentenceTransformer

model = SentenceTransformer("all-MiniLM-L6-v2")

def embed(text: str) -> list[float]:
    return model.encode(text).tolist()

# Test it
vector = embed("VelesDB runs fully offline")
print(f"Dimension: {len(vector)}")  # 384

Step 2: Store documents in VelesDB

VelesDB is a source-available vector database that runs as a library. No server process. No Docker. Just a folder on disk.

import velesdb
from sentence_transformers import SentenceTransformer

model = SentenceTransformer("all-MiniLM-L6-v2")

def embed(text: str) -> list[float]:
    return model.encode(text).tolist()

# Open a local database (creates a folder on disk)
db = velesdb.Database("./offline_assistant")
collection = db.get_or_create_collection("knowledge", dimension=384)

# Your knowledge base
documents = [
    "Patient records must be stored on-premises per HIPAA regulations.",
    "Air-gapped networks prohibit any outbound internet connections.",
    "Edge devices in manufacturing often lack reliable connectivity.",
    "Privacy-conscious users prefer local processing over cloud APIs.",
    "Retrieval-augmented generation grounds LLM answers in real data.",
    "Vector similarity search finds semantically related documents.",
    "Local-first architectures work offline and sync when connected.",
    "Ollama runs open-weight LLMs locally on consumer hardware.",
]

# Embed and store
for i, doc in enumerate(documents):
    collection.upsert(i, vector=embed(doc), payload={"text": doc})

print(f"Stored {len(documents)} documents")

Step 3: RAG retrieval (offline)

Search your knowledge base by meaning, not keywords:

def retrieve(query: str, top_k: int = 3) -> list[str]:
    results = collection.search(vector=embed(query), top_k=top_k)
    return [r["payload"]["text"] for r in results]

# Test retrieval
context = retrieve("Why would someone need offline AI?")
for doc in context:
    print(f"  - {doc}")

Output:

  - Air-gapped networks prohibit any outbound internet connections.
  - Privacy-conscious users prefer local processing over cloud APIs.
  - Edge devices in manufacturing often lack reliable connectivity.

No internet was used. The embedding model and the vector search both run locally.

Step 4: Agent memory (persistent context)

RAG retrieves documents, but your assistant also needs to remember conversations and learned procedures. VelesDB's Agent Memory SDK handles this with three subsystems:

import time

memory = db.agent_memory(384)

# Semantic memory: facts the agent knows
memory.semantic.store(1, "User prefers concise answers", embed("User prefers concise answers"))
memory.semantic.store(2, "User works in healthcare IT", embed("User works in healthcare IT"))

# Episodic memory: events that happened
memory.episodic.record(1, "User asked about HIPAA compliance", int(time.time()))

# Procedural memory: learned workflows
memory.procedural.learn(
    1,
    "answer_with_context",
    ["retrieve relevant docs", "check episodic memory for prior questions", "generate answer with Ollama"],
    confidence=0.9
)

Now the assistant can recall facts, events, and procedures:

# What does the agent know about the user?
facts = memory.semantic.query(embed("What does the user need?"), top_k=2)
for f in facts:
    print(f"  Fact: {f['content']} (score: {f['score']:.2f})")

# What happened recently?
events = memory.episodic.recent(5)
for e in events:
    print(f"  Event: {e['description']}")

# What procedure should the agent follow?
procedures = memory.procedural.recall(embed("how to answer a question"), top_k=1)
for p in procedures:
    print(f"  Procedure: {p['name']} -> {p['steps']}")

Step 5: Connect to a local LLM

Ollama exposes a local HTTP API on localhost:11434. No internet required.

import requests
import json

OLLAMA_URL = "http://localhost:11434/api/generate"
OLLAMA_MODEL = "llama3"

def check_ollama() -> bool:
    """Verify Ollama is running and has at least one model installed."""
    try:
        r = requests.get("http://localhost:11434/api/tags", timeout=3)
        models = [m["name"] for m in r.json().get("models", [])]
        if not models:
            print("Ollama is running but no models installed.")
            print(f"Run: ollama pull {OLLAMA_MODEL}")
            return False
        if not any(OLLAMA_MODEL in m for m in models):
            print(f"Model '{OLLAMA_MODEL}' not found. Available: {models}")
            return False
        return True
    except requests.ConnectionError:
        print("Ollama is not running. Start it with: ollama serve")
        return False

def ask_local_llm(question: str, context: list[str], facts: list[str]) -> str:
    context_block = "\n".join(f"- {c}" for c in context)
    facts_block = "\n".join(f"- {f}" for f in facts)

    prompt = f"""You are a helpful assistant. Answer the question using ONLY the provided context and facts.

Context (retrieved documents):
{context_block}

Known facts about the user:
{facts_block}

Question: {question}

Answer:"""

    response = requests.post(OLLAMA_URL, json={
        "model": OLLAMA_MODEL,
        "prompt": prompt,
        "stream": False
    }, timeout=120)

    result = response.json()
    if "error" in result:
        raise RuntimeError(f"Ollama error: {result['error']}")
    return result["response"]

The full pipeline

Putting it all together:

def offline_assistant(question: str) -> str:
    # 1. Retrieve relevant documents
    context = retrieve(question, top_k=3)

    # 2. Recall user-specific facts from memory
    facts_results = memory.semantic.query(embed(question), top_k=2)
    facts = [f["content"] for f in facts_results]

    # 3. Check if we have answered something similar before
    events = memory.episodic.recent(5)

    # 4. Ask the local LLM
    answer = ask_local_llm(question, context, facts)

    # 5. Record this interaction in episodic memory
    memory.episodic.record(
        int(time.time()),
        f"Answered: {question[:100]}",
        int(time.time())
    )

    return answer

# Verify Ollama is ready, then use it
if check_ollama():
    answer = offline_assistant("What are the requirements for handling patient data?")
    print(answer)

This entire pipeline runs without a single network call. The embedding model, the vector database, the memory system, and the LLM all execute locally.

Cloud vs. local: a practical comparison

	Cloud stack	Local stack
Works offline	No	Yes
Latency	200-500ms per API call	10-50ms (embeddings), 1-10s (LLM)
Cost	Pay per token/query	Free after download
Privacy	Data leaves your machine	Data never leaves your machine
Setup	API keys, accounts, billing	One-time download
Model quality	GPT-4 level	Good (Llama 3 8B) to great (70B)
Scalability	Unlimited	Limited by hardware

The tradeoff is clear: cloud gives you better models and infinite scale. Local gives you privacy, offline capability, and zero ongoing cost. For many use cases, local is not just "good enough." It is the only option.

Where this matters

Healthcare: HIPAA requires that patient data stays on-premises. A local AI assistant can help clinicians without sending PHI to cloud servers.

Defense and government: Air-gapped networks exist for a reason. An offline AI assistant works behind any security perimeter.

Travel and field work: No Wi-Fi on the plane, no signal in the field. Your assistant still works.

Privacy-conscious users: Some people simply do not want their questions going to a third-party server. Fair enough.

Edge computing: IoT gateways, manufacturing floors, remote sensors. Connectivity is unreliable. Local AI is the only reliable option.

Getting started

Everything you need:

Ollama for local LLM inference
sentence-transformers for local embeddings
VelesDB® for local vector storage and agent memory (~3MB binary, source-available under Elastic License 2.0)

The complete code from this article works as a starting point. Swap in your own documents, adjust the retrieval parameters, and you have a private AI assistant that never phones home.

What is the most interesting offline use case you can think of? I would love to hear about environments where cloud AI simply is not an option. Drop a comment below.

Share memory between AI agents without infrastructure

Julien L — Wed, 01 Apr 2026 06:06:37 +0000

Two AI agents need to collaborate. One researches, the other writes. How do they share what they know?

This is not a theoretical question. Multi-agent systems are the dominant trend in agentic AI right now. Gartner reported a 1445% surge in enterprise inquiries about multi-agent architectures. Every serious AI project is moving from "one big agent" to "specialized agents that cooperate."

But here is the dirty secret: the hard part is not building agents. It is sharing state between them.

The infrastructure tax

When Agent A discovers a fact and Agent B needs to use it, you typically need one of these:

Redis for shared key-value state
PostgreSQL for structured shared data
RabbitMQ/Kafka for message passing
A custom API layer to coordinate everything

That is a lot of moving parts for what is conceptually simple: "remember this, so another agent can find it later."

What if both agents could just read and write to the same file?

The architecture

Here is what we are building: two Python scripts that share one VelesDB database file. The researcher agent gathers facts and records events. The writer agent reads those facts and checks what was already covered.

┌──────────────┐         ┌──────────────────┐         ┌──────────────┐
│  Researcher  │───────▶ │  VelesDB file    │ ◀───────│    Writer    │
│    Agent     │  write  │  (shared state)  │  read   │    Agent     │
│              │         │                  │         │              │
│ - search web │         │ semantic memory  │         │ - read facts │
│ - store facts│         │ episodic memory  │         │ - check done │
│ - log events │         │                  │         │ - write draft│
└──────────────┘         └──────────────────┘         └──────────────┘

No Redis. No message queue. No API. Just a folder on disk.

Setup

pip install velesdb sentence-transformers

That installs the database engine (a ~6MB native binary inside the Python wheel) and the embedding model. No Docker, no API keys.

The researcher agent

This agent searches for information and stores what it finds in semantic memory (facts) and episodic memory (events).

# researcher_agent.py
import velesdb
import time
from sentence_transformers import SentenceTransformer

model = SentenceTransformer("all-MiniLM-L6-v2")

def embed(text):
    return model.encode(text).tolist()

# Open the shared database
db = velesdb.Database("./shared_agent_brain")
memory = db.agent_memory(384)

# ---- Store researched facts in semantic memory ----
facts = [
    (1, "Multi-agent systems saw a 1445% surge in Gartner inquiries in 2025"),
    (2, "CrewAI and AutoGen are the two most popular multi-agent frameworks"),
    (3, "Shared state is the hardest problem in multi-agent architectures"),
    (4, "Most multi-agent systems use Redis or message queues for coordination"),
    (5, "Local-first databases eliminate infrastructure dependencies for agent memory"),
]

for fact_id, text in facts:
    memory.semantic.store(fact_id, text, embed(text))
    print(f"  [semantic] Stored: {text}")

# ---- Record research events in episodic memory ----
now = int(time.time())
events = [
    (1, "Searched web for multi-agent architecture trends 2025-2026", now - 3600),
    (2, "Found Gartner report on agentic AI surge", now - 1800),
    (3, "Compared CrewAI vs AutoGen vs LangGraph for memory handling", now - 900),
    (4, "Identified shared state as the key unsolved problem", now),
]

for event_id, description, timestamp in events:
    memory.episodic.record(event_id, description, timestamp, embed(description))
    print(f"  [episodic] Recorded: {description}")

print("\nResearcher done. Closing database.")

The researcher stores five facts and four timestamped events. All of them are embedded as 384-dimensional vectors using all-MiniLM-L6-v2, so the writer can search them semantically later.

The writer agent

A separate Python script. Different process. Same database path.

# writer_agent.py
import velesdb
from sentence_transformers import SentenceTransformer

model = SentenceTransformer("all-MiniLM-L6-v2")

def embed(text):
    return model.encode(text).tolist()

# Open the SAME database the researcher wrote to
db = velesdb.Database("./shared_agent_brain")
memory = db.agent_memory(384)

# ---- Query semantic memory: what facts did the researcher find? ----
print("Facts about multi-agent trends:")
results = memory.semantic.query(embed("What are the trends in multi-agent AI?"), top_k=3)
for r in results:
    print(f"  [{r['score']:.4f}] {r['content']}")

print("\nFacts about state sharing:")
results = memory.semantic.query(embed("How do agents share state?"), top_k=3)
for r in results:
    print(f"  [{r['score']:.4f}] {r['content']}")

# ---- Check episodic memory: what was already researched? ----
print("\nResearch timeline (most recent first):")
recent = memory.episodic.recent(limit=4)
for event in recent:
    print(f"  {event['description']}")

# ---- Find specific episodes by topic ----
print("\nEpisodes about framework comparison:")
similar = memory.episodic.recall_similar(embed("framework comparison analysis"), top_k=2)
for s in similar:
    print(f"  [{s['score']:.4f}] {s['description']}")

Real results

Run the researcher first, then the writer:

python researcher_agent.py
python writer_agent.py

Here is the actual output from the writer agent:

Facts about multi-agent trends:
  [0.6159] CrewAI and AutoGen are the two most popular multi-agent frameworks
  [0.5812] Shared state is the hardest problem in multi-agent architectures
  [0.5255] Most multi-agent systems use Redis or message queues for coordination

Facts about state sharing:
  [0.6717] Shared state is the hardest problem in multi-agent architectures
  [0.5047] Most multi-agent systems use Redis or message queues for coordination
  [0.4449] Local-first databases eliminate infrastructure dependencies for agent memory

Research timeline (most recent first):
  Identified shared state as the key unsolved problem
  Compared CrewAI vs AutoGen vs LangGraph for memory handling
  Found Gartner report on agentic AI surge
  Searched web for multi-agent architecture trends 2025-2026

Episodes about framework comparison:
  [0.2404] Compared CrewAI vs AutoGen vs LangGraph for memory handling
  [0.1861] Searched web for multi-agent architecture trends 2025-2026

The writer found exactly the facts the researcher stored, ranked by semantic relevance. The query "How do agents share state?" returned "Shared state is the hardest problem" at 0.67 even though the query words do not match the stored text literally. That is semantic search working as expected.

The episodic timeline gives the writer a chronological view of what research was already done, so it does not duplicate effort.

How it works under the hood

VelesDB stores everything in a local folder. The agent_memory(384) call creates three internal collections (semantic, episodic, procedural) backed by HNSW indexes for fast vector search.

When the researcher writes and closes the database, the data is persisted to disk. When the writer opens the same path, it reads that persisted state. No network calls, no serialization protocol, no connection string.

The key insight: the database file is the message bus.

Limitations

This approach has real constraints you should know about:

Single-process access. VelesDB locks the database file for writes. Two agents cannot write simultaneously to the same database. This means sequential workflows only: researcher runs, finishes, then writer runs.

No real-time streaming. If you need Agent B to react the instant Agent A stores something, you need a message queue or pub/sub system. VelesDB is not that.

Workarounds that do work:

Sequential pipelines. Most multi-agent workflows are already sequential (research, then write, then review). This fits naturally.
Read-only mode. One agent writes, multiple agents read. VelesDB allows concurrent reads after the writer closes.
Periodic snapshots. Copy the database file for each reader agent. They get a consistent snapshot without locking conflicts.

For a two-agent pipeline where one produces and the other consumes, this is a practical fit. For a swarm of 50 agents writing simultaneously, you need a different architecture.

When to use this vs. Redis/Postgres

Scenario	Use VelesDB shared file	Use Redis/Postgres
2-5 agents, sequential pipeline	Yes	Overkill
Agents on the same machine	Yes	Unnecessary
Need semantic search over shared facts	Yes (built-in)	Requires extra setup
50+ concurrent writing agents	No	Yes
Real-time pub/sub between agents	No	Yes
Zero infrastructure requirement	Yes	No

Getting started

pip install velesdb sentence-transformers

VelesDB is source-available under the Elastic License 2.0. The full code and documentation are on GitHub:

VelesDB on GitHub
Agent Memory SDK docs
Article 2: Give your AI agent a real memory (single-agent deep dive)

What is your multi-agent architecture? Are you running sequential pipelines or full concurrent swarms? I am curious what state-sharing problems you have hit in practice.

One query is never enough: why top RAG systems search three times

Julien L — Mon, 30 Mar 2026 13:31:19 +0000

LangChain has MultiQueryRetriever. LlamaIndex has SubQuestionQueryEngine. Every serious RAG framework decomposes user questions into multiple search queries before hitting the vector database.

Why? Because a single embedding compresses your entire question into one point in vector space. And one point can only land in one neighborhood.

Take this question: "How do I fix a slow database connection in my Flask app?"

Three concepts, three clusters in embedding space:

Database connections - pooling, timeouts, driver configuration
Flask-specific patterns - SQLAlchemy setup, app factory patterns, teardown handling
Performance diagnostics - profiling, query logging, bottleneck identification

Embed the full question, and the resulting vector lands in the "Flask + database" neighborhood. The performance diagnostics cluster is invisible. You get back five results about Flask and database setup, zero about profiling or bottleneck identification.

This is not about relationships between entities (that is a graph problem). This is about semantic coverage: one embedding captures one perspective, but most real questions have two or three.

The fix is simple: search three times, fuse the results. And you can do it in one API call.

Proof: one query vs. three queries

Let's prove it. We will build a 12-document technical corpus and compare single-query retrieval against multi-query decomposition.

pip install velesdb sentence-transformers

import velesdb
from sentence_transformers import SentenceTransformer

db = velesdb.Database("./multi_query_demo")
model = SentenceTransformer("all-MiniLM-L6-v2")

collection = db.get_or_create_collection("tech_docs", dimension=384)

Here is our documentation corpus - 12 articles across different domains:

docs = [
    {"id": 1, "title": "Database connection pooling with SQLAlchemy",
     "content": "Connection pooling reuses existing database connections instead of creating new ones. Configure pool_size and max_overflow in SQLAlchemy create_engine to control the pool.",
     "domain": "database"},

    {"id": 2, "title": "Flask app factory pattern for database setup",
     "content": "Use the Flask app factory pattern to initialize SQLAlchemy. Call db.init_app(app) inside create_app() to avoid circular imports and enable testing with different configs.",
     "domain": "flask"},

    {"id": 3, "title": "Profiling slow SQL queries with EXPLAIN ANALYZE",
     "content": "Run EXPLAIN ANALYZE before your query to see the execution plan. Look for sequential scans on large tables, missing indexes, and high row estimates.",
     "domain": "performance"},

    {"id": 4, "title": "Configuring connection timeouts in PostgreSQL",
     "content": "Set statement_timeout to kill long queries. Set idle_in_transaction_session_timeout to reclaim idle connections. Both prevent resource exhaustion under load.",
     "domain": "database"},

    {"id": 5, "title": "Flask-SQLAlchemy session management pitfalls",
     "content": "Always call db.session.remove() at the end of requests. Use scoped_session to avoid sharing sessions across threads. Forgetting teardown causes connection leaks.",
     "domain": "flask"},

    {"id": 6, "title": "Identifying bottlenecks with Python cProfile",
     "content": "Wrap your endpoint with cProfile to find where time is spent. Sort by cumulative time. Database calls often dominate - look for many small queries (N+1 problem).",
     "domain": "performance"},

    {"id": 7, "title": "Async database drivers: asyncpg vs psycopg3",
     "content": "asyncpg delivers 2-5x throughput over synchronous psycopg2 for concurrent workloads. psycopg3 supports both sync and async modes for gradual migration.",
     "domain": "database"},

    {"id": 8, "title": "Flask request lifecycle and database teardown",
     "content": "Flask fires teardown_appcontext after each request. Register a handler to close database sessions. Without it, connections pile up until the pool is exhausted.",
     "domain": "flask"},

    {"id": 9, "title": "Load testing database connections with Locust",
     "content": "Use Locust to simulate concurrent users hitting your API. Monitor connection pool saturation and response times. A sudden latency spike usually means pool exhaustion.",
     "domain": "performance"},

    {"id": 10, "title": "JWT authentication middleware for Flask",
     "content": "Implement JWT validation as a Flask before_request hook. Decode the token, verify the signature, and attach the user to flask.g for downstream handlers.",
     "domain": "security"},

    {"id": 11, "title": "Deploying Flask apps with Gunicorn and Nginx",
     "content": "Run Gunicorn with multiple workers behind Nginx. Each worker gets its own connection pool. Set worker count to (2 * CPU cores) + 1 for CPU-bound apps.",
     "domain": "deployment"},

    {"id": 12, "title": "Database migration strategies with Alembic",
     "content": "Use Alembic for schema migrations. Always test migrations on a staging database first. Use --sql mode to review generated SQL before applying to production.",
     "domain": "database"},
]

points = []
for doc in docs:
    embedding = model.encode(doc["content"]).tolist()
    points.append({
        "id": doc["id"],
        "vector": embedding,
        "payload": {
            "title": doc["title"],
            "content": doc["content"],
            "domain": doc["domain"],
        }
    })
collection.upsert(points)

Now, the experiment. Same user question, three different search angles:

user_question = "How do I fix a slow database connection in my Flask app?"

# Single query - the naive approach
single_vec = model.encode(user_question).tolist()
single_results = collection.search(vector=single_vec, top_k=5)

print("--- Single query results ---")
for r in single_results:
    p = r["payload"]
    print(f"  [{r['score']:.3f}] {p['title']} ({p['domain']})")

Run this yourself. You will see 3 Flask articles and 2 database articles. Performance diagnostics like "Profiling slow SQL queries" and "Identifying bottlenecks with cProfile" are completely absent from the top 5.

Now, let's decompose the question into three search intents:

# Three angles on the same question
q1 = model.encode("database connection pool configuration timeout").tolist()
q2 = model.encode("Flask SQLAlchemy session management setup").tolist()
q3 = model.encode("profiling slow queries performance bottleneck").tolist()

print("\n--- Query 1: database connections ---")
for r in collection.search(vector=q1, top_k=3):
    print(f"  [{r['score']:.3f}] {r['payload']['title']}")

print("\n--- Query 2: Flask patterns ---")
for r in collection.search(vector=q2, top_k=3):
    print(f"  [{r['score']:.3f}] {r['payload']['title']}")

print("\n--- Query 3: performance diagnostics ---")
for r in collection.search(vector=q3, top_k=3):
    print(f"  [{r['score']:.3f}] {r['payload']['title']}")

Here is what actually happens:

--- Query 1: database connections ---
  [0.659] Database connection pooling with SQLAlchemy
  [0.587] Flask request lifecycle and database teardown
  [0.575] Configuring connection timeouts in PostgreSQL

--- Query 2: Flask patterns ---
  [0.601] Flask app factory pattern for database setup
  [0.511] Database connection pooling with SQLAlchemy
  [0.499] Flask request lifecycle and database teardown

--- Query 3: performance diagnostics ---
  [0.655] Profiling slow SQL queries with EXPLAIN ANALYZE
  [0.590] Identifying bottlenecks with Python cProfile
  [0.459] Configuring connection timeouts in PostgreSQL

Query 3 surfaces "Profiling slow SQL queries" and "Identifying bottlenecks with cProfile" at the top - two articles that the single query missed entirely. Across all three queries, we find 6 unique documents instead of 5, covering domains the single query could not reach.

The problem: you now have 9 results with duplicates, no unified ranking, and custom code to merge them. Or you use fusion.

Multi-query fusion: one API call, merged results

VelesDB has multi-query fusion built in. You pass multiple vectors, pick a fusion strategy, and get a single ranked result set:

results = collection.multi_query_search(
    vectors=[q1, q2, q3],
    top_k=5,
    fusion=velesdb.FusionStrategy.rrf()
)

print("\n--- Fused results (RRF) ---")
for r in results:
    p = r.get("payload", r.get("bindings", {}))
    print(f"  {p['title']} ({p['domain']})")

Reciprocal Rank Fusion (RRF) works by converting positions into scores: a document ranked #1 in any query gets a high score, one ranked #5 gets less. Documents that appear in multiple queries get boosted. The math is simple: score = sum(1 / (k + rank)) for each query where the document appears.

Here is the actual output:

--- Fused results (RRF) ---
  Flask request lifecycle and database teardown (flask)
  Database connection pooling with SQLAlchemy (database)
  Configuring connection timeouts in PostgreSQL (database)
  Flask-SQLAlchemy session management pitfalls (flask)
  Load testing database connections with Locust (performance)

Three domains represented: flask, database, and performance. "Load testing database connections with Locust" was buried in the single query results but the fusion pulled it up because it ranked well across multiple angles. One API call, no glue code.

Fusion strategies: pick the right one

RRF is the safe default, but VelesDB supports five strategies. Four of them work with any number of query vectors:

# These 4 strategies accept N vectors
strategies = {
    "rrf": velesdb.FusionStrategy.rrf(),
    "average": velesdb.FusionStrategy.average(),
    "maximum": velesdb.FusionStrategy.maximum(),
    "weighted": velesdb.FusionStrategy.weighted(0.6, 0.3, 0.1),
}

for name, strategy in strategies.items():
    results = collection.multi_query_search(
        vectors=[q1, q2, q3],
        top_k=3,
        fusion=strategy,
    )
    titles = [r.get("payload", r.get("bindings", {}))["title"][:50] for r in results]
    print(f"  {name:16s} => {titles}")

Each strategy produces a different ranking:

rrf              => ["Flask request lifecycle and database teardown",
                     "Database connection pooling with SQLAlchemy",
                     "Configuring connection timeouts in PostgreSQL"]

average          => ["Database connection pooling with SQLAlchemy",
                     "Flask request lifecycle and database teardown",
                     "Configuring connection timeouts in PostgreSQL"]

maximum          => ["Flask app factory pattern for database setup",
                     "Database connection pooling with SQLAlchemy",
                     "Flask request lifecycle and database teardown"]

weighted         => ["Database connection pooling with SQLAlchemy",
                     "Flask request lifecycle and database teardown",
                     "Flask app factory pattern for database setup"]

The fifth strategy, relative_score, is designed for exactly 2 branches (e.g., dense + sparse retrieval). Use it when you have two complementary search signals:

# relative_score: exactly 2 vectors (dense + sparse style)
results = collection.multi_query_search(
    vectors=[q1, q2],
    top_k=3,
    fusion=velesdb.FusionStrategy.relative_score(0.7, 0.3),
)

When to use each:

RRF - Your default. Position-based, ignores raw scores. Works well when queries have different scales. Best for: most RAG pipelines.

Average - Averages the similarity scores across queries. Favors documents that are moderately relevant to everything. Best for: broad recall when all intents matter equally.

Maximum - Takes the highest score from any query. Favors documents that are extremely relevant to at least one intent. Best for: when you want specialist documents, not generalists. Notice how it pulled "Flask app factory pattern" to #1 because it scored highest on query 2.

Relative score - Normalizes scores per branch, then blends with custom weights. Designed for exactly 2 branches (dense + sparse). Best for: hybrid vector + BM25 fusion where you control the balance.

Weighted - Assigns explicit weights to each query vector. Works with N vectors. Best for: when you know the user cares more about one angle (e.g., 60% database, 30% Flask, 10% performance).

Quality modes: squeeze more precision from each query

Before fusion even happens, you can control how thoroughly each individual search explores the HNSW index:

query_vec = model.encode(user_question).tolist()

for mode in ["fast", "balanced", "accurate"]:
    results = collection.search_with_quality(query_vec, mode, top_k=5)
    titles = [r["payload"]["title"][:50] for r in results]
    print(f"  {mode:10s} => {titles}")

fast - Explores fewer candidates. Sub-millisecond. Use for autocomplete, typeahead.
balanced - Good default. Explores more paths in the HNSW graph.
accurate - Maximum recall. Explores extensively. Use for final answers.
perfect - Brute force. Guarantees the mathematically correct top-k. Slow on large collections.
autotune - Lets the engine pick based on collection size and query complexity.

On our 12-document corpus, all three modes return the same results - the HNSW index is small enough that even fast explores everything. The difference shows up on larger collections (10K+ documents) where fast may skip graph neighborhoods that accurate would visit. This is where quality modes matter: when your collection grows, you trade latency for recall.

The combination is powerful: decompose a question into sub-queries, search each with accurate quality, fuse with RRF. You get coverage and precision that single-query retrieval cannot match.

Putting it all together: a production-ready retrieval function

import velesdb
from sentence_transformers import SentenceTransformer

def multi_angle_search(
    collection,
    model: SentenceTransformer,
    question: str,
    angles: list[str],
    top_k: int = 5,
    fusion: str = "rrf",
) -> list[dict]:
    """Search from multiple angles and fuse results.

    Args:
        collection: VelesDB collection
        model: SentenceTransformer encoder
        question: Original user question
        angles: List of reformulated search queries
        top_k: Number of results to return
        fusion: Fusion strategy name

    Returns:
        Fused, deduplicated, ranked results
    """
    strategies = {
        "rrf": velesdb.FusionStrategy.rrf(),
        "average": velesdb.FusionStrategy.average(),
        "maximum": velesdb.FusionStrategy.maximum(),
    }

    vectors = [model.encode(angle).tolist() for angle in angles]

    return collection.multi_query_search(
        vectors=vectors,
        top_k=top_k,
        fusion=strategies.get(fusion, strategies["rrf"]),
    )

Usage:

results = multi_angle_search(
    collection,
    model,
    question="How do I fix a slow database connection in my Flask app?",
    angles=[
        "database connection pool configuration timeout",
        "Flask SQLAlchemy session management setup",
        "profiling slow queries performance bottleneck",
    ],
    top_k=5,
)

for r in results:
    p = r.get("payload", r.get("bindings", {}))
    print(f"  {p['title']}")

In a production RAG pipeline, the "angles" list comes from an LLM. Ask GPT or Claude to decompose the user question into 2-4 search queries, embed each one, and fuse. This is exactly what LangChain's MultiQueryRetriever and LlamaIndex's SubQuestionQueryEngine do - except here the fusion happens inside the database engine, not in Python glue code.

When to use multi-query vs. single query

Not every question needs three searches:

Single query works fine when:

The question is specific and unambiguous ("What is the default pool_size in SQLAlchemy?")
Your corpus is small and homogeneous
Latency matters more than recall (autocomplete, typeahead)

Multi-query wins when:

The question spans multiple domains or concepts
Users ask vague questions that map to several topics
Completeness matters (legal, medical, compliance use cases)
You are building agentic RAG where the LLM generates sub-queries anyway

Full working example

The complete, tested script is available on GitHub:
examples/tutorials/multi_query_fusion_demo.py

VelesDB is a source-available (Elastic License 2.0) local-first database combining vector, graph, and columnar storage in a single ~6MB Rust binary. No Docker. No API keys.

Stop Using Cosine for Everything: 5 Distance Metrics That Unlock Hidden Powers in Your Vector Database

Julien L — Sun, 29 Mar 2026 15:11:29 +0000

Everyone uses cosine similarity. Tutorials use it. Frameworks default to it. If you ask "which distance metric should I use?", the answer is always "cosine, probably."

But here is the thing: your vector database supports other metrics. And those metrics unlock use cases that cosine literally cannot handle.

This is not a math lecture. This is a practical guide. Five metrics, five real-world problems, working code you can run in two minutes. By the end, you will look at your vector database differently.

A quick mental model (no math degree required)

Before we dive in, let's build some intuition. Imagine you have two arrows on a piece of paper:

Cosine asks: "Do these arrows point in the same direction?" It does not care how long they are.

Euclidean asks: "How far apart are the tips of these arrows?" It cares about both direction and length.

Dot Product asks: "Do they point the same way, AND are they both strong signals?" Direction plus intensity.

Hamming asks: "How many switches are flipped differently between these two?" It works on binary on/off data.

Jaccard asks: "How much overlap is there between these two sets?" It works on yes/no memberships.

That is it. Five different questions, five different superpowers. Let's see them in action.

Setup

pip install velesdb

One line. No Docker. No API keys. VelesDB® is an embedded database written in Rust (~6MB binary). It runs in your process.

import velesdb

db = velesdb.Database("./my_data")

1. Cosine: the one you already know (but maybe not why)

The question it answers: "Are these two things about the same topic?"

Cosine measures the angle between two vectors. If two documents are about machine learning, their embedding vectors will point in roughly the same direction, regardless of document length. A 280-character tweet and a 10-page paper about the same topic will score high.

collection = db.create_collection("articles", dimension=4, metric="cosine")

# Simulated embeddings: [tech, science, cooking, sports]
collection.upsert([
    {"id": 1, "vector": [0.9, 0.8, 0.0, 0.0], "payload": {"title": "Introduction to Machine Learning"}},
    {"id": 2, "vector": [0.8, 0.9, 0.0, 0.0], "payload": {"title": "Neural Networks Explained"}},
    {"id": 3, "vector": [0.0, 0.1, 0.9, 0.8], "payload": {"title": "Best Pasta Recipes"}},
    {"id": 4, "vector": [0.1, 0.0, 0.0, 0.9], "payload": {"title": "World Cup 2026 Preview"}},
    {"id": 5, "vector": [0.7, 0.6, 0.0, 0.1], "payload": {"title": "Deep Learning for Beginners"}},
])

results = collection.search(vector=[0.85, 0.75, 0.0, 0.0], top_k=3)

score=1.000  Introduction to Machine Learning
score=0.994  Deep Learning for Beginners
score=0.993  Neural Networks Explained

All three AI articles cluster together. Pasta and football? Nowhere close. This is cosine's sweet spot: semantic similarity where you care about topic, not intensity.

When to use cosine: semantic search, document similarity, FAQ matching, any text embedding comparison.

2. Euclidean: the anomaly hunter

The question it answers: "How far is this point from what's normal?"

Here is where it gets interesting. Imagine IoT sensors on a factory floor, each sending readings every minute: temperature, pressure, humidity, vibration. Normal readings cluster in a tight neighborhood. An anomaly is a point that is physically far from the cluster.

Cosine would miss this. Why? Because a reading of [78C, 985hPa, 12%, 4.8g] could point in a similar direction to [22C, 1013hPa, 45%, 0.3g]. Same general "shape" of data, vastly different magnitudes. Cosine says "similar." Euclidean says "these are 70 units apart, something is on fire."

collection = db.create_collection("sensors", dimension=4, metric="euclidean")

# Sensor: [temperature_C, pressure_hPa, humidity_%, vibration_g]
collection.upsert([
    {"id": 1, "vector": [22.0, 1013.0, 45.0, 0.3], "payload": {"status": "normal", "time": "08:00"}},
    {"id": 2, "vector": [22.5, 1012.5, 47.0, 0.3], "payload": {"status": "normal", "time": "09:00"}},
    {"id": 3, "vector": [21.8, 1013.5, 44.0, 0.4], "payload": {"status": "normal", "time": "10:00"}},
    {"id": 4, "vector": [23.0, 1012.0, 46.0, 0.3], "payload": {"status": "normal", "time": "11:00"}},
    {"id": 5, "vector": [78.0, 985.0, 12.0, 4.8],  "payload": {"status": "ANOMALY", "time": "11:15"}},
])

results = collection.search(vector=[22.0, 1013.0, 45.0, 0.3], top_k=5)

distance=  0.00  08:00 - normal
distance=  1.14  10:00 - normal
distance=  1.73  11:00 - normal
distance=  2.12  09:00 - normal
distance= 70.92  11:15 - ANOMALY  *** ALERT ***

Normal readings are all within distance 0-2 of each other. The anomaly is at distance 70. That is not a subtle difference. That is a fire alarm.

When to use euclidean: anomaly detection, IoT monitoring, fraud detection, anything where the absolute values matter, not just the direction.

3. Dot Product: the smart recommender

The question it answers: "Is this relevant to me, and how confident are you?"

Dot product is cosine's bigger sibling. Cosine only looks at direction. Dot product looks at direction AND magnitude. Think of it this way: two movies can both be sci-fi (same direction), but a critically acclaimed blockbuster has a "louder" embedding signal than a forgettable B-movie.

With cosine, they would score equally. With dot product, quality rises to the top.

collection = db.create_collection("movies", dimension=4, metric="dotproduct")

# Dimensions: [sci_fi, action, drama, comedy]
# Higher magnitude = stronger signal / higher quality
collection.upsert([
    {"id": 1, "vector": [0.95, 0.80, 0.30, 0.05], "payload": {"title": "Interstellar", "rating": 8.7}},
    {"id": 2, "vector": [0.40, 0.35, 0.10, 0.02], "payload": {"title": "Low-Budget Sci-Fi B-Movie", "rating": 3.2}},
    {"id": 3, "vector": [0.85, 0.90, 0.20, 0.10], "payload": {"title": "The Matrix", "rating": 8.7}},
    {"id": 4, "vector": [0.05, 0.05, 0.10, 0.95], "payload": {"title": "Comedy Special", "rating": 7.0}},
    {"id": 5, "vector": [0.70, 0.60, 0.50, 0.05], "payload": {"title": "Blade Runner 2049", "rating": 8.0}},
])

results = collection.search(vector=[0.9, 0.8, 0.1, 0.0], top_k=5)

score=1.525  Interstellar (rating: 8.7)
score=1.505  The Matrix (rating: 8.7)
score=1.160  Blade Runner 2049 (rating: 8.0)
score=0.650  Low-Budget Sci-Fi B-Movie (rating: 3.2)
score=0.095  Comedy Special (rating: 7.0)

Notice: the B-movie is sci-fi (same direction as Interstellar), but it ranks way below because its embedding magnitude is weaker. Dot product naturally surfaces quality. This is why recommendation systems at scale often prefer it over cosine.

When to use dot product: recommendation engines, search ranking where content quality matters, any case where you want relevance weighted by confidence.

4. Hamming: the duplicate detective

The question it answers: "How many bits are different between these two?"

This one is completely different from the previous three. Hamming works on binary vectors (0s and 1s) and simply counts how many positions differ. It is lightning fast and perfect for one thing: comparing hashes.

Real-world scenario: you run a content platform. Users upload images. You want to detect reposts, even if someone cropped the image, added a filter, or recompressed it. The approach: compute a perceptual hash (pHash) of each image, which produces a binary fingerprint. Near-duplicate images have fingerprints that differ by just a few bits.

collection = db.create_collection("image_hashes", dimension=16, metric="hamming")

# Simulated 16-bit perceptual hashes
collection.upsert([
    {"id": 1, "vector": [1,0,1,1,0,0,1,0,1,1,0,1,0,0,1,1],
     "payload": {"file": "sunset_original.jpg", "source": "photographer"}},
    {"id": 2, "vector": [1,0,1,1,0,0,1,0,1,1,0,1,0,0,1,0],
     "payload": {"file": "sunset_cropped.jpg", "source": "instagram repost"}},
    {"id": 3, "vector": [1,0,1,1,0,0,1,0,1,1,0,1,0,1,1,1],
     "payload": {"file": "sunset_filtered.jpg", "source": "pinterest"}},
    {"id": 4, "vector": [0,1,0,0,1,1,0,1,0,0,1,0,1,1,0,0],
     "payload": {"file": "cat_photo.jpg", "source": "original"}},
    {"id": 5, "vector": [1,0,1,1,0,0,1,0,1,1,0,1,0,0,0,1],
     "payload": {"file": "sunset_watermarked.jpg", "source": "stock site"}},
])

new_upload = [1,0,1,1,0,0,1,0,1,1,0,1,0,0,1,1]  # same as original
results = collection.search(vector=new_upload, top_k=5)

hamming= 0 bits  [DUPLICATE      ]  sunset_original.jpg (photographer)
hamming= 1 bits  [NEAR-DUPLICATE ]  sunset_cropped.jpg (instagram repost)
hamming= 1 bits  [NEAR-DUPLICATE ]  sunset_filtered.jpg (pinterest)
hamming= 1 bits  [NEAR-DUPLICATE ]  sunset_watermarked.jpg (stock site)
hamming=16 bits  [different image]  cat_photo.jpg (original)

Zero to two bits difference? That is the same image with minor modifications. A content moderation bot can flag these in real-time. No ML model needed. No GPU. Just binary comparison at database speed.

When to use hamming: image deduplication, audio fingerprinting, DNA sequence comparison, binary feature matching, plagiarism detection with locality-sensitive hashing.

5. Jaccard: the taste matcher

The question it answers: "How much overlap is there between these two sets?"

Jaccard is beautifully simple: take two sets, divide the size of their intersection by the size of their union. If you and I both like 3 of the same genres out of 4 total unique genres between us, that is 75% Jaccard similarity.

No embeddings. No ML model. No neural network. Just set math.

collection = db.create_collection("user_profiles", dimension=10, metric="jaccard")

# Genres: [action, comedy, sci-fi, horror, drama, romance, thriller, documentary, anime, musical]
collection.upsert([
    {"id": 1, "vector": [1,0,1,0,1,0,1,0,0,0],
     "payload": {"user": "Alice", "likes": "action, sci-fi, drama, thriller"}},
    {"id": 2, "vector": [0,1,0,0,0,1,0,0,0,1],
     "payload": {"user": "Bob", "likes": "comedy, romance, musical"}},
    {"id": 3, "vector": [1,0,1,1,0,0,1,0,1,0],
     "payload": {"user": "Charlie", "likes": "action, sci-fi, horror, thriller, anime"}},
    {"id": 4, "vector": [1,1,1,1,1,1,1,1,1,1],
     "payload": {"user": "Dave", "likes": "literally everything"}},
    {"id": 5, "vector": [1,0,1,0,0,0,0,1,0,0],
     "payload": {"user": "Eve", "likes": "action, sci-fi, documentary"}},
])

results = collection.search(vector=[1,0,1,0,1,0,0,0,0,0], top_k=5)

75.0% match  Alice (action, sci-fi, drama, thriller)
50.0% match  Eve (action, sci-fi, documentary)
33.3% match  Charlie (action, sci-fi, horror, thriller, anime)
30.0% match  Dave (literally everything)
 0.0% match  Bob (comedy, romance, musical)

Alice shares 3 out of 4 unique genres with you. Dave likes everything, but his union is 10 genres while the overlap is only 3, so Jaccard penalizes him. Bob has zero overlap. The math is transparent, explainable, and instant.

When to use jaccard: user matching, product tagging, skill matching in recruiting, collaborative filtering, any comparison of categorical membership.

The cheat sheet

Metric	Best for	Score meaning	Think of it as
Cosine	Semantic search	1.0 = same topic	"Same direction?"
Euclidean	Anomaly detection	Lower = closer	"How far apart?"
Dot Product	Recommendations	Higher = better match	"Same direction + strong signal?"
Hamming	Hash comparison	Lower = more similar	"How many bits differ?"
Jaccard	Set overlap	1.0 = identical sets	"How much in common?"

The full picture

Choosing the right distance metric is like choosing the right tool. You can hammer a screw into wood, but a screwdriver works better.

Most developers never think about this because most tutorials only show cosine. But the moment you realize that euclidean catches anomalies that cosine misses, or that Jaccard gives you a recommendation engine without any ML, your vector database becomes something much more versatile than a "semantic search box."

All the code in this article runs as-is. You can grab the complete script from GitHub and try it yourself.

pip install velesdb
python distance_metrics_demo.py

VelesDB is a source-available embedded database (Elastic License 2.0) written in Rust. ~6MB binary, no Docker, no server process, no API keys. Just pip install and go.

Full docs: velesdb.com/en
GitHub: github.com/cyberlife-coder/VelesDB
Python SDK: pypi.org/project/velesdb

What distance metric surprised you the most? Have you used Hamming or Jaccard in a real project? I'd love to hear about it in the comments.

Your RAG pipeline is missing two-thirds of the picture

Julien L — Sun, 29 Mar 2026 07:38:10 +0000

Most RAG pipelines do one thing well: find text chunks that are semantically similar to a query. But a real customer question like "My API calls are failing and I need to upgrade my plan" isn't answered by similarity alone. You need:

Semantic similarity to understand the intent (vector search)
Keyword precision to catch exact terms like "API" and "upgrade" (text search)
Metadata filtering to surface only relevant, high-quality articles (SQL conditions)
Relationship awareness to follow the thread from "API rate limits" to "plan upgrade" to "billing FAQ" (graph traversal)

Gluing Pinecone + Elasticsearch + Neo4j together to get this is an infrastructure nightmare. VelesQL does it in one query string, inside a single embedded engine.

In this tutorial, we'll build a customer support AI agent that uses all four query types against VelesDB® v1.9.3.

What is VelesQL?

VelesQL is a SQL-like language with three domain-specific extensions:

NEAR - vector similarity search (HNSW)
MATCH 'term' - full-text search (BM25)
MATCH (a)-[:REL]->(b) - Cypher-like graph pattern matching

Combine them with standard SQL predicates (AND, OR, <, =, >) and you can express hybrid retrieval logic in one statement. If you know SQL and a bit of Cypher, you already know 90% of VelesQL.

-- Hybrid vector + text + metadata
SELECT * FROM support_kb
WHERE vector NEAR $v
  AND content MATCH 'authentication'
  AND resolved_pct > 80
LIMIT 5

-- Graph + vector in one query
MATCH (doc:Document)-[:AUTHORED_BY]->(author:Person)
WHERE similarity(doc.embedding, $question) > 0.8
  AND author.department = 'Engineering'
RETURN author.name, doc.title
ORDER BY similarity() DESC LIMIT 5

The first query combines vector search, keyword matching, and SQL filters. The second one walks the knowledge graph with node labels, filters by metadata, and ranks nodes by semantic similarity. Both are VelesQL, both run in one engine.

Setup

pip install velesdb

That installs a ~6MB native Rust engine. No Docker, no server, no config files.

import velesdb
from sentence_transformers import SentenceTransformer

model = SentenceTransformer("all-MiniLM-L6-v2")
db = velesdb.Database("./support_data")

# Create a graph collection: vector + graph + columnar in one object
graph = db._inner.create_graph_collection(
    "support_kb", dimension=384, metric="cosine"
)

# Get the collection handle for upsert and VelesQL SELECT queries
collection = db._inner.get_collection("support_kb")

New in v1.9.3: create_graph_collection gives you a unified object that supports vector search, graph traversal, and Cypher-like MATCH queries. The underlying collection handle is used for upserting points and running SELECT queries.

Step 1: Build the knowledge base

We'll populate a support knowledge base for a SaaS product. Each article gets a vector embedding from its title and content, plus structured metadata and a _labels field for graph node typing:

articles = [
    {
        "id": 1,
        "title": "How to reset your password",
        "content": "To reset your password, navigate to Settings, "
                   "then Security, then Reset Password...",
        "category": "account",
        "product": "auth-service",
        "difficulty": "beginner",
        "resolved_pct": 95.0,
        "views": 12500,
        "_labels": ["Article"],
    },
    {
        "id": 2,
        "title": "Setting up two-factor authentication",
        "content": "Enable 2FA from Settings, Security, 2FA. "
                   "We support Google Authenticator and YubiKey...",
        "category": "account",
        "product": "auth-service",
        "difficulty": "intermediate",
        "resolved_pct": 88.0,
        "views": 8900,
        "_labels": ["Article"],
    },
    # ... 8 more articles covering billing, technical, compliance
]

points = []
for article in articles:
    text = f"{article['title']} {article['content']}"
    embedding = model.encode(text).tolist()
    payload = {k: v for k, v in article.items() if k != "id"}
    points.append({
        "id": article["id"],
        "vector": embedding,
        "payload": payload
    })

collection.upsert(points)

Ten articles across four categories: account, billing, technical, compliance. Each has a difficulty level, a resolution rate, and a view count. The _labels field is what lets MATCH queries filter by node type (like :Article or :Person in Cypher). In production you'd have thousands - the queries scale the same way.

Step 2: Semantic search with NEAR

A customer writes: "I forgot my password and I'm locked out." Let's find relevant articles:

question = "I forgot my password and I am locked out of my account"
query_vec = model.encode(question).tolist()

results = collection.query(
    "SELECT * FROM support_kb WHERE vector NEAR $v LIMIT 5",
    params={"v": query_vec}
)

for r in results:
    print(f"  {r['fused_score']:.3f} | {r['payload']['title']}")

  0.645 | How to reset your password
  0.203 | Setting up two-factor authentication
  0.160 | Resolving payment failures
  0.083 | SSO integration with SAML and OIDC
  0.080 | Upgrading your subscription plan

The NEAR operator runs HNSW similarity search against the article embeddings. Results are ranked by cosine similarity. This is the same search you'd get from any vector database, but expressed as a query string you can log, compose, and debug.

Step 3: Add metadata filters

The customer is a free-tier user. We only want beginner-level articles with a high resolution rate:

results = collection.query(
    """SELECT * FROM support_kb
       WHERE vector NEAR $v
       AND difficulty = 'beginner'
       AND resolved_pct > 90
       LIMIT 5""",
    params={"v": query_vec}
)

  0.645 | How to reset your password      | beginner | 95.0%
  0.013 | Understanding your invoice       | beginner | 92.0%

The SQL conditions work on the structured metadata alongside the vector similarity. The advanced SSO and 2FA articles are gone because they're not "beginner" difficulty. This is the part most vector databases make painful - you either filter client-side (wasting bandwidth) or learn a custom filter DSL. VelesQL keeps it SQL.

Step 4: Keyword precision with MATCH

Now a developer writes: "How do I configure authentication for my API?" This needs both semantic understanding and keyword precision. The word "authentication" should match exactly:

question = "How do I configure authentication for my API?"
query_vec = model.encode(question).tolist()

results = collection.query(
    """SELECT * FROM support_kb
       WHERE vector NEAR $v
       AND content MATCH 'authentication'
       LIMIT 5""",
    params={"v": query_vec}
)

for r in results:
    print(f"  fused={r['fused_score']:.3f} vec={r['vector_score']:.3f}"
          f" | {r['payload']['title']}")

  fused=0.017 vec=0.017 | Setting up two-factor authentication
  fused=0.016 vec=0.016 | Webhook configuration and troubleshooting
  fused=0.016 vec=0.016 | GraphQL API getting started guide
  fused=0.008 vec=0.008 | How to reset your password
  fused=0.008 vec=0.008 | SSO integration with SAML and OIDC

The MATCH operator runs BM25 full-text search. Combined with NEAR, VelesDB fuses both signals using Reciprocal Rank Fusion (RRF). Articles containing "authentication" get a score boost. The fused_score blends semantic relevance (from the vector) with keyword relevance (from BM25).

This solves a classic RAG failure mode: pure vector search might rank a vaguely related billing article above a directly relevant authentication guide, because the embeddings happen to be close. Adding MATCH anchors the results to the user's exact terminology.

Step 5: Graph relationships and traversal

So far we've been querying the vector+columnar store. VelesDB also includes a native graph engine. Let's add knowledge relationships:

# Articles form a learning path
graph.add_edge({
    "id": 101, "source": 1, "target": 2,
    "label": "NEXT_STEP",
    "properties": {"reason": "After password reset, enable 2FA"}
})
graph.add_edge({
    "id": 102, "source": 2, "target": 8,
    "label": "NEXT_STEP",
    "properties": {"reason": "Advanced: set up SSO after 2FA"}
})

# Technical cross-references
graph.add_edge({
    "id": 105, "source": 5, "target": 6,
    "label": "RELATED",
    "properties": {"reason": "Rate limits affect webhook delivery"}
})
graph.add_edge({
    "id": 106, "source": 6, "target": 10,
    "label": "NEXT_STEP",
    "properties": {"reason": "After webhooks, try the GraphQL API"}
})

Now traverse the graph from the top vector search result. If the customer asked about password resets, what should they read next?

# BFS: find related articles within 2 hops
related = graph.traverse_bfs(1, max_depth=2)
for r in related:
    print(f"  depth={r['depth']} | {r['target_id']} via edge path {r['path']}")

  depth=1 | 2 via edge path [101]
  depth=2 | 8 via edge path [101, 102]

The customer asked about password reset. The graph tells us: next, suggest 2FA. After that, SSO. This is the GraphRAG pattern - use vector similarity to find the entry point, then walk the relationship graph to surface connected knowledge.

Step 6: Cypher-like MATCH queries

The Python traversal API works, but writing graph logic in application code means your queries are scattered across functions. VelesQL supports Cypher-like MATCH syntax so you can express graph patterns directly in a query string:

results = graph.match_query(
    "MATCH (article:Article)-[:NEXT_STEP]->(next:Article) "
    "WHERE article.category = 'account' "
    "RETURN article.title, next.title, next.difficulty "
    "ORDER BY article.title "
    "LIMIT 10"
)

for r in results:
    p = r["projected"]
    print(f"  {p['article.title']} -> {p['next.title']} ({p['next.difficulty']})")

  How to reset your password -> Setting up two-factor authentication (intermediate)
  Setting up two-factor authentication -> SSO integration with SAML and OIDC (advanced)

Same data, same graph, but now the query is a single readable string. (article:Article)-[:NEXT_STEP]->(next:Article) reads like a sentence: "find Article nodes linked by a NEXT_STEP edge to another Article." Filter with WHERE, pick your columns with RETURN, sort, paginate. If you've used Cypher, this is familiar.

Now the part that no graph database does alone - combining graph traversal with vector similarity in one query:

question = "I need help securing my account"
query_vec = model.encode(question).tolist()

results = graph.match_query(
    "MATCH (article:Article)-[:NEXT_STEP]->(next:Article) "
    "WHERE similarity(article.embedding, $v) > 0.3 "
    "RETURN article.title, next.title "
    "ORDER BY similarity() DESC "
    "LIMIT 5",
    params={"v": query_vec},
    vector=query_vec,
    threshold=0.3
)

for r in results:
    print(f"  score={r['score']:.3f} | "
          f"{r['projected']['article.title']} -> {r['projected']['next.title']}")

  score=0.621 | How to reset your password -> Setting up two-factor authentication
  score=0.198 | Setting up two-factor authentication -> SSO integration with SAML and OIDC

Read that query out loud: "find Article nodes connected by NEXT_STEP edges, where the article is semantically similar to my question, return titles sorted by similarity." That's vector search and graph traversal in one statement.

Under the hood, the planner picks the best execution strategy automatically:

plan = graph.explain(
    "MATCH (article:Article)-[:NEXT_STEP]->(next:Article) "
    "WHERE similarity(article.embedding, $v) > 0.5 "
    "RETURN article.title, next.title LIMIT 5"
)
print(plan["tree"])

Query Plan:
+-- MatchTraversal
|   +-- Strategy: VectorFirst: Search top-20 candidates, then validate graph
|   +-- Max Depth: 1
|   +-- Relationships: 1
|   +-- Similarity Threshold: 0.50
+-- Limit: 5

Estimated cost: 0.251ms
Index used: HNSW

Three strategies available: VectorFirst (find similar nodes, then walk edges), GraphFirst (traverse first, then score by similarity), or Parallel (run both and merge). The planner chooses based on your query shape. You don't need to think about it.

In a traditional stack, this would be: run a vector search in Pinecone, take the IDs, query Neo4j for neighbors, join results in Python. Here it's one query, one engine, one result set.

Step 7: The complete pipeline

Here's the full support agent in action. One customer question triggers vector search, text matching, metadata filtering, and graph traversal:

def answer_support_question(question: str, graph):
    query_vec = model.encode(question).tolist()

    # Step 1: Hybrid search with filters
    results = collection.query(
        """SELECT * FROM support_kb
           WHERE vector NEAR $v
           AND content MATCH 'API'
           AND resolved_pct > 70
           LIMIT 3""",
        params={"v": query_vec}
    )

    top = results[0]
    print(f"Best match: {top['payload']['title']}")
    print(f"  Score: {top['fused_score']:.3f}")

    # Step 2: Walk the knowledge graph from the top result
    related = graph.traverse_bfs(top["id"], max_depth=2)
    if related:
        print("Related articles:")
        for r in related:
            print(f"  -> article {r['target_id']} "
                  f"(depth={r['depth']})")

    return results, related

answer_support_question(
    "My API calls are getting rejected, need help with rate limits",
    graph
)

Best match: API rate limiting and quotas
  Score: 0.016
Related articles:
  -> article 6 (depth=1)
  -> article 10 (depth=2)

The hybrid search found the API rate limiting article (combining semantic match + keyword "API" + high resolution filter). Then traverse_bfs walked the graph from that entry point to surface connected articles: webhook troubleshooting (article 6, because rate limits affect webhook delivery) and the GraphQL API guide (article 10, as a next step after webhooks).

Four query paradigms - vector, text, columnar, graph - two calls, one engine, zero infrastructure.

What's under the hood

VelesDB v1.9.3 gives you visibility into query execution:

plan = graph.explain(
    "SELECT * FROM support_kb "
    "WHERE vector NEAR $v AND category = 'technical' LIMIT 10"
)
print(plan["tree"])

Query Plan:
+-- VectorSearch
|   +-- Collection: support_kb
|   +-- ef_search: 100
|   +-- Candidates: 10
+-- Filter
|   +-- Conditions: category = ?
|   +-- Selectivity: 50.0%
+-- Limit: 10

Estimated cost: 0.106ms
Index used: HNSW
Filter strategy: post-filtering (low selectivity)

The planner tells you which index it used, the filter strategy, and the estimated cost. When you're debugging slow queries in production, this is gold.

Adaptive search quality

VelesDB v1.9.3 includes search quality modes that trade precision for speed:

# Fast: fewer candidates, lower latency
results = collection.search_with_quality(query_vec, "fast", top_k=5)

# Balanced: good default
results = collection.search_with_quality(query_vec, "balanced", top_k=5)

# Accurate: more candidates, higher recall
results = collection.search_with_quality(query_vec, "accurate", top_k=5)

Five modes available: fast, balanced, accurate, perfect, and autotune. Use fast for autocomplete, accurate for final answers, autotune to let the engine decide based on collection size.

Multi-query fusion

When one question maps to multiple search intents, fuse them:

# Customer asks about both account and billing
q1 = model.encode("password reset account access").tolist()
q2 = model.encode("billing invoice payment").tolist()

results = collection.multi_query_search(
    vectors=[q1, q2],
    top_k=5,
    fusion=velesdb.FusionStrategy.rrf()
)

Five fusion strategies:

velesdb.FusionStrategy.rrf()                         # Reciprocal Rank Fusion
velesdb.FusionStrategy.average()                      # Average scores
velesdb.FusionStrategy.maximum()                      # Take the max
velesdb.FusionStrategy.relative_score(0.7, 0.3)       # Weighted by score type
velesdb.FusionStrategy.weighted(0.5, 0.3, 0.2)        # Custom weight blend

This is useful when a single user query decomposes into multiple search intents - common in agentic RAG pipelines where the LLM generates sub-queries.

VelesQL parser

You can now validate and introspect queries before executing them:

from velesdb import VelesQL

# Validate user input
assert VelesQL.is_valid("SELECT * FROM kb WHERE vector NEAR $v LIMIT 10")
assert not VelesQL.is_valid("DROP TABLE kb")  # Nice try

# Introspect a query
parsed = VelesQL.parse(
    "SELECT * FROM support_kb WHERE vector NEAR $v "
    "AND category = 'technical' LIMIT 5"
)
print(parsed.table_name)          # "support_kb"
print(parsed.has_vector_search()) # True
print(parsed.has_where_clause())  # True
print(parsed.limit)               # 5

The parser understands GROUP BY, HAVING, ORDER BY, JOIN, DISTINCT, and OFFSET:

agg = VelesQL.parse(
    "SELECT category, COUNT(*) FROM kb GROUP BY category"
)
print(agg.group_by)  # ["category"]

ordered = VelesQL.parse(
    "SELECT * FROM kb ORDER BY views DESC LIMIT 10"
)
print(ordered.order_by)  # [("views", "DESC")]

This is valuable for building query builders, admin UIs, or query validation middleware in production systems.

The full picture

Capability	VelesQL Syntax	What it does
Vector search	`WHERE vector NEAR $v`	Semantic similarity (HNSW)
Text search	`AND content MATCH 'term'`	BM25 keyword ranking
Metadata filter	`AND price < 100`	SQL-style conditions
Graph pattern	`MATCH (a:Label)-[:REL]->(b)`	Cypher-like traversal
Graph + vector	`WHERE similarity() > 0.8`	Fused vector + graph
Graph traversal	`graph.traverse_bfs()`	Programmatic BFS/DFS
Query plan	`graph.explain()`	Execution introspection
Quality modes	`search_with_quality("fast")`	Precision/speed tradeoff
Multi-query fusion	`multi_query_search()`	Combine multiple intents
Query validation	`VelesQL.is_valid()`	Pre-execution checks

All of this runs inside a single ~6MB embedded engine. No Docker, no network calls, no infrastructure to maintain.

Why this matters for RAG

The typical RAG architecture looks like this:

Embed the user question
Vector search in Pinecone/Qdrant/Weaviate
Maybe filter results client-side
Maybe query a separate text search engine
Maybe query a graph database for relationships
Glue it all together in application code

With VelesQL:

Embed the user question
SELECT ... WHERE vector NEAR $v AND content MATCH 'term' AND filter = value
MATCH (a)-[:RELATED]->(b) WHERE similarity(a.embedding, $v) > 0.5

Two queries. One engine. Vector, text, metadata, and graph - all in VelesQL.

Less infrastructure. Less code. Fewer failure modes. And because it's embedded, your tests run in milliseconds against real data - no mock database needed.

Getting started

pip install velesdb sentence-transformers

The complete runnable script for this tutorial is available as a single Python file. Copy, paste, run.

Full docs: velesdb.com/en
GitHub: github.com/cyberlife-coder/VelesDB

VelesDB is source-available under the Elastic License 2.0.

What's your current stack for hybrid retrieval? Are you gluing multiple databases together, or have you found a unified approach? I'd love to hear what works (and what breaks) in your RAG pipelines.

Build a local RAG pipeline in 30 lines of Python (no Docker, no API keys)

Julien L — Sun, 29 Mar 2026 07:11:22 +0000

Most RAG tutorials start with "spin up Docker" and "get your API key." This one starts with pip install.

The problem

Retrieval-Augmented Generation (RAG) is the standard way to ground LLM answers in your own data. But the typical setup looks like this:

Spin up a Docker container for your vector database
Sign up for an API and grab your keys
Configure connection strings, authentication, ports
Write 100+ lines of glue code

That is a lot of infrastructure for what is conceptually simple: embed text, store vectors, search by similarity.

What if you could skip all of that?

The 30-line local RAG pipeline

Here is a complete RAG pipeline. No Docker. No API keys. No cloud. Just Python.

pip install velesdb sentence-transformers

from sentence_transformers import SentenceTransformer
from velesdb import Database

# Load embedding model (runs locally, no API key)
model = SentenceTransformer("all-MiniLM-L6-v2")

# Open a local database (just a folder on disk)
db = Database("./rag_data")
collection = db.get_or_create_collection("documents", dimension=384)

# Your documents (from a file, a PDF, a web scrape, anything)
documents = [
    "VelesDB® combines vector, graph, and columnar storage in one binary.",
    "HNSW indexing enables fast approximate nearest neighbor search.",
    "The Python SDK supports both vector search and graph traversal.",
    "RAG pipelines retrieve relevant context before generating answers.",
    "Local-first means no network dependency and full data privacy.",
    "Embeddings capture semantic meaning as high-dimensional vectors.",
]

# Embed and store each chunk
for i, doc in enumerate(documents):
    embedding = model.encode(doc).tolist()
    collection.upsert(i, vector=embedding, payload={"text": doc})

# Search with natural language
query = "How does vector search work?"
query_vec = model.encode(query).tolist()
results = collection.search(vector=query_vec, top_k=3)

for r in results:
    print(f"[{r['score']:.4f}] {r['payload']['text']}")

That is it. 30 lines, and you have a working RAG retrieval engine running entirely on your machine.

What the results look like

When you run the query "How does vector search work?", you get ranked results with cosine similarity scores:

[0.6821] HNSW indexing enables fast approximate nearest neighbor search.
[0.5765] Embeddings capture semantic meaning as high-dimensional vectors.
[0.4938] VelesDB combines vector, graph, and columnar storage in one binary.

The model understands that "vector search" is semantically close to "nearest neighbor search" and "embeddings," even though those exact words do not appear in the query. That is the power of semantic search over keyword matching.

From retrieval to generation

The retrieval step above gives you ranked chunks. To turn this into a full RAG pipeline, you need one more function that formats the results into an LLM prompt:

def build_rag_prompt(collection, model, question, top_k=3):
    query_vec = model.encode(question).tolist()
    results = collection.search(vector=query_vec, top_k=top_k)
    context = "\n".join(r["payload"]["text"] for r in results)
    return f"""Answer the question using only the context below.

Context:
{context}

Question: {question}
Answer:"""

prompt = build_rag_prompt(collection, model, "How does vector search work?")
# Pass 'prompt' to any LLM: OpenAI, Anthropic, Ollama, llama.cpp...

You can feed this prompt to any LLM you want. OpenAI, Anthropic, a local Ollama instance, it does not matter. The retrieval layer is completely decoupled from the generation layer.

The comparison

	Typical RAG stack	This approach
Vector store	Chroma (Docker) or Pinecone (cloud)	VelesDB (`pip install`)
Setup	Docker compose + API keys + env vars	`pip install velesdb`
Lines of code	80-150	30
Network required	Yes (cloud) or Docker daemon	No
Data privacy	Data leaves your machine	Everything stays local
Binary size	500MB+ Docker image	~6MB

Scaling it up

The example above uses a small list of strings, but the pattern scales to real documents. Here is how you would chunk a text file:

def chunk_file(filepath, max_length=500):
    with open(filepath) as f:
        text = f.read()
    paragraphs = [p.strip() for p in text.split("\n\n") if p.strip()]
    chunks = []
    for p in paragraphs:
        if len(p) <= max_length:
            chunks.append(p)
        else:
            sentences = p.split(". ")
            current = ""
            for s in sentences:
                if len(current) + len(s) > max_length:
                    chunks.append(current.strip())
                    current = s
                else:
                    current += ". " + s if current else s
            if current:
                chunks.append(current.strip())
    return chunks

Load, chunk, embed, store. The same pattern every time.

Limitations

This approach is not for everyone:

Single machine only. VelesDB is an embedded database. If you need distributed vector search across a cluster, look at Milvus or Qdrant.
Bring your own embeddings. VelesDB stores and searches vectors but does not generate them. You need a model like sentence-transformers or an API.
No built-in reranking. For production RAG, you might want a cross-encoder reranking step. That is outside VelesDB's scope.

For local development, prototyping, edge deployments, privacy-sensitive applications, and anywhere you want RAG without infrastructure, this works.

Get started

pip install velesdb sentence-transformers

VelesDB® on GitHub (source-available, Elastic License 2.0)
VelesDB on PyPI
sentence-transformers docs

Previous articles in this series:

What is your current RAG stack, and how many moving parts does it have? I am curious whether "just pip install" would work for your use case.

Build an MCP server that gives any LLM long-term memory

Julien L — Sat, 28 Mar 2026 08:09:57 +0000

Your LLM forgets everything after each session. MCP lets you fix that with 3 tools and zero infrastructure.

No database cluster. No Redis. No "memory service" running in the background. Just a Python script and a 3MB embedded engine that persists to disk.

What is MCP (in 30 seconds)

MCP (Model Context Protocol) is the standard way LLMs connect to external tools. Donated to the Linux Foundation, it's now supported by Claude, GPT, Gemini, and most agent frameworks. You write a server that exposes "tools" - the LLM discovers them and calls them when needed.

Think of it as a USB port for AI: plug in a memory server, and every LLM that speaks MCP gets long-term memory.

The full server: 60 lines of Python

Here's a working MCP server that gives any LLM three memory tools: store facts, recall facts, and record events.

from fastmcp import FastMCP
from sentence_transformers import SentenceTransformer
from datetime import datetime
import time
import velesdb

# --- Setup ---
model = SentenceTransformer("all-MiniLM-L6-v2")
db = velesdb.Database("./llm_memory")
memory = db.agent_memory(384)

mcp = FastMCP("LLM Memory Server")

def embed(text: str) -> list[float]:
    return model.encode(text).tolist()

# --- Tool 1: Store a fact ---
@mcp.tool
def remember_fact(content: str) -> str:
    """Store a fact in long-term semantic memory. Use this when you learn
    something important about the user, their project, or their preferences."""
    vec = embed(content)
    fact_id = int(time.time() * 1000) % 2_000_000_000
    memory.semantic.store(fact_id, content, vec)
    return f"Stored: {content}"

# --- Tool 2: Recall relevant facts ---
@mcp.tool
def recall_facts(query: str, top_k: int = 5) -> list[dict]:
    """Search long-term memory for facts relevant to a query.
    Use this at the start of conversations or when you need context."""
    results = memory.semantic.query(embed(query), top_k=top_k)
    return [{"content": r["content"], "score": round(r["score"], 4)} for r in results]

# --- Tool 3: Record a timestamped event ---
@mcp.tool
def record_event(description: str) -> str:
    """Record a timestamped event in episodic memory.
    Use this to log important moments: decisions, errors, milestones."""
    vec = embed(description)
    event_id = int(time.time() * 1000) % 2_000_000_000
    now = int(time.time())
    memory.episodic.record(event_id, description, now, vec)
    ts = datetime.fromtimestamp(now).strftime("%Y-%m-%d %H:%M")
    return f"Recorded at {ts}: {description}"

if __name__ == "__main__":
    mcp.run()

Save this as memory_server.py. That's the entire server.

What each tool does

remember_fact(content) takes any string and stores it as a vector in semantic memory. The embedding is generated automatically using all-MiniLM-L6-v2 (384 dimensions). When the LLM learns that you prefer dark mode, it calls this tool.

recall_facts(query, top_k) searches memory by semantic similarity. The LLM calls this at the start of a conversation to load context about you, or mid-conversation when it needs to check what it already knows.

record_event(description) logs a timestamped event. "User deployed to production." "Fixed the CSS bug." "User said the recursive chunking approach worked." This gives the LLM a timeline of what happened.

Connect it to Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "memory": {
      "command": "python",
      "args": ["memory_server.py"],
      "cwd": "/path/to/your/project"
    }
  }
}

On macOS, the config file lives at ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows: %APPDATA%\Claude\claude_desktop_config.json.

Restart Claude Desktop. You should see the memory tools appear in the tools list.

A real conversation

Here's what it looks like when the LLM actually uses the memory:

You: I'm building a RAG pipeline for legal documents. We're using LangChain with a recursive text splitter, chunk size 512.

Claude (calls remember_fact):

remember_fact("User is building a RAG pipeline for legal documents using LangChain, recursive text splitter, chunk size 512")
→ Stored: User is building a RAG pipeline for legal documents...

Claude (calls record_event):

record_event("Started discussing legal RAG pipeline architecture")
→ Recorded at 2026-03-28 10:15: Started discussing legal RAG pipeline architecture

The next day, you open a new chat:

You: Can you help me with my project?

Claude (calls recall_facts):

recall_facts("user's current project")
→ [{"content": "User is building a RAG pipeline for legal documents using LangChain, recursive text splitter, chunk size 512", "score": 0.4218}]

Claude: Sure! Last time we talked about your legal RAG pipeline with LangChain. You were using a recursive text splitter with chunk size 512. Where did you leave off?

No context window stuffing. No manually copy-pasting previous conversations. The LLM just remembers.

Let's verify the similarity scores

The scores above are real. Here's a standalone test you can run:

from sentence_transformers import SentenceTransformer
import velesdb
import time

model = SentenceTransformer("all-MiniLM-L6-v2")
db = velesdb.Database("./test_memory")
memory = db.agent_memory(384)

def embed(text):
    return model.encode(text).tolist()

# Store some facts
memory.semantic.store(1, "User is building a RAG pipeline for legal documents", embed("User is building a RAG pipeline for legal documents"))
memory.semantic.store(2, "User prefers dark mode in all applications", embed("User prefers dark mode in all applications"))
memory.semantic.store(3, "User's timezone is Europe/Paris", embed("User's timezone is Europe/Paris"))

# Query
results = memory.semantic.query(embed("user's current project"), top_k=3)
for r in results:
    print(f"[{r['score']:.4f}] {r['content']}")

[0.4218] User is building a RAG pipeline for legal documents
[0.1340] User prefers dark mode in all applications
[0.0892] User's timezone is Europe/Paris

The most relevant fact surfaces first with a clear score gap. That's cosine similarity doing its job with a model that runs locally in 384 dimensions.

Building this from scratch vs. using VelesDB®

What you need	From scratch	VelesDB MCP server
Vector storage	Pinecone/Weaviate/Chroma + API keys	`db.agent_memory(384)`
Embedding	OpenAI API calls ($) or local model setup	`sentence-transformers` (local, free)
Timestamped events	PostgreSQL + schema design	`memory.episodic.record()`
Persistence	Managed DB or Docker volume	Automatic (file on disk)
MCP integration	Custom protocol handler	`@mcp.tool` decorator
Infrastructure	3+ services running	Zero. One Python file
Binary size	500MB+ Docker images	~3MB embedded engine

Getting started

Install:

pip install velesdb fastmcp sentence-transformers

The source is on GitHub. VelesDB is source-available under the Elastic License 2.0.

The full MCP server code from this article is ready to copy-paste. Save it as memory_server.py, point Claude Desktop at it, and your LLM will never forget again.

What's your biggest pain point with LLM memory right now? Are you building something with MCP? I'd love to hear about it in the comments.

Give your AI agent a real memory in 50 lines of Python

Julien L — Fri, 27 Mar 2026 17:12:58 +0000

Your AI agent is brilliant for exactly one conversation. Then it forgets everything.

It doesn't remember that the user prefers dark mode. It can't recall that it already solved this exact problem last Tuesday. It has no idea which approach worked and which one failed.

Most developers fix this by duct-taping a vector store, a Redis cache, and a conversation log together. That's three services to maintain for something that should be built into the engine.

I wanted a single pip install that gives an AI agent the same three types of memory that cognitive science describes for humans: what it knows (semantic), what it experienced (episodic), and what it knows how to do (procedural). This distinction comes from Endel Tulving's foundational work (1972) and Larry Squire's taxonomy of memory systems (2004), and it has been successfully implemented in cognitive architectures like SOAR and ACT-R for decades.

So I built it into VelesDB®.

The problem with "memory" in AI agents today

Most agent frameworks give you a flat list of messages or a vector store. That's like giving a human a notebook and calling it memory.

Real memory has structure:

Semantic memory is your knowledge base. Facts, concepts, relationships. "Python is interpreted." "The user's timezone is UTC+1."
Episodic memory is your autobiography. What happened, when, in what context. "Last Tuesday, the user asked about deployment and I suggested Docker."
Procedural memory is your muscle memory. Skills, workflows, learned behaviors. "When the user asks about bugs, first check the logs, then reproduce the issue."

LangChain gives you ConversationBufferMemory. That's episodic at best, and it's just a list. No semantic search, no temporal queries, no skill learning. If you want all three memory types, you're stitching together Pinecone + Redis + Postgres - three services, three APIs, three failure modes.

Setup: one line

pip install velesdb

No Docker. No Redis. No Postgres. The entire engine - vector search, graph storage, and the agent memory SDK - ships as a ~3MB native binary inside the Python wheel.

A complete agent memory in 50 lines

Here's a personal assistant that remembers facts about the user, recalls past conversations, and learns which approaches work:

import velesdb
import time
from sentence_transformers import SentenceTransformer

model = SentenceTransformer("all-MiniLM-L6-v2")
db = velesdb.Database("./agent_brain")
memory = db.agent_memory(384)

def embed(text):
    return model.encode(text).tolist()

# ---- Semantic: store facts the agent learns ----
memory.semantic.store(1, "User prefers dark mode in all applications", embed("User prefers dark mode in all applications"))
memory.semantic.store(2, "User's timezone is Europe/Paris (UTC+1)", embed("User's timezone is Europe/Paris (UTC+1)"))
memory.semantic.store(3, "User is building a RAG pipeline with LangChain", embed("User is building a RAG pipeline with LangChain"))

# ---- Episodic: record what happened during conversations ----
now = int(time.time())
memory.episodic.record(1, "User asked how to chunk PDFs for RAG", now - 86400, embed("User asked how to chunk PDFs for RAG"))
memory.episodic.record(2, "Suggested recursive text splitter, user said it worked", now - 3600, embed("Suggested recursive text splitter, user said it worked"))
memory.episodic.record(3, "User reported slow vector search on 50K vectors", now, embed("User reported slow vector search on 50K vectors"))

# ---- Procedural: learn skills from experience ----
memory.procedural.learn(1, "debug_slow_search", [
    "Check vector count and dimension",
    "Verify HNSW index is built",
    "Profile the query with timing",
    "Consider reducing top_k or adding filters"
], embed("debug slow vector search performance issues"), 0.85)

memory.procedural.learn(2, "help_with_rag", [
    "Ask about data source format (PDF, web, DB)",
    "Recommend chunking strategy based on source",
    "Suggest embedding model for their language",
    "Show how to store and search with VelesDB"
], embed("help user build a RAG retrieval pipeline"), 0.92)

That's your agent's brain. Persisted to disk, searchable, and it survives restarts. Now let's use it.

Querying each memory type

Semantic: "What do I know about this user?"

# The agent needs context about the user before responding
facts = memory.semantic.query(embed("What is the user currently building?"), top_k=3)
for fact in facts:
    print(f"[{fact['score']:.2f}] {fact['content']}")

[0.32] User is building a RAG pipeline with LangChain
[0.11] User's timezone is Europe/Paris (UTC+1)
[0.10] User prefers dark mode in all applications

The agent now knows the user is working with LangChain and RAG before the user even mentions it in this session.

Episodic: "Have we dealt with this before?"

# User says: "My search is slow again"
similar_events = memory.episodic.recall_similar(embed("my vector search is slow"), top_k=2)
for event in similar_events:
    print(f"[{event['score']:.2f}] {event['description']}")

[0.76] User reported slow vector search on 50K vectors
[0.10] User asked how to chunk PDFs for RAG

The agent remembers this exact problem has happened before, with a strong similarity score. Instead of starting from scratch, it can reference past context.

You can also query by time:

# What happened in the last hour?
recent = memory.episodic.recent(limit=5)

# What happened before yesterday?
old_events = memory.episodic.older_than(before=int(time.time()) - 86400, limit=10)

Procedural: "What should I do here?"

# The user mentions slow search. The agent looks up its playbook.
procedures = memory.procedural.recall(embed("vector search is slow, need to debug performance"), top_k=1)
for proc in procedures:
    print(f"Procedure: {proc['name']} (confidence: {proc['confidence']:.0%})")
    for i, step in enumerate(proc['steps'], 1):
        print(f"  {i}. {step}")

Procedure: debug_slow_search (confidence: 85%)
  1. Check vector count and dimension
  2. Verify HNSW index is built
  3. Profile the query with timing
  4. Consider reducing top_k or adding filters

The agent has a learned playbook. And the best part: it gets better over time.

The feedback loop: agents that learn

After the agent follows a procedure and it works, reinforce it:

# The debug_slow_search procedure worked - boost its confidence
memory.procedural.reinforce(1, success=True)

If it failed:

# The procedure didn't help this time
memory.procedural.reinforce(1, success=False)

Confidence scores adjust automatically. Over time, the agent naturally favors procedures that have a track record of working. Confidence scores adjust automatically: +0.1 on success, -0.05 on failure, clamped to [0, 1]. It's a deliberately simple mechanism. Over time, the agent naturally favors procedures that have a track record of working. The idea of reinforcing procedural knowledge through experience is inspired by cognitive architectures like SOAR and ACT-R, though VelesDB keeps the implementation pragmatic rather than trying to model the full complexity of human skill acquisition.

Real use case: a support agent that gets smarter

Here's how these three memory types work together in a realistic scenario:

def handle_user_message(memory, message, model):
    """A support agent that uses all three memory types."""
    msg_vec = model.encode(message).tolist()

    # 1. What do I know about this user? (semantic)
    context = memory.semantic.query(msg_vec, top_k=3)

    # 2. Have we seen this problem before? (episodic)
    past = memory.episodic.recall_similar(msg_vec, top_k=3)

    # 3. What's my best playbook for this? (procedural)
    playbooks = memory.procedural.recall(msg_vec, top_k=1, min_confidence=0.5)

    # Build the prompt with real context
    prompt = f"User message: {message}\n\n"
    if context:
        prompt += "Known facts about this user:\n"
        prompt += "\n".join(f"- {c['content']}" for c in context) + "\n\n"
    if past:
        prompt += "Relevant past interactions:\n"
        prompt += "\n".join(f"- {p['description']}" for p in past) + "\n\n"
    if playbooks:
        p = playbooks[0]
        prompt += f"Recommended procedure ({p['name']}, {p['confidence']:.0%} confidence):\n"
        prompt += "\n".join(f"  {i+1}. {s}" for i, s in enumerate(p['steps']))

    return prompt

# Example
prompt = handle_user_message(memory, "My vector search is really slow", model)
print(prompt)

The agent doesn't just answer the question. It brings the full context: who the user is, what happened before, and what to do about it. That's the difference between a chatbot and an assistant.

What this replaces

What you need	Without VelesDB	With VelesDB
Semantic memory	Pinecone/Chroma + custom metadata	`memory.semantic.store()`
Episodic memory	Redis/Postgres + timestamp queries	`memory.episodic.record()`
Procedural memory	Custom code + JSON files	`memory.procedural.learn()`
Infrastructure	3 services, 3 APIs, Docker	`pip install velesdb`
Disk footprint	500MB+ Docker images	~3MB binary, data files only

Limitations (being honest)

VelesDB is a single-node embedded database. It's not a replacement for a distributed system.

Scaling: if your agent needs to handle millions of memories across multiple machines, use a client-server vector database
Multi-process: VelesDB locks the database directory, so one process at a time (fine for most agent use cases)
Embedding model: you bring your own, VelesDB stores and searches vectors but doesn't generate them

For the 90% of agent projects that run on a single machine with thousands to hundreds of thousands of memories, this is the entire backend.

Getting started

pip install velesdb

import velesdb

db = velesdb.Database("./agent_brain")
memory = db.agent_memory(384)  # dimension of your embedding model

# Store a fact
memory.semantic.store(1, "User likes Python", [0.1, 0.2, ...])  # 384-dim vector

# Record an event
memory.episodic.record(1, "User asked about Python", int(time.time()), [0.1, ...])

# Learn a procedure
memory.procedural.learn(1, "help_with_python", ["Check version", "Suggest docs"], [0.1, ...], 0.8)

Full docs: velesdb.com/en
GitHub: github.com/cyberlife-coder/VelesDB
Python SDK (MIT): pypi.org/project/velesdb

References

The Agent Memory SDK is grounded in decades of cognitive science research:

Tulving, E. (1972). Episodic and Semantic Memory. In E. Tulving & W. Donaldson (Eds.), Organization of Memory (pp. 381-403). Academic Press. The foundational paper that introduced the distinction between semantic memory (general knowledge) and episodic memory (personal experiences).
Squire, L.R. (2004). Memory systems of the brain: A brief history and current perspective. Neurobiology of Learning and Memory, 82(3), 171-177. The modern taxonomy that maps declarative (semantic + episodic) and nondeclarative (procedural) memory to distinct brain systems.
Anderson, J.R. (1996). ACT-R: A Theory of Higher Level Cognition. Human-Computer Interaction, 12(4), 439-462. The cognitive architecture that models how declarative knowledge compiles into procedural skills through practice. VelesDB's procedural.reinforce() borrows the core idea (procedures gain or lose confidence with experience) while keeping the implementation simple and predictable.
Laird, J.E., Newell, A., & Rosenbloom, P.S. (1987). SOAR: An Architecture for General Intelligence. Artificial Intelligence, 33(1), 1-64. The first cognitive architecture to unify problem-solving, learning, and multiple memory systems in a single agent framework.

I'm building VelesDB as a source-available local-first database for AI applications. If you're working on AI agents and struggling with memory management, I'd like to hear about your setup. What are you currently using to persist agent state between sessions?