HFresh is Weaviate's disk-based vector index for applications that prioritize lower memory use over peak query throughput. That tradeoff is useful for small applications with limited resources as well as large datasets. Weaviate Cloud's Free Tier, for example, uses HFresh by default through its Cost Optimized profile.

Understanding HNSW's memory bottleneck in similarity search​

When it comes to finding similar vectors quickly, HNSW (Hierarchical Navigable Small World) has become the gold standard. It's fast and accurate, but as datasets grow from millions to billions of vectors, HNSW reveals a fundamental constraint: its graph and vector cache are kept in memory.

HNSW is a graph-based index that organizes vectors into a hierarchical structure. At the top layer, you have a sparse graph with long-distance connections that help you quickly navigate to the right neighborhood. As you descend through the layers, the graphs become denser with more local connections, eventually guiding you to the most similar vectors at the bottom layer.

The question isn't whether HNSW is good. It absolutely is. If you need the lowest possible latency and highest throughput, HNSW is hard to beat. But many applications prioritize lower memory use and larger scale over peak query performance.

This is where disk-based indexes become interesting. What if you could trade some latency for much lower memory use and the ability to scale to larger datasets?

Introducing HFresh​

HFresh is a modern disk-based vector index designed for high recall, strong update performance, and controlled query I/O at large scale. It builds on ideas introduced by the SPFresh research paper, adapting the design to use battle-tested components already present in Weaviate.

At a high level, HFresh belongs to the family of partition-based vector indices. Instead of connecting every vector to neighbors in a global graph like HNSW, HFresh divides vectors into many small regions called postings. Each posting contains vectors that are close to each other in vector space and is stored on disk in an LSM store.

To make this layout efficient, HFresh uses a two-stage search strategy.

First, a compact in-memory centroid index identifies which regions of the vector space are relevant to a query. Then, only corresponding postings are fetched from disk and searched in detail. By limiting disk reads to a small subset of the dataset, HFresh is designed to keep I/O bounded and latency predictable, even as the dataset grows into billions.

This structure is designed to support very large datasets while keeping performance predictable.

Freshness without rebuilds​

The key idea behind SPFresh, and inherited by HFresh, is that most updates only affect a small region of the vector space.

In traditional partition-based indexes, updates can accumulate and partitions can drift, eventually requiring a full rebuild to restore recall and latency, a process that can take hours or days at scale.

SPFresh shows that this is often unnecessary. In a well-structured partitioned index, inserting or deleting a vector typically only affects a small neighborhood of the vector space. Instead of rebuilding everything, you can maintain index quality through incremental rebalancing, using a small set of local operations.

• Splitting oversized postings
• Merging undersized ones
• Reassigning vectors when boundaries shift

These operations run mostly asynchronously in the background, continuously repairing small local imbalances before they accumulate into global problems. The result is an index that stays fresh and well-balanced over time, without disruptive rebuild cycles.

How HFresh builds on SPFresh​

HFresh takes the core idea behind SPFresh and adapts it to fit Weaviate's architecture. The goal was not to reproduce the paper component by component, but to keep what makes the design so interesting:

• local maintenance instead of rebuilds
• controlled query I/O
• a clear separation between the in-memory routing layer and disk-based postings

From there, we made a series of pragmatic choices. Instead of introducing entirely new ANN machinery, we reused battle-tested pieces already present in Weaviate and shaped them to serve this new layout. This means keeping the overall SPFresh philosophy, while rethinking some of its components to better match Weaviate's strengths around indexing, filtering, compression, and updates.

HNSW as the centroid index​

A key design choice in HFresh is the use of HNSW as the centroid index, rather than SPTAG.

SPTAG is the ANN index used in Microsoft's original SPANN design and carried over into SPFresh. It combines a partitioning tree with a graph, allowing queries to quickly navigate toward the closest centroids and, from there, the right posting lists. For Weaviate, however, HNSW was the more natural fit: it already plays that role very well.

HNSW is the most widely used vector index in Weaviate and one of the most battle-tested parts of the system. We understand its behavior well in production, across a wide range of workloads and dataset sizes. Reusing it for centroid search lets HFresh build on infrastructure that is already proven, rather than introducing a brand-new mechanism.

HNSW is also a strong fit for what the centroid index actually needs to do. In HFresh, the centroid layer is responsible for routing queries to the right postings quickly and accurately. That means it must remain compact, have low latency, and support frequent updates as postings evolve over time.

Centroids are not static: splits, merges, and reassignments continuously reshape the partitioning of the vector space, so the centroid index must be able to absorb many insertions and deletions without requiring expensive rebuilds.

Another advantage is that the centroid index can itself be quantized. Because the centroid layer is only used to identify promising regions of the vector space, HFresh can compress those vectors aggressively enough to reduce memory usage while maintaining the accuracy needed for strong recall. In fact, HFresh uses HNSW with RQ8, reducing memory usage of centroids by 4x.

Using HNSW here also means that improvements to HNSW automatically benefit HFresh. A good example is ACORN, which improves filtered search by making graph traversal more efficient when only part of the dataset matches a filter. Since HFresh relies on HNSW as the centroid layer, those improvements are not isolated: they strengthen HFresh's query path.

Quantization​

HFresh uses Rotational Quantization in two places, with two different compression levels.

The reason is that the two stages of search have different jobs. The centroid index routes the query to the right postings, so it needs enough precision to avoid sending the query to the wrong part of the vector space. The postings, on the other hand, are used to generate candidates. Their approximate scores are not the final ranking, because HFresh later rescores the best candidates using the original uncompressed vectors.

Rotational Quantization works by rotating vectors into a representation that is easier to compress, then reducing the precision of each dimension. HFresh uses:

• RQ8 for centroids, reducing centroid vector memory by 4x
• RQ1 for postings, reducing stored vector data by up to 32x compared to 32-bit floats

RQ8 for the centroid index​

The first stage of HFresh search uses an HNSW index over centroids. This in-memory index identifies which postings are likely to contain the nearest neighbors for a query.

HFresh uses RQ8 here because routing mistakes are expensive. If the centroid search misses the right region, the later posting scan may never see the true nearest neighbors. RQ8 gives a strong compromise: it makes centroid-vector payloads approximately 4x smaller before overhead while keeping enough precision for accurate routing.

This works especially well because the centroid index is much smaller than the full vector dataset. HFresh can afford a higher-precision compression format for centroids, while still keeping the in-memory layer compact.

RQ1 for postings​

After HFresh has selected the most promising postings, it scans the vectors stored inside them. This stage has a different tradeoff.

Postings live on disk, so their size directly affects storage cost and query I/O. HFresh stores posting vectors with RQ1, where each dimension is represented with a single bit. Compared to 32-bit float vectors, that is up to a 32x reduction in vector storage.

That aggressive compression makes each posting smaller and cheaper to read. It also makes the first-pass distance computation fast enough to scan many candidates.

HFresh does not rely on RQ1 scores for the final ranking. Instead, RQ1 is used to build a candidate set. HFresh then fetches the original uncompressed vectors for the top candidates and recomputes exact distances during rescoring. This keeps disk reads small without giving up final ranking quality.

Background operations​

The reason HFresh can stay balanced over time without rebuilds is that maintenance is built directly into the index. Instead of letting imbalances accumulate and then fixing everything in one large offline job, HFresh breaks down maintenance into small background tasks that can be processed continuously.

In practice, most foreground writes stay simple: vectors are appended quickly, and follow-up work is pushed to background queues. Those tasks are persisted in dedicated on-disk queues, so they survive restarts and can be drained incrementally by the scheduler.

HFresh organizes this work into three main background task types: split, merge, and reassign.

Split: When a posting grows too large, HFresh splits it. The posting is loaded, stale entries are garbage-collected, its vectors are divided into two balanced groups using the Balanced K-Means algorithm, and two new centroids are created to replace the old one. This keeps postings from growing too much, which would make disk reads heavier and routing less precise.

Merge: The opposite problem is postings that become too small. That can happen after deletes or simply as the data distribution evolves. In those cases, HFresh looks for a nearby posting that can absorb the smaller one without becoming too large itself. If it finds a good candidate, it merges the two and removes the extra centroid. This prevents the index from fragmenting into too many tiny postings.

Reassign: After a split or a merge, some vectors may no longer belong in the posting where they are currently stored. That's where reassignment comes in. The SPFresh paper describes a protocol called LIRE (Lightweight Incremental Rebalancing) which, after a split, checks whether some vectors would now fit better under one of the new centroids, or even under a neighboring posting. After a merge, it checks whether some vectors that were absorbed should really be moved elsewhere instead. These reassignments let HFresh progressively correct mistakes instead of trying to get everything perfect in one step.

Together, these background operations form a continuous balancing loop. Inserts make local changes, and the index quietly tidies itself up afterward. The result is an index that stays fresh over time without disruptive rebuild cycles.

Filtered search​

Filtered vector search adds another constraint: results must be similar to the query vector while also satisfying the filter. In an e-commerce search, for example, that might mean finding similar products from specific brands, within a price range, and currently in stock.

HFresh uses an allow list, represented as a bitmap, to track the document IDs that satisfy the filter. It then chooses between two search strategies based on the number of matching vectors.

For highly selective filters, running the full HFresh pipeline can cost more than searching the matching subset directly. When the allow list contains fewer than 5,000 IDs, HFresh bypasses centroid routing and posting scans, fetches the original vectors for those IDs, and computes exact distances over them. The current 5,000-ID cutoff is a fixed internal heuristic, not a configurable threshold or a general tuning recommendation.

Posting-aware filtering​

For broader filters, HFresh uses its regular two-stage search with a posting-aware form of prefiltering. The filter identifies matching objects, but the centroid HNSW routes queries to postings rather than individual objects. HFresh bridges those two levels using metadata that records which vector IDs belong to each posting.

The process is:

1. Translate the object-level allow list into posting eligibility using the posting metadata.
2. Navigate the centroid HNSW with ACORN, selecting postings that can contribute at least one matching vector.
3. Read the selected postings and reapply the original allow list while scanning their compressed vectors.
4. Rescore the top candidates using their original uncompressed vectors.

Because HFresh can replicate a vector across multiple postings, it also tracks which matching vectors have already contributed to posting selection. This avoids reading multiple postings solely because they contain replicas of the same match. Together, posting-level selection and vector-level checks reduce unnecessary disk reads while ensuring that the final results satisfy the filter.

How to use HFresh​

To use HFresh, configure it as the vector index when creating a collection.

Here is an example using the Python client:

from weaviate.classes.config import Configure, VectorDistances

collection = client.collections.create(
    name="Article",
    vector_config=Configure.Vectors.self_provided(
        name="Title",
        vector_index_config=Configure.VectorIndex.hfresh(
            distance_metric=VectorDistances.COSINE,
        ),
    ),
)

Experiments​

We benchmarked uncompressed HNSW, HNSW with RQ1, HNSW with RQ8, and HFresh on the DBpedia OpenAI 1M dataset. HNSW indexes were built with efConstruction=256 and maxConnections=16.

Heap usage​

These measurements report Go heap usage, not total process or system memory. HFresh also relies on OS-managed caching for its on-disk data, which is not captured by the heap figures.

The clearest difference is heap usage at rest. HFresh uses 239 MB of heap, compared with 6.67 GB for uncompressed HNSW.

HFresh also uses less heap than quantized HNSW. HNSW with RQ1 uses 715 MB, approximately 3x as much as HFresh, while HNSW with RQ8 uses 2.38 GB, approximately 10x as much.

This difference follows directly from HFresh's architecture. HFresh keeps the RQ8-compressed centroid index and supporting metadata in memory while storing compressed postings on disk. Posting membership, vector versions and deletion state, and posting sizes also consume heap and grow with the dataset, but this layout reduces the heap required for index data.

Query throughput​

The QPS-recall curve shows the query-performance side of HFresh's heap advantage.

At comparable recall, HNSW and its quantized variants deliver substantially higher throughput than HFresh. This is expected: HNSW searches an in-memory graph, while HFresh reads selected postings from disk and fetches original vectors for rescoring.

These results clarify when to choose each index. HNSW remains the better option when the lowest latency and highest throughput matter most. HFresh is designed for workloads where keeping the full index in memory is too expensive and lower throughput is an acceptable tradeoff for a much smaller heap footprint.

Scaling to one billion vectors​

Separately from the DBpedia benchmarks, we tested HFresh index construction with one billion randomly generated 256-dimensional vectors. We used default index-construction settings and imported batches of 1,000 with 12 workers.

The run successfully constructed the billion-vector HFresh index. No recall or QPS measurements were collected for this scale test.

The VM memory measurements come from GCP system metrics, while the heap measurement comes from a Go heap profile.

Conclusion​

HFresh gives Weaviate a disk-based index for memory-efficient vector search, from small applications to large, mutable datasets. By keeping a compact centroid index and supporting metadata in memory and maintaining disk-resident postings incrementally, it reduces the heap required for index data without relying on full index rebuilds. HNSW remains the better choice when the lowest latency and highest throughput matter most; HFresh is designed for workloads where a smaller heap footprint justifies lower query throughput.

HFresh was introduced as a technical preview in Weaviate 1.36 and became generally available in Weaviate 1.38. See the documentation to get started.

If you are evaluating HFresh for a large-scale workload, we would like to hear about your dataset, performance requirements, and results.

Ready to start building?​

Check out the Quickstart tutorial, or sign up for a free Weaviate Cloud account.

Building Foundry
A practical series on creative workflows, semantic search, and Weaviate.

Read the previous post in the series: Part 2: Where creative workflows break.

Part 1 introduced the problem. Part 2 showed why familiar ways of organising work become less reliable as an archive grows. Now we are going to build the solution.

Foundry turns an existing archive into a searchable creative library. It scans the files, records what it finds, prepares each asset for retrieval, and synchronises the result with Weaviate. Nothing is moved or renamed. Every result still leads back to its original source.

creative archive
      ↓
read-only scanner
      ↓
manifest and descriptions
      ↓
Weaviate collection
      ↓
keyword, semantic, or hybrid search
      ↓
source asset

Starting with the archive we already have​

Our test archive contains 23 assets from five fictional projects. Inside are concept art, design exports, production notes, audio, video, and reference images.

The names are deliberately inconsistent:

final_FINAL_v7.svg
BROLL_NEW2.svg
scene_14_USE_THIS.svg
logo_options_FINAL3.svg
bridge_texture.svg

That mess is intentional. Foundry should be useful with the archive a team has today, not the perfectly organised archive it may never have time to create.

Step 1: scan without changing the source​

Foundry begins with a read-only scan. It walks the selected folder and records facts about every supported file.

npm install
npm run demo

The scanner captures the source path, project, file type, size, modified date, and a content hash. It writes the result to output/manifest.json.

The content hash gives each asset a stable identity. It lets Foundry detect changes even when a filename stays the same and skip work when nothing has changed.

The browser turns that inventory into something visual. Images have previews, videos can be played, and documents remain visible without thumbnails.

This first checkpoint matters because search cannot find what the scanner missed.

Step 2: prepare records for retrieval​

The manifest tells us what exists. The next step is to describe what those files contain.

The preparation stage adds descriptions, tags, extracted text, relationship roles, and a source URI. A prepared image record looks like this:

{
  "fileName": "rain-floor.jpg",
  "relativePath": "RAIN TRAILER/References/rain-floor.jpg",
  "project": "RAIN TRAILER",
  "assetType": "image",
  "relationshipRole": "reference",
  "description": "Heavy rain striking a reflective floor with bright droplets and bokeh.",
  "tags": ["rain", "wet floor", "reflection", "atmosphere"],
  "sourceUri": "foundry://RAIN TRAILER/References/rain-floor.jpg"
}

The foundry:// URI points back to the asset without treating Weaviate as file storage. A production version could use a DAM link, mounted path, S3 URL, or application route.

For now, the demo uses a small enrichment manifest so every run produces the same result. Later versions can generate this context from image captions, OCR, transcripts, and video keyframes.

Step 3: synchronise with Weaviate​

Before synchronisation, Foundry shows exactly what will be indexed. The user can review descriptions, metadata, and source paths before anything reaches Weaviate.

The application then creates or updates the Foundry collection. Weaviate generates embeddings and stores them beside the metadata. Each object keeps its source path and rights status.

Running the process again does not create duplicates. Deterministic identifiers ensure that each asset updates the same object.

The same workflow is available from the command line:

npm run scan
npm run ingest:prepare
npm run ingest:cloud

Cloud credentials stay in a local .env file:

WEAVIATE_URL=https://your-cluster.weaviate.network
WEAVIATE_API_KEY=replace-with-a-read-write-api-key
WEAVIATE_COLLECTION=Foundry

Step 4: search the archive​

Once synchronisation finishes, the archive becomes a live search workspace.

The first test query is easy to describe but hard to map to a filename:

white rabbit in a grassy landscape

The results include a rabbit reference, the Big Buck Bunny trailer, and related landscape imagery. There is no need to remember a filename or folder. The user describes what they remember and Foundry brings the relevant work back into view.

Foundry exposes three retrieval modes:

keyword  → exact words and names
semantic → meaning represented by embeddings
hybrid   → keyword and semantic signals combined

Keyword search works when someone remembers a filename or production term. Semantic search works when they remember the content. Hybrid search brings both kinds of memory into one result set.

Filters make those results practical. Users can narrow the archive by project, file type, or relationship role. The same pattern can support approval status, rights, expiry dates, and delivery formats.

What the build proves​

The prototype now completes the journey from source folder to useful result:

• It scans a nested archive without changing the source files.
• It creates stable records and detects changes with content hashes.
• It enriches records before ingestion instead of relying on filenames alone.
• It stores searchable records and managed embeddings in Weaviate.
• It compares keyword, semantic, and hybrid retrieval on the same archive.
• It returns images and video with links back to their source.

Foundry is still a prototype. Automatic enrichment, incremental rescans, rights-aware filtering, and relevance feedback would be the next update to the project.

Run Foundry​

The project is available on GitHub.

cp .env.example .env
# Add your Weaviate Cloud URL and API key

npm install
npm run demo

Use Node.js 22 or newer for cloud synchronisation and live search. The local inventory can run without cloud credentials.

From hidden files to useful history​

Foundry began with a familiar creative frustration: remembering the work but not where it lives.

It does not replace the folders, tools, or habits behind that work. It gives the archive a new way to reveal itself. An asset that once depended on the right filename, folder, or colleague can now be found through the idea behind it.

The archive stops being a place where finished work disappears. It becomes creative material again.

Ready to start building?​

Check out the Quickstart tutorial, or sign up for a free Weaviate Cloud account.

Intro​

If you have ever tried to put a stack of investor decks, scientific papers, or annual reports through a RAG pipeline, then you know the drill: set up an Optical Character Recognition (OCR) or text-extraction step, pick a chunking strategy, embed text, and finally retrieve information. After going through all this, someone may ask a question about revenue in Q2 FY25, and your retrieval would return three pages of unrelated bullet points because the actual answer is in a bar chart that was invisible to your index.

This used to be what people had to do — just leave out the interesting parts of a PDF from RAG such as bar charts with trends, comparison tables, architectural diagrams, and things in general that make PDFs so much more valuable than mere text.

In this article, we'll show you a better way that not only retrieves the rich information embedded in charts, but also eliminates complex processing steps. We'll cover:

• Classic RAG: Why OCR and text embedding works great for some (structured and unstructured) data, but not for rich PDFs.
• Late Interaction RAG: What late-interaction multi-vector models are, and why they let you skip text extraction entirely.
• Drag-N-Drop and Done: How to ingest multiple PDFs in Weaviate Cloud with just a few clicks.
• Real Examples: Example queries against NVIDIA's FY2026 quarterly earnings, where each top result is the exact chart that answers a question.
• Complex Agentic Reasoning: How to wrap the same data with the Weaviate Query Agent for synthesised answers with page-image citations.
• Codified and Deployment-Ready: The same ingestion pipeline in roughly 50 lines of Python for when you need to deploy this in production.

If you'd rather just see the demo first and read the explanations later, skip to the queries section below.

How traditional RAG falls short​

Let's first look at what most people do today when it comes to building a RAG pipeline for PDFs:

1. OCR (or text-extract) the file (using either a python library or third-party tooling).
2. Chunk the text.
3. Embed the chunks with a text embedding model.
4. Retrieve, (maybe) rerank, generate.

There's nothing inherently bad about this workflow, but there's a naive underlying assumption that the page can be reduced to a sequence of text tokens without losing the richness of the content. For a press release or a Wikipedia article, this is mostly fine, but for a slide deck full of charts, a 10-K with comparison tables, or an academic paper with illustrative figures, it's simply not enough.

You could build a complex ETL pipeline to extract charts and vectorize them separately, but that means another model in the pipeline and introduces more complexity into the stack as well as merging problems at query time.

With a late-interaction multi-vector model, you don't need any of those: You embed the page, and not the text within it. The model sees the chart the way you do. Yes, you heard that right, there is not even a chunking step — the page is the chunk.

Late-interaction multi-vector retrieval, in two paragraphs​

Before we get to the demo, let's take a quick detour on what makes this work. If you already know your way around ColPali / ColBERT, feel free to skip or skim.

Traditional dense embedding models compress an entire document (or chunk) into a single vector. Late-interaction multi-vector models do something different: they encode the document as a set of vectors, typically one per token (or for a vision model like the one we're about to use, one per image patch). At query time, your query is also encoded as a set, and the relevance score is the sum of best matches between query tokens and document tokens (a quantity called MaxSim).

Instead of asking "is this whole page about my whole question?", the model can ask "is the part of this page that talks about Q4 FY26 a good match for the part of my question about 'change over time'?". For a chart-heavy page, this is exactly the granularity that's needed. The model doesn't have to summarise an entire slide into a single vector, but can keep one vector per region of the page, and the query can pick out the regions that matter.

So really, there are two distinct advantages here:

1. Because it's a visual model you keep the layout, the charts, the tables, etc. and
2. By using MaxSim over a set of vectors, you eliminate the need for chunking.

Weaviate offers multi2multivec-weaviate, a vectorizer module that runs a hosted late-interaction multi-vector model on Weaviate Cloud, so you don't have to host or manage a model in order to generate multi-vectors from your PDFs.

Ingesting PDFs by Drag-and-Drop​

The fastest way to try this is the drag-and-drop importer in Weaviate Cloud.

1. Open your cluster in the Console.
2. Go to Collections and create a new collection.
3. Select the upload from file option and drop in your PDFs.

And that's the entire ingestion process. Behind the scenes, Weaviate is doing three things:

1. Rendering each PDF page to a high-resolution image.
2. Storing that image as a BLOB property on a new collection.
3. Vectorizing it with the multi2multivec-weaviate module, producing many vectors per page.

A few things are worth noting:

• One object equals one page. The unit of retrieval is the page, which is also the unit a human navigates a document by.
• No OCR. The model never sees the text as text. It sees the page as an image. That's why a chart with no caption is just as searchable as a paragraph.
• The vectors are compressed. Late-interaction models can produce hundreds of vectors per page, which would be expensive to store naively. Weaviate uses a multi-vector encoding scheme that keeps the index compact. (More on that also in the trade-offs section below.)

For this demo, we've imported NVIDIA's four FY2026 quarterly investor presentations (Q1 through Q4). They cover the financial year ending in January 2026, contain wall-to-wall charts and tables, and total 92 pages. The whole import took about a minute and a half.

Interrogating NVIDIA's Quarterly Earnings​

Before we do anything fancy such as agentic reasoning on the data, we want to show you the raw retrieval results, as they are already impressive on their own.

With ingestion complete, you can query the data directly in the Console (or with any Weaviate client). The query is in plain English, and the result is a ranked list of pages with page images inline.

Let's walk through three queries and show you what results are returned.

Query 1: "how did automotive revenue change over time?"​

The top result is a single page from the Q2 FY26 deck, titled Automotive. The left half is a bar chart showing five quarters of revenue ($346M → $449M → $570M → $567M → $586M, +69% Y/Y). The right half contains three bullet points about Thor SoC and DRIVE AV.

The phrase "over time" doesn't appear anywhere on this page. Neither does the word "change". The model didn't match against text semantically, but rather the image of the page. What it saw was five bars of increasing height with quarterly labels, and that was enough to identify the page as a match for a question about a temporal trend.

Query 2: "gross margin trend"​

The top result here is the Q2 FY26 Financial Summary page. On the left is a combination chart: revenue bars and a non-GAAP gross margin line over five quarters. On the right is a GAAP/non-GAAP KPI table with Y/Y and Q/Q deltas.

Again, nothing on this page literally says "gross margin trend", but there is a line chart that visualises the gross margin dipping from 75.7% to 61.0% in Q1 FY26 and recovering to 72.7% in Q2 FY26. That's what a trend looks like, and it's what the model retrieved.

A side note: the same page also contains a detailed financial table. That makes it a particularly useful retrieval target if you're then going to ask follow-up questions like "by how many basis points did gross margin recover Q/Q?" The answer is sitting on the page the model already returned. More on that below when we introduce the Query Agent.

Query 3: "how did data center revenue change over time?"​

The top result is the Q4 FY26 Revenue page — a Y/Y bar chart ($39.3B → $68.1B) with a callout that data center revenue is up 13x since the emergence of ChatGPT. This is a great example that the model still respects text when it's the better match. In this case the chart is less relevant, but the box stating the exact answer is what returned the highest similarity (MaxSim) on this page. So you get the best of both modalities.

The runner-up is the dedicated Data Center page from a different quarter, which splits the segment into Compute and Networking:

Notice how the second-best match isn't simply "another page about data center", but a different kind of answer — the same revenue, broken down differently. That's a useful property for an agent that wants to triangulate across multiple views of the same underlying number. Speaking of which...

From search to answers: the Weaviate Query Agent​

Vector search returns results, but sometimes you want an answer.

The Weaviate Query Agent is a managed agent that wraps vector retrieval with multi-step reasoning, source citations, and inline page images. It is available out of the box for any Weaviate Cloud cluster. Simply point it to a collection and ask a question.

If we ask "How did automotive revenue change across FY26 quarters? What's driving it?" about the same collection, the agent comes back with a synthesised answer (the numbers from the bar chart, plus the bullet points about Thor SoC and DRIVE AV adoption) and the underlying page images as citations. The agent decided which pages to retrieve, looked at them visually, and quoted directly from the slide.

Open the Sources panel and you'll see exactly which pages backed the answer. Among the citations is the Automotive page from the Q1 FY26 deck — the same kind of bar chart we surfaced in the raw vector search earlier, just for a different quarter.

Every numerical claim in the response is anchored to a specific page in a specific PDF, with the page image right there for verification. You don't have to blindly trust the agent, but can read the contents of the slide for yourself.

Building a deployable pipeline with Python​

The drag-and-drop UI is the fastest path to creating a POC, but most production pipelines need code, and here is the equivalent in roughly 50 lines.

First, install the dependencies:

pip install "weaviate-client>=4.21" PyMuPDF

Then, render each PDF page to a 2000-pixel PNG and store it as a BLOB in a collection vectorized with multi2multivec-weaviate:

import os
from base64 import b64encode
from pathlib import Path

import fitz  # PyMuPDF
from weaviate import connect_to_weaviate_cloud
from weaviate.classes.config import Configure, DataType, Property


def page_to_b64(page, long_edge: int = 2000) -> str:
    scale = long_edge / max(page.rect.width, page.rect.height)
    pix = page.get_pixmap(matrix=fitz.Matrix(scale, scale))
    return b64encode(pix.tobytes(output="png")).decode()


client = connect_to_weaviate_cloud(
    os.environ["WEAVIATE_URL"],
    auth_credentials=os.environ["WEAVIATE_API_KEY"],
)

if not client.collections.exists("PDF"):
    client.collections.create(
        name="PDF",
        properties=[
            Property(name="pdf_name", data_type=DataType.TEXT),
            Property(name="page_number", data_type=DataType.INT),
            Property(name="page_image", data_type=DataType.BLOB),
        ],
        vector_config=Configure.MultiVectors.multi2vec_weaviate(
            image_field="page_image",
        ),
    )

col = client.collections.get("PDF")
for pdf_path in Path("pdfs").glob("*.pdf"):
    with col.batch.fixed_size(batch_size=2) as batch, fitz.open(pdf_path) as doc:
        for i, page in enumerate(doc, start=1):
            batch.add_object(properties={
                "pdf_name": pdf_path.name,
                "page_number": i,
                "page_image": page_to_b64(page),
            })

client.close()

A few notes on the above:

• The Python call MultiVectors.multi2vec_weaviate(image_field="page_image") configures the multi2multivec-weaviate module. This is the same vectorizer used by the Console import UI.
• PyMuPDF does the rasterization. The 2000 pixel long-edge target is a sensible default; smaller targets saves time while larger gives the model more detail. We haven't found a strong case for going below 1500 or above 2500.
• batch_size=2 is intentional. Each object carries a multi-megabyte image, so small batches keep the gRPC payload sane.

Query the created collection to return ranked pages:

from weaviate.classes.query import MetadataQuery

res = col.query.near_text(
    query="how did automotive revenue change over time",
    limit=5,
    return_properties=["pdf_name", "page_number"],
    return_metadata=MetadataQuery(distance=True),
)
for o in res.objects:
    print(o.metadata.distance, o.properties)

On the NVIDIA corpus, this returns the Q2 FY26 Automotive page as result #1: the same five-quarter bar chart you saw above, retrieved by an end-to-end pipeline that contains zero OCR.

The same Query Agent you saw in the Console is also available from Python. Pass it the collections to reason over, then ask():

from weaviate.agents.query import QueryAgent
from weaviate_agents.classes import QueryAgentCollectionConfig

agent = QueryAgent(
    client=client,
    collections=[
        QueryAgentCollectionConfig(name="PDF"),
    ],
)

response = agent.ask("How did automotive revenue change across FY26 quarters? What's driving it?")
response.display()

response.display() renders the same synthesised answer plus page-image citations you saw in the Console.

So is this the silver bullet for PDFs?​

Of course not. As always in Engineering, there are trade-offs:

• Many vectors per object/page. Late-interaction multi-vector models produce many vectors per page. You can partially offset this with compression techniques, such as Muvera, which are natively supported in Weaviate. This helps, but also introduces a compression/accuracy trade-off. For a corpus that is dominated by large amounts of plain text (think legal contracts, transcripts, or log files), a text embedding model will still be cheaper and just as accurate.
• Page-level retrieval is coarse. If your answer lives in one paragraph buried in a dense contract, returning a whole page may be more context than you want. In practice, we see this typically mitigated in the agent layer (e.g. Weaviate's Query agent), where the relevant paragraph can be identified without requiring a significant number of tokens.
• The model has to understand your charts. It generalises well from the public corpora it was trained on, but if you have very domain-specific visual conventions (think highly stylised internal templates), you should validate retrieval quality on it first.

So when does this approach with late-interaction multi-vector models win? Mostly in PDF-heavy domains that contain assets such as quarterly slide decks, due-diligence packets, scientific figures, and technical drawings, etc. For text-dominated corpora, a text pipeline is most likely cheaper and sufficiently performant.

For further optimization, you might consider using a hybrid approach, where you identify pages with charts to implement as multi-vectors and the remaining corpus as text, and then use an RRF-style approach to merge results at query time.

Conclusion​

Let's wrap up with the key takeaways:

• Charts and tables are not problems to be solved by better OCR. They are primary information that gets destroyed in extraction. If your pipeline only indexes text, valuable information from charts is already lost before you started embedding.
• Late-interaction multi-vector models let you skip extraction entirely. Render the page, embed the image, and ask questions about what the image means. The model retrieves pages by what they look like --- charts, tables, layout, and all.
• On Weaviate Cloud, ingestion is drag-and-drop. Point the Query Agent at the resulting collection, ask a question, and get an answer with proper images as citation.
• Turn the same primitive into deployable code. MultiVectors.multi2vec_weaviate(image_field="page_image") is the entire vectorizer config. The rest is rasterising pages with PyMuPDF and a small batch.add_object loop.

If you have been working around chart-heavy PDFs because the indexing pipeline made them too painful to deal with, this is worth a try. The kind of files you used to skip, because they were "mostly charts", are exactly what this approach is built for.

Spin up a Weaviate Cloud cluster, upload your PDFs, and start asking questions today.

Ready to start building?​

Check out the Quickstart tutorial, or sign up for a free Weaviate Cloud account.

Two search features reach general availability in this release: the Boost API for query-time rescoring, and Maximal Marginal Relevance (MMR) diversity selection, which works on hybrid search as well as vector search. Two more are new: 4-bit Rotational Quantization as a preview, and an experimental Search REST API. This post also covers gRPC-Web, which shipped quietly in the 1.38 line, and the HNSW snapshot rework, which cuts commit-log disk usage and speeds up startup.

Here are the release highlights!

• Boost API - General Availability
• MMR Diversity Selection - General Availability
• 4-bit Rotational Quantization (Preview)
• Search REST API (Experimental)
• gRPC-Web
• HNSW Snapshots, Automatic - General Availability
• Performance Improvements and Fixes
• Community Contributions
• Summary

Boost API - General Availability​

The Boost API, introduced as a preview in v1.38, is now generally available.

Boost is a query-time rescorer. After the primary search fetches its candidates, Weaviate scores each one against your boost conditions and re-sorts the list. Unlike a filter, it never removes anything: an object that matches nothing is demoted, not dropped. That is the difference between "only show me in-stock products" and "prefer in-stock products, but still show me the perfect match that is out of stock".

How it works​

A boost holds between one and twenty conditions, and there are four kinds:

• filter promotes results that satisfy a filter
• property_value ranks by a numeric property's value
• time_decay favors objects near a point in time
• numeric_decay favors objects near a target number

Two weights control the result. The outer weight (default 0.5) mixes the boost score into the original relevance score: (1 - weight) * primary + weight * boost. Each condition then carries its own weight (default 1.0). Make that one negative if you want the condition to demote instead of promote.

A third setting, depth (default 100, capped by QUERY_MAXIMUM_RESULTS), is how many candidates the primary search fetches before the re-sort. An operator can move that default for the whole cluster with QUERY_BOOST_DEFAULT_DEPTH.

Here is what that does to a real result page. The same query runs twice over a small product catalog: once plain, once with a boost that prefers products that are in stock and recently released:

from datetime import timedelta
from weaviate.classes.query import Boost, Filter

prefer_in_stock_and_recent = Boost.blend(
    [
        Boost.filter(Filter.by_property("in_stock").equal(True), weight=2.0),
        Boost.time_decay("released", scale=timedelta(days=30)),
    ],
    weight=0.3,   # 30% boost, 70% original relevance
    depth=200,    # re-score the top 200 candidates
)

for label, boost in (("plain hybrid", None), ("with boost", prefer_in_stock_and_recent)):
    response = collection.query.hybrid(query="wireless headphones", limit=4, boost=boost)
    print(label)
    for obj in response.objects:
        print("  ", obj.properties["title"], "| in stock:", obj.properties["in_stock"])

plain hybrid
   Kestrel Wireless Headphones | in stock: True
   Meridian Wireless Headphones | in stock: False
   Aurora Wireless Headphones | in stock: False
   Nimbus Wireless Headphones | in stock: True
with boost
   Kestrel Wireless Headphones | in stock: True
   Nimbus Wireless Headphones | in stock: True
   Wireless Earbuds Pro | in stock: True
   Meridian Wireless Headphones | in stock: False

Nimbus is in stock and twelve days old, so it climbs from fourth to second. The earbuds take third for the same reason, even though the text match is weaker. The two out-of-stock listings lose ground: Meridian slides to fourth, and Aurora drops off the page. Neither one was removed from the result set. Kestrel, the best keyword and vector match, still holds first place. A weight of 0.3 leaves 70% of the score with the search itself. Raise it toward 1.0 and stock and freshness take over the ordering. Lower it toward 0.0 and you get the plain result back.

Boost is available on hybrid, bm25, near_text, near_vector, near_object, near_media, and near_image, in both the .query.* and .generate.* namespaces. It is not available on fetch_objects, which has no relevance score to blend with.

MMR Diversity Selection - General Availability​

MMR diversity selection, a preview since v1.37, is now generally available. It works on hybrid search alongside every near_* search. Hybrid support is not new in v1.39: it landed in v1.38.6, so if you are on a recent 1.38 patch you already have it. What v1.39 changes is the maturity label.

MMR picks results one at a time. At each step it weighs two things: how well a candidate matches the query, and how different it is from the results already picked. You end up with a first page that covers the topic instead of showing the same passage nine times. That helps most in hybrid search. The keyword half and the vector half of a hybrid query tend to agree on the same cluster of near-identical chunks, so their merged top 10 is often the most repetitive list in your system.

How it works​

MMR runs near the end of the query pipeline, after the two halves are merged and before the page is cut. A reranker, if you use one, runs after MMR:

Two values configure it, and both are easy to get backwards.

balance trades relevance against diversity. It takes a value from 0.0 to 1.0, and anything outside that range is rejected with MMR balance must be between 0 and 1. At 1.0 you get pure relevance, which is the same order you would get without MMR. At 0.0 you get pure diversity. So lower means more diverse. The default is 0.0, not 0.5. Leave balance out and you get the most aggressive setting there is, so always pass it explicitly.

limit on the MMR selection is your page size, the number of results you get back. MMR picks those results out of a candidate pool, and the pool is the query's own limit. The MMR limit must be at least 1 and no larger than the query limit.

Here is the same query at three settings. The collection holds documentation chunks, and four of them say roughly the same thing about carbon pricing:

from weaviate.classes.query import Diversity

for balance in (1.0, 0.3, 0.0):
    response = collection.query.hybrid(
        query="carbon pricing",
        limit=8,                                                      # candidate pool
        diversity_selection=Diversity.mmr(limit=4, balance=balance),  # 4 returned
    )
    print(f"balance={balance}")
    for obj in response.objects:
        print("  ", obj.properties["title"])

balance=1.0
   Carbon tax versus cap and trade
   Carbon pricing basics
   Carbon pricing FAQ
   What is a carbon price?
balance=0.3
   Carbon tax versus cap and trade
   Carbon pricing FAQ
   Carbon pricing basics
   Adaptation funding for coastal cities
balance=0.0
   Carbon tax versus cap and trade
   Methane rules for oil and gas
   Adaptation funding for coastal cities
   Renewable subsidies and grid buildout

At 1.0 the page is four ways of saying the same thing, which is the page you get without MMR. At 0.3 one of the duplicates gives up its slot to a chunk on adaptation funding. At 0.0 relevance stops counting after the first pick, and a carbon-pricing query comes back with methane rules and grid buildout. That last one is what you get if you leave balance out.

You need Python client 4.23.0 or newer. That is the release where diversity_selection arrives on collection.query.hybrid and collection.generate.hybrid. MMR is not available on bm25, which has no vectors to measure distance between, and it does not work on multi-vector collections.

4-bit Rotational Quantization (Preview)​

Rotational quantization (RQ) shrinks vectors in two steps. First it rotates the vector so the values spread evenly across the dimensions. Then it stores each dimension as a small integer code instead of a 32-bit float. Weaviate already ships 8-bit and 1-bit RQ. v1.39 adds a 4-bit width as a preview.

Four bits is half a byte, so two dimensions pack into one byte. At 1536 dimensions that is a 16-byte header plus 768 bytes of codes: 784 bytes per vector, against 6144 bytes for raw float32. That is 7.84x smaller, not a round "8x", because the header stays.

The general form is 16 + ceil(outputDim / 2) bytes, where outputDim = 64 * ceil(inputDim / 64). The rotation rounds your dimension count up to the next multiple of 64. At 1536 that round-up is free, because 1536 is 24 x 64. At 1000 dimensions it is not: you pay for 1024.

How it works​

There is no preview flag to unlock. It is a plain schema value, rq.bits = 4, on a vector index:

from weaviate.classes.config import Configure

client.collections.create(
    "Doc",
    vector_config=Configure.Vectors.text2vec_weaviate(
        name="default",
        source_properties=["title", "body"],
        vector_index_config=Configure.VectorIndex.hnsw(
            quantizer=Configure.VectorIndex.Quantizer.rq(
                bits=4,
                rescore_limit=20,
            ),
        ),
    ),
)

bits is fixed the moment RQ is first enabled on a vector, and you cannot change it later. There is no migration from 8-bit codes to 4-bit codes, so pick the width when you create the collection.

If you would rather not set it per collection, an operator can make it the cluster-wide default for new vector indexes with DEFAULT_QUANTIZATION=rq-4. A new HNSW index then comes up with bits: 4 and a rescoreLimit of 20. Flat indexes are left alone.

Like the other RQ widths, 4-bit works with the cosine, dot, and l2-squared distance metrics.

Search REST API (Experimental)​

Weaviate has two search APIs today. gRPC is fast, but it wants a generated client and HTTP/2. GraphQL means building a query string by hand and digging metadata out of _additional. Neither is pleasant from a shell script, a Lambda, an edge worker, an API gateway, or a language with no Weaviate client.

v1.39 adds an experimental Search REST API. You post JSON over plain HTTP/1.1 and get JSON back, and the endpoints are described by the OpenAPI spec like the rest of the REST API. That also suits LLM tool calling, where a model needs a documented HTTP endpoint rather than a client library.

v1.39.0 shipped one endpoint, POST /v1/search/{collection}/near-text. The v1.39.1 patch added three more search endpoints and a matching aggregate endpoint, so on 1.39.1 or newer you get all five:

• POST /v1/search/{collection}/near-text
• POST /v1/search/{collection}/bm25
• POST /v1/search/{collection}/hybrid
• POST /v1/search/{collection}/near-object
• POST /v1/aggregate/{collection}

The examples below use near-text.

How it works​

The endpoints are off by default. Turn them on per node with EXPERIMENTAL_REST_SEARCH_ENABLED:

services:
  weaviate:
    image: cr.weaviate.io/semitechnologies/weaviate:1.39.1
    environment:
      EXPERIMENTAL_REST_SEARCH_ENABLED: 'true'

Accepted truthy values are on, enabled, 1, and true. One switch covers every endpoint in the set. When the feature is off, the routes are still there. They answer 422 with a message naming the variable to set, instead of a confusing 404.

The request body is all camelCase. For near-text, query is a required array of strings, and each string is a piece of text to search for. Send one string for an ordinary search. Send several and Weaviate averages them into a single search vector. You can also send certainty or distance (not both), targetVector, where, limit, offset, autoLimit, returnProperties, returnMetadata, tenant, and consistencyLevel.

curl -s -X POST http://localhost:8080/v1/search/Movie/near-text \
  -H 'Content-Type: application/json' \
  -d '{"query":["spaceship galaxy"],"limit":3,
       "returnProperties":["title","hasAuthor.name"],
       "returnMetadata":["distance"]}'

The response is {results, tookMs}. Every hit comes back in the same flat shape, {id, properties, references, metadata}:

{
  "results": [
    {
      "id": "2aeb3309-33e7-4a8d-a8e2-6413b53890d8",
      "properties": { "title": "spaceship galaxy adventure" },
      "references": { "hasAuthor": [ { "name": "famous writer" } ] },
      "metadata": { "distance": 0.07182336 }
    }
  ],
  "tookMs": 2
}

references is left out when your query does not read across a reference, and metadata is left out when you asked for nothing beyond the id. Vectors are never returned.

On errors you get the standard {"error": [{"message": "..."}]} body.

No official client wraps this endpoint yet. Every Weaviate client speaks gRPC for search, so curl or raw HTTP is how you reach it for now. Boost, MMR, reranking, generative search, and group-by are not available over REST.

gRPC-Web​

Browsers cannot speak plain gRPC, so front-end code has never been able to call Weaviate's gRPC API directly. gRPC-Web closes that gap by serving the same API over ordinary HTTP. It arrived in v1.38.3 and has not been covered in a release post until now.

The interface lives under the /v1/grpc-web/ path prefix on the same port as the REST API (default 8080). It is not on the gRPC port and not on a port of its own, so there is no second port to open in a firewall or an ingress rule.

It is enabled by default. To turn it off, set the runtime-configuration key grpc_web_enabled to false. The key is snake_case, and it has no environment-variable equivalent. The change takes effect without a restart. While the interface is off, a request to a /v1/grpc-web/ path comes back as a plain 404, the same as any other path Weaviate does not serve. The rest of the REST API is unaffected.

One caveat: the Weaviate client libraries all connect over plain gRPC today, so none of them uses this interface yet.

HNSW Snapshots, Automatic - General Availability​

An HNSW index is rebuilt on startup by replaying its commit log, the append-only write-ahead log that records every change to the graph. A snapshot is a compacted image of that graph, so startup can load one file instead of replaying millions of records. Until now the snapshot was an optional cache: you scheduled it with a handful of environment variables, and the log it summarized stayed on disk forever. You paid for the same graph twice.

In v1.39 snapshots are automatic and generally available. Weaviate writes and refreshes them in the background, and once a new snapshot is safely on disk it deletes every commit log that snapshot covers. What you get:

• Less disk. You keep the snapshot plus the writes made since it, instead of the snapshot plus the full history. On vector-heavy clusters that is most of the win.
• Faster, steadier startup. Loading a snapshot takes about the same time on every restart. Replaying a log that only ever grows does not.
• Nothing to tune. There are no snapshot environment variables and no schedule to set. Weaviate decides when to write the next one.

Two things to know about the disk savings. The cleanup only runs on shards that are loaded, so an inactive tenant keeps its old files until the next time you use it. And disk usage goes up for a while during a snapshot, because Weaviate writes the new file before it deletes the old ones. Keep the headroom you have today.

Five settings that used to control snapshotting are now ignored. Weaviate still accepts them, and they will be removed in a future version:

PERSISTENCE_HNSW_DISABLE_SNAPSHOTS
PERSISTENCE_HNSW_SNAPSHOT_INTERVAL_SECONDS
PERSISTENCE_HNSW_SNAPSHOT_ON_STARTUP
PERSISTENCE_HNSW_SNAPSHOT_MIN_DELTA_COMMITLOGS_NUMBER
PERSISTENCE_HNSW_SNAPSHOT_MIN_DELTA_COMMITLOGS_SIZE_PERCENTAGE

Setting any of them logs a one-line warning at startup instead of failing, so an upgrade will not break on a stale config file. Delete them when it suits you. One HNSW persistence setting survives: PERSISTENCE_HNSW_MAX_LOG_SIZE (default 500MiB). It sets the write-ahead-log rotation size, not anything about snapshots, and it still applies.

Performance Improvements and Fixes​

Beyond the headline features, v1.39 ships a long list of improvements. A few worth calling out:

• Faster keyword search: bm25 queries, and the keyword half of hybrid, come back sooner after a round of work on the scoring path.
• Cross-property keyword AND: a new AndCross search operator asks for every query term to appear somewhere on the object, rather than all of them inside one property. It shipped in the 1.38 line, and it is opt-in, so plain And keeps the behavior you have today.
• Cheaper async replication: background repair does less redundant work on clusters with many tenants. Fixes stop deleted objects from coming back during a first scan, stop a repair from overwriting a newer local write, and stop a tenant shutdown from leaking memory.
• Leaner HFresh: the HFresh vector index uses less memory and writes to disk less often.
• More reliable backups: listing a backup on Azure no longer scans every object, a restore no longer forces lazy-loaded shards to load, and you can now set how many files an incremental backup deduplicates.
• Safer replica movement: moving a replica between nodes now uses hard links, so it no longer pauses compaction. Schema changes that would clash with a move in flight are rejected, and two copy operations on the same shard no longer trip over each other.
• Latency metrics below a millisecond: the HTTP and gRPC request-duration histograms now have buckets down to 100µs, so fast queries no longer all land in one bucket.
• Batch delete returns 422: a batch delete with missing match fields now answers 422 Unprocessable Entity instead of 500.

Community Contributions​

Weaviate is open source, and this release includes work from five first-time contributors. Thank you to:

• @hashkanna: location configuration for the text2vec-google module (#8418)
• @vjsai: rejecting a negative desiredCount in sharding configuration (#11824)
• @Joe-Weaviate: using automaxprocs to set GOMAXPROCS, adding cgroup v2 support (#11918)
• @VihaanAgarwal: a fix to the object write path on collections with named vectors (#11919)
• @apoorva-01: returning 422 for a batch delete with missing match fields (#12049)

If you'd like to contribute, check out the contributor guide and the good-first-issue label on GitHub.

Summary​

Weaviate v1.39 promotes two search features to general availability, previews a third, and makes HNSW snapshots automatic.

Key highlights:

• Boost API (GA): query-time rescoring that promotes or demotes results without dropping any, across hybrid, keyword, and vector searches
• MMR Diversity Selection (GA): diversity selection on hybrid and near_* searches, so page one covers the topic instead of repeating it
• 4-bit Rotational Quantization (Preview): a third RQ width at 784 bytes per 1536-dimension vector, 7.84x smaller than raw float32, on HNSW indexes
• Search REST API (Experimental): JSON over plain HTTP/1.1, off by default. near-text in v1.39.0, plus bm25, hybrid, near-object, and an aggregate endpoint in v1.39.1
• gRPC-Web: the gRPC API reachable from a browser over ordinary HTTP, on the REST port, enabled by default since v1.38.3
• HNSW Snapshots, Automatic (GA): less disk spent on commit logs, faster and steadier startup, five tuning knobs retired, and nothing left to schedule

Ready to get started?

The release is available open-source on GitHub and on Weaviate Cloud, where you can spin up a cluster on the free tier.

If you are upgrading a self-hosted cluster, check the migration guide for version-specific notes.

Thanks for reading, and happy vector searching!

Ready to start building?​

Check out the Quickstart tutorial, or sign up for a free Weaviate Cloud account.

Building Foundry
A practical series on creative workflows, semantic search, and Weaviate.

Read the previous post in the series: Part 1: AI isn't replacing creativity, it's removing friction.

Most creative teams already know they are losing time to search. What is less obvious is where the breakdown actually happens. It usually doesn’t begin with bad tools or careless teams. Instead, as projects scale, naming conventions drift, metadata quality drops, and the cost of keeping everything perfectly organized becomes higher than the cost of living with a little chaos. For a while, that tradeoff feels reasonable. Then retrieval starts to fail, and no one can find anything anymore.

The first failure: folders​

Folder trees work best when projects are small, ownership is stable, and everyone agrees on the same mental model. Creative production rarely stays in that state for long.

In game development, one environment team might organize assets by biome, another by sprint, and another by engine-ready status. All three structures make sense locally. Across a two-year production, they become incompatible maps of the same work. In film production, footage often starts organized by shoot day, then gets reorganized by sequence in editorial, while VFX and color keep their own derivative structures. In design teams, client work, exploration files, and final exports often live in separate systems with weak links between them.

Folders still matter, but over time they describe where a file landed, not what that file is useful for.

The second failure: tags​

Tagging is usually proposed as the cure for messy folders, and in controlled environments it can work well. The challenge is that consistent tagging is a process discipline, and process discipline is fragile under deadline pressure.

Animation teams shipping sequences on tight schedules do not stop to apply perfect descriptive tags to every versioned scene file. Music producers bouncing between sessions do not pause to classify each stem with reusable semantic labels. Designers preparing campaign variants for multiple channels rarely annotate every intermediate exploration with future retrieval in mind.

None of this reflects poor craft. It reflects incentives. Teams optimize for shipping what is needed now, not for a hypothetical retrieval request six months later. As a result, tag quality tends to be uneven: high for formal deliverables, sparse for working files, and inconsistent across individuals.

The third failure: keyword search​

Keyword search is excellent when the query and the stored text use the same words. But creative work is full of vocabulary mismatch. A film editor might search for "quiet emotional close-up" while a clip is described internally as "CU actor B reaction alt take." A game artist may search "wet brutalist corridor" while files are named around level IDs and sprint numbers. A graphic designer searching for "playful geometric logo options" may be looking for a file titled final_FINAL_logo_v7, because the client came back half a dozen times with edits.

Creative work is messy, and file names rarely contain the descriptions we need to find them again.

These failures compound over time​

Any one of these issues is manageable. Together, they create a compounding effect.

A project starts with a clean structure. Team members rotate. Vendors contribute assets using different conventions. Naming drift increases. Tagging discipline varies by deadline and role. Archive volume grows. Eventually the team has not one system but several partially overlapping systems. At that point, finding material becomes less about search and more about social memory: asking the person who might remember.

That approach does not scale. It also creates uneven access to institutional knowledge. Senior contributors become implicit search engines, and new team members spend longer rebuilding context that already exists in files they cannot easily discover.

What retrieval needs to do differently​

If we treat this as a retrieval problem rather than an organization problem, requirements change.

Retrieval has to work when naming is imperfect. It has to work when tags are incomplete. It has to work when the user can describe intent clearly but cannot reproduce the original wording used at creation time. It also has to preserve precision when exact constraints matter, such as project, date range, rights status, delivery format, or asset type.

That is why modern systems combine multiple signals:

• semantic similarity for meaning
• keyword matching for exact terms
• metadata filters for hard constraints

This can be built using a two-phase path: ingestion first, retrieval second.

Ingestion is where assets are prepared for future search. Files are processed, embeddings are generated, and available metadata is attached. In creative pipelines, this can include project identifiers, file types, timestamps, contributor roles, rights or licensing fields, and any production-specific attributes you already track. The goal is to capture enough structure and enough semantic representation that future queries have multiple routes to the right result.

Retrieval is where those routes are combined. A user might search in natural language, then refine with metadata filters, then rely on hybrid ranking that blends semantic and keyword scores. Vector databases can store embeddings with metadata at scale, which means semantic and filtered search can run in one coherent flow.

Using Weaviate as an implementation example, we can ingest assets with embeddings and metadata, query with vector and keyword signals, then apply metadata constraints for production-safe results.

What’s next​

Creative workflows do not break because teams are disorganized. They break because production systems are optimized for shipping, while media retrieval systems are often optimized for ideal data hygiene that real projects cannot maintain.

Building a vector-based retrieval system is the practical direction for teams that want less time lost to searching and less creative work stranded in archives.

In the next post, we’ll begin that implementation with the foundation: data ingestion. A read-only discovery pass will scan a messy creative archive and turn it into a structured manifest ready for metadata enrichment and vector embeddings. From there, we can ingest those records into Weaviate and add hybrid queries and metadata filtering.

Ready to start building?​

Check out the Quickstart tutorial, or sign up for a free Weaviate Cloud account.

Scaling test-time compute has become one of the clearest successes of the foundation model era. Spend more compute on a problem at inference, get a better result. Retrieval is no exception. The new effort parameter in the Query Agent’s Search Mode now lets you control this. On BRIGHT Biology, one of the hardest reasoning-intensive retrieval benchmarks, ultrahigh effort Search Mode lifts nDCG@10 to 57.5 compared to 13.0 with Hybrid Search alone.

Different applications sit at different points on the accuracy / latency tradeoff curve. Available in weaviate-agents 1.8.0 and agents-typescript-client 1.7.0, effort lets you choose per request how much work the Query Agent invests in each search.

from weaviate.agents.query import QueryAgent

qa = QueryAgent(
  client=client,
  collections=["IRPAPERS"]
)

response = qa.search(
  "What are Listwise Rerankers?",
  effort="ultrahigh"
)

import { QueryAgent } from "weaviate-agents";

const qa = new QueryAgent(client, {
  collections: ["IRPAPERS"],
});

const response = await qa.search("What are Setwise Rerankers?", {
  effort: "ultrahigh",
});

Search Mode’s three effort tiers: medium, high, and ultrahigh scale computation at the two stages where Search Mode does its work: query writing and reranking. At higher effort, the agent thinks longer about how to decompose queries and reranks results more thoroughly. At lower effort, it trades some of that depth for speed and cost. Turn it up when the answer matters, and turn it down when latency does!

Benchmarks​

The following table compares our medium, high, and ultrahigh effort tiers in Search Mode against Weaviate’s Hybrid Search across 8 benchmarks: 5 subsets from BRIGHT, IRPAPERS, WixQA, and a subset from OBLIQ-Bench. We chose these benchmarks because they illustrate reasoning-intensive and domain-specific retrieval problems.

Methodology​

As in our first Search Mode Benchmarking blog, we compare against Weaviate's Hybrid Search, combining BM25 with vector search over Snowflake Arctic 2.0 embeddings, fused with Reciprocal Rank Fusion (RRF). We then run Search Mode at each of the three effort tiers on the same collections. To account for the stochasticity of the models used in Search Mode, every Search Mode configuration is run for 3 trials, and we report the mean and standard deviation across trials. Hybrid Search is nearly deterministic given a fixed collection, so we report a single run.

Metrics Glossary​

• Gold Document: In IR benchmarks, the "gold document" is the labeled relevant document, or documents, for a given query.
• Success@K: Measures whether or not the K retrieved documents are gold documents. We typically report Success when setting K = 1 to account for multiple gold documents per query.
• Recall@K: Measures how many of the gold documents are in the top K results.
• nDCG@K: Short for normalized Discounted Cumulative Gain, nDCG considers not only whether relevant documents are retrieved, but also how they are ordered. Its strength lies in capturing graded relevance rather than binary relevance, and rewarding systems that place the best results higher in the list.

For all metrics, higher values indicate better performance. Each metric emphasizes a different aspect of information retrieval, and together they provide a fuller picture.

Benchmarks Glossary​

• BRIGHT: Featured in ICLR 2025, BRIGHT tests reasoning-intensive retrieval with long, descriptive queries sampled from StackExchange posts. The gold documents are web pages cited in accepted or highly upvoted answers. We use 5 subsets: Biology, Earth Science, Economics, Psychology, and Robotics.
• IRPAPERS: Our benchmark of Information Retrieval papers, published at the start of 2026 to study domain-specific retrieval and compare text- and image-based systems. We report results on the text transcriptions.
• WixQA: Released by the Wix.com AI Research team in May 2025, WixQA tests domain-specific technical support retrieval with 200 expert-written customer queries, each paired with gold documents authored by Wix support specialists.
• OBLIQ-Bench: Introduced by MIT researchers in May 2026, OBLIQ-Bench targets queries where relevance is latent, or oblique, rather than stated in the document's surface text. We use the Congress Hearings subset with 254 tip-of-the-tongue queries over 213,650 congressional hearing passages.

Across all eight benchmarks, the pattern is consistent: every effort tier of Search Mode outperforms Hybrid Search, and higher effort delivers higher accuracy on average. The size of the gap between tiers depends on the problem. On BRIGHT, where queries demand multi-step reasoning, the tiers separate sharply. Ultrahigh effort lifts nDCG@10 from 13.0 to 57.5 on Biology and from 22.2 to 54.4 on Psychology, with each step up in effort buying meaningful additional accuracy. On domain-specific, but less reasoning-intensive benchmarks like IRPAPERS and WixQA, the gap shrinks. Here medium effort already captures most of the gain over Hybrid Search, and higher tiers add smaller increments on top.

Because Search Mode’s inference pipeline is stochastic, adjacent tiers can overlap on individual datasets. For example, on BRIGHT Economics, medium effort edges out high. Averaged across benchmarks and trials, the ordering holds and higher effort consistently delivers higher accuracy. Standard deviations are computed across three trials per system, and the consistency across runs gives us confidence these gains are robust rather than artifacts of a single sample.

BRIGHT​

The BRIGHT subsets reward effort differently. On Biology and Psychology, each step up in effort buys a meaningful gain, with ultrahigh effort roughly quadrupling Hybrid Search's nDCG@10 on Biology. Earth Science tells a different story, where medium effort already triples the Hybrid Search baseline and the higher tiers add smaller refinements on top. Robotics is the most striking case where medium and high effort improve on Hybrid Search only modestly, but ultrahigh effort jumps well past both, lifting Success@1 from 25.7 at medium to 45.9 at high. Robotics also has by far the longest queries of the five subsets, averaging 819 tokens, which suggests the hardest queries are exactly where the extra computation pays off most.

IRPAPERS​

Compared to BRIGHT, the effort tiers sit much closer together on IRPAPERS. Medium effort already captures most of the gain over Hybrid Search, with high and ultrahigh adding only a couple of points on top.

WixQA​

The pattern from IRPAPERS repeats here. Every Search Mode effort tier clears Hybrid Search by a wide margin, while the gaps between effort tiers stay small. In practical terms, even at medium effort, Search Mode returns the document a Wix support specialist would hand you at rank 1 for about two out of three customer questions, compared to two out of five with Hybrid Search. On benchmarks like these, where queries are shorter and demand less multi-step reasoning than BRIGHT, medium effort seems to capture most of the available gain. For latency-sensitive applications or to save cost, it may be worth testing whether the cheapest tier is already enough.

OBLIQ-Bench​

These are the lowest absolute scores in this analysis. Hybrid Search essentially hits the floor, surfacing the gold passage in its top 20 results for fewer than 1 in 12 queries. Search Mode changes the picture substantially. Ultrahigh effort reaches 24.4 Success@1, roughly a 7x improvement over Hybrid Search, and this is the one benchmark where the tiers stay cleanly separated on every metric. Each step up in effort buys a real gain, reinforcing the pattern from BRIGHT that the hardest problems reward the most computation.

What is Search Mode?​

The Query Agent is Weaviate’s agentic interface to your data. Instead of writing search queries, filters, and aggregations by hand, you describe what you want in natural language and the Query Agent figures out how to get it from your Weaviate collections. It comes in three modes: Ask Mode, which answers questions with generated responses grounded in your data, Search Mode, which returns the documents themselves, and Suggest Queries Mode, which proposes queries to help users explore what their collections can answer.

Search Mode is a drop-in upgrade for any pipeline that expects ranked search results and can tolerate additional latency, whether that’s a RAG system, an agentic workflow, or even a search bar.

The benchmarks so far have tested how well Search Mode finds relevant documents, but it can do more. Because the Query Agent understands your collection schemas, it can translate natural language into structured queries. For example, given a query such as, "Find me some vintage shoes under $70", Search Mode recognizes "under $70" as a structured filter. It applies a hard constraint on the price property, and searches for vintage shoes among the results that qualify. This lets you combine semantic meaning and structured constraints with one system.

Conclusion​

Our benchmarks show what higher effort in Search Mode buys: consistent accuracy gains that grow with the difficulty of the retrieval problem. Additional effort trades latency and cost for that quality. If your application depends on surfacing the right result, such as agentic workflows, deep research, or high-stakes question answering, we recommend experimenting with the new effort tiers. If you are latency-sensitive, medium effort Search Mode or Weaviate's Hybrid Search remains a great fit.

All results can be found or reproduced with our open-source query-agent-benchmarking tool. This tool supports 22 benchmarks in total, further including benchmarks such as BEIR, LoTTe, EnronQA, and FreshStack if you would like to extend these comparisons. The tool further supports running the effort sweep comparison on your own search evals stored in Weaviate.

Thank you for reading!

Ready to start building?​

Check out the Quickstart tutorial, or sign up for a free Weaviate Cloud account.

File names like final_final_v7.png, USE_THIS_ONE.mov or new_character_export.psd are oddly universal. They appear in game studios, post-production houses, animation pipelines, and design agencies working across every kind of project. The specific conventions vary, but the underlying situation does not: creative work accumulates faster than anyone can organise it, and finding something you made six months ago is often harder than making it again from scratch.

You don’t need better naming conventions or a different design tool to solve this. It’s a retrieval problem, and it’s one that most creative tools have never been designed to solve.

The problem isn’t creativity​

The persistent question in conversations about AI and creative work is whether AI can generate something: a painting, a screenplay, or a piece of music. But the more immediate and practical story is far less dramatic.

Consider how a game production pipeline actually works. A concept artist produces dozens of character sketches before one direction gets approved. The rejected explorations go into a folder named something like “alt_directions_v2”, and within three months nobody can reliably locate the version that sparked the final design. Then, on a sequel or expansion, someone needs that exact colour palette and aesthetic direction. Because searching for “dark armour character concepts 2023” turns up nothing useful, they start from scratch rather than building on what already exists.

The same problem looks different depending on the discipline. A film editor searching for specific B-roll scrolls through bins labelled by card number and shoot date, because nobody had time to write shot descriptions during production. An animator looking for a reference of a particular run cycle digs through folders three levels deep before giving up. A graphic designer trying to find an earlier logo exploration for a returning client reconstructs it from memory. A music producer hunting for a drum texture they used two years ago opens session after session, listening through stems, until they find it or settle for something new.

Searching for previous work, redesigning things that have already been done, and trying to stay organized in a sea of ever-growing media all take away from the creative work that actually matters.

Where time actually goes​

In most creative workflows, the actual moment of making something occupies a surprisingly small fraction of total project time. Pre-production and post-production dwarf the production itself. Research, reference gathering, asset organisation, version tracking, and the constant process of locating what already exists all compete for hours that would otherwise go toward the work.

Consider a scenario common in animation production: a rigging team needs to check how a particular character’s shoulder topology was handled in a previous project. There is no organised asset library, just a shared drive arranged by project name and date. The rig file is in there somewhere, but finding it requires either knowing exactly where to look or asking someone who does. If the person who built the original rig has since moved to a different studio, that knowledge leaves with them.

This is partly a documentation problem, but the right naming and organization only gets a team so far. The work exists. The information exists. But the inability to retrieve it efficiently is costing the team time, consistency, and sometimes money when they unknowingly reproduce work that already exists.

Traditional search compounds the problem rather than solving it. Keyword search requires you to guess which words were used when something was named or described, often by someone else, often months or years earlier. Searching for “blue environmental concept” returns nothing if the file is called ENV_ALTSTYLING_DARK_V4.

Weaviate is designed to handle this type of retrieval, storing semantic representations alongside traditional metadata so creative assets can be searched by both meaning and structured filters.

AI as a workflow layer​

The most useful aspect of AI for creative fields isn’t as a generator of new work, but as the infrastructure layer that makes existing work more accessible.

This is where a class of technology called semantic search becomes genuinely relevant to creative workflows. To build this infrastructure layer, we can use semantic search to organize and retrieve documents based on meaning, not just by matching exact terms or phrases.

This works by using machine learning to change the original media into vector embeddings. A machine learning model processes a piece of content, whether that content is text, an image, or an audio file, and converts it into a long list of numbers that represents what the content means or depicts. Two things that mean a similar thing, even if described very differently, produce number sequences that sit close together in the resulting high-dimensional vector space. For example, a query for “dark forest with blue atmospheric haze” and an image of a misty pine forest at dusk will produce embeddings that cluster near each other in this space, even though neither the query nor the image share any matching text.

Vector search is the process of finding items whose embeddings are closest to a given query. That proximity is what enables retrieval by meaning rather than by keyword.

A simple example​

A game studio building an open-world RPG might accumulate tens of thousands of concept images over a multi-year production. Team composition changes, folder structures evolve, and naming conventions that were carefully maintained in year one have become considerably more creative by year three.

A designer joining the team near launch needs reference for a cold, forested biome that should feel visually distinct from the game’s existing environments. Searching for “cold forest biome” returns nothing useful from a keyword search because those files were named when nobody anticipated that particular query. A semantic search system, given the same natural-language description, can match against visual embeddings of the images themselves, automatically generated descriptions created during indexing, or a combination of both.

Before search becomes possible, content needs to be processed and stored in a way that supports semantic retrieval. This is the ingestion step: running files through a pipeline that generates an embedding for each item and stores that embedding alongside the original content and its metadata.

Metadata remains important even in a semantic search system. We still need to keep that information to know that our result belongs to the correct project, was created within the past two years, and is the right file type. So, in addition to our original media and our generated vector embeddings, it’s important that we store the file’s metadata as well.

A vector database holds all of this together. Unlike a traditional relational database designed for exact lookups, a vector database stores embeddings alongside the original data and metadata, with its internal architecture optimised for fast semantic retrieval. When you run a query, the database converts it into an embedding and returns the items whose embeddings are most similar. The result is search that appears to understand what you are actually looking for, not just what you typed. You can try the semantic search playground to see the difference between keyword, vector, and hybrid results on the same query.

This is just the start​

None of what has been described here is beyond current technology. Semantic search and vector databases are already used in enterprise knowledge management, legal document retrieval, and e-commerce product search for exactly these reasons. We can apply those same principles to creative asset management.

The challenge lies in the ingestion layer: deciding what gets indexed, how descriptions and embeddings are generated for different content types, and how the search interface fits into existing tools and workflows.

What’s next​

In the next post, we’ll look closely at where creative workflows actually break down, and why conventional folder structures, tagging systems, and keyword search consistently fail to keep pace with how creative teams produce work. After that, we’ll walk through a concrete implementation: a working semantic search system for creative assets built with Weaviate, step by step.

Ready to start building?​

Check out the Quickstart tutorial, or sign up for a free Weaviate Cloud account.

A query in production is slow. Maybe it was always a little slow and it finally crossed the line where someone noticed, or maybe it regressed after a data load. Either way you now have a single question, and it is the same question every time: where did the time go? Was it the filter, the vector search, the object read from disk, or the keyword scoring? Until you can split that number into its parts, every fix is a guess.

Weaviate has always been able to answer this. The trouble was getting the answer out.

How we used to find slow queries​

The existing tool is the slow query log. You turn it on with two environment variables and restart the node:

QUERY_SLOW_LOG_ENABLED=true
QUERY_SLOW_LOG_THRESHOLD=2s

Any query that runs longer than the threshold is logged at WARN with its full timing breakdown attached: the class and shard, the filters, the limit, and every internal timer the engine recorded on the way through. If you have runtime overrides already wired up, you can flip both settings live from the overrides file and skip the restart, because the server rereads them on its load interval.

For catching regressions across a whole fleet over time, this works well. It is a passive net that stays out of the way until something trips it.

Where the old approach falls short​

The slow query log is built for a different job than the one you have when a specific query is slow right now, and four things get in the way.

First, the plain enablement path needs a restart. Restarting a node to debug a latency problem changes the thing you are measuring. A fresh process starts with cold OS page caches, so the first queries after a restart read from disk where a warm node would have hit memory. You end up profiling the restart as much as the query.

Second, the settings you tune live are temporary knobs. If you raised the threshold or toggled the log through runtime overrides to catch a specific query, that change lives in the overrides file, not in the deployment manifests your cluster is actually built from. It is a state you have to remember to undo, and it drifts out of sync with how the deployment is defined.

Third, it is always after the fact. The log only reacts once a query has already crossed the threshold. You cannot point it at the query in front of you and ask for its numbers; you wait for that query, or one like it, to be slow again. On top of that the log samples about one percent of all queries at INFO regardless of speed, so a fast query can show up in the output next to the genuinely slow ones and you have to filter the noise out.

Fourth, it is per node. Each node logs the shard searches that ran on it, and nothing stitches those lines together. On a single query that fans out across a cluster, the timings you want are spread across several nodes' logs, and reassembling one query's picture is manual work.

What is query profiling?​

Query profiling is the direct answer to all four. It is a per-query, opt-in flag. You set it on one search, the server collects the timing breakdown for that search, and it returns the numbers inline on the response. There is no env var, no threshold, no restart, and nothing to reset afterward.

Under the hood it uses the same instrumentation as the slow query log, so the numbers are the same numbers, delivered differently. And it closes the per-node gap directly: the coordinating node gathers the profiles from every shard on every node that took part in the query and returns them together. One request gives you the whole cluster's view of that one query.

You enable it per query. In Python, add it to the return metadata:

from weaviate.classes.query import MetadataQuery

response = collection.query.near_vector(
    near_vector=[0.1, 0.2, 0.3],
    limit=10,
    return_metadata=MetadataQuery(query_profile=True),
)

for shard in response.query_profile.shards:
    print(shard.name, shard.node, shard.searches)

Query profiling is available in the official Python, JavaScript/TypeScript, Java (v6), and C# clients, and over gRPC directly by setting QueryProfile in the request metadata. The profile rides on the response object at response.query_profile, not on any individual result. Profiling covers vector search, keyword scoring, and filter evaluation. It does not measure generative modules, rerankers, or other post-processing.

Query profiling was introduced in v1.36.9, announced as a preview with the v1.37 release, and is generally available as of v1.38. When the flag is off, the cost is a single boolean check. When it is on, the added cost is microsecond-level timer reads. It is meant for debugging and optimization, not for your production hot paths.

Reading the numbers​

The profile is organized by shard. Each shard entry names the shard and the node that ran it, and holds a details map of metric name to value for each search type it performed. A pure vector query shows the vector timers, a BM25 query shows the keyword timers, a filtered query adds the filter timers, and a hybrid query carries both a vector and a keyword section. Only the stages that actually ran show up, so the exact set of fields depends on the query.

total_took is the wall time of the whole shard search. Everything else explains where that time went.

On the vector path, objects_took is object hydration: reading the final objects out of the on-disk objects store. A high value here means disk-bound hydration, and it usually points at page-cache misses, a large limit, or large objects. This is the clearest disk signal in the profile.

filters_build_allow_list_took is filter resolution: turning your where clause into a set of matching document IDs through the inverted index. It is driven by filter cardinality and by whether those index segments are in memory or on disk. The filters_ids_matched count sits right next to it and tells you which regime you are in. A large count means a broad filter matching many documents; a small count with a high time points more at disk reads.

vector_search_took is the vector index doing its search, and its main sub-timer is knn_search_layer_N_took, one entry per HNSW layer, with layer 0 normally dominating. This is graph traversal: exploring candidates and computing distances. It is worth being precise here, because it is easy to read a high vector time as the node running out of resources. It usually is not. The HNSW graph lives in RAM, so this timer measures compute, not a wait on disk. A high value means the traversal itself is expensive, and the levers are the ones that control traversal cost: ef, vector dimensionality, and the filter strategy on filtered searches. Tune those before you reach for more hardware.

The one vector stage that can genuinely touch disk is knn_search_rescore_took. It only appears when compression is enabled, and it reads full-precision vectors back to rescore the compressed candidates. A high value there can mean disk latency during rescore, which is a different problem from a slow traversal.

hnsw_flat_search is a boolean, not a timer. When it is true under a filter, the filter was selective enough that a brute-force scan of the matches was cheaper than walking the graph, and the engine took that path on purpose.

On the keyword path, the kwd_* family breaks BM25 down the same way. Two are worth knowing by name. kwd_3_term_time is the cost of reading the per-term posting lists out of the inverted segments, so it is sensitive to the number of query terms and to disk reads. kwd_4_bmw_time is the BlockMax WAND traversal that scores the posting blocks, so it grows with low query selectivity and long posting lists. A slow keyword query is usually one or the other, and the split tells you which.

Worked examples​

The numbers below are illustrative, but they show the shape of the output and how to read it.

A vector search where hydration dominates:

{
  "shards": [
    {
      "name": "1a2b3c4dshard",
      "node": "weaviate-0",
      "searches": {
        "vector": {
          "details": {
            "total_took": "48.2ms",
            "filters_build_allow_list_took": "2.1ms",
            "filters_ids_matched": "512",
            "vector_search_took": "8.4ms",
            "knn_search_layer_0_took": "7.9ms",
            "knn_search_rescore_took": "0.3ms",
            "hnsw_flat_search": "false",
            "objects_took": "36.8ms"
          }
        }
      }
    }
  ]
}

The filter and the vector search are cheap. objects_took is most of total_took, so the time is going into reading objects off disk. Check the page cache and storage on that node, and consider a smaller limit or a lighter payload.

A filter that matches too much:

{
  "shards": [
    {
      "name": "9f8e7d6cshard",
      "node": "weaviate-1",
      "searches": {
        "vector": {
          "details": {
            "total_took": "61.5ms",
            "filters_build_allow_list_took": "41.2ms",
            "filters_ids_matched": "12840000",
            "vector_search_took": "15.6ms",
            "knn_search_layer_0_took": "14.8ms",
            "hnsw_flat_search": "false",
            "objects_took": "3.9ms"
          }
        }
      }
    }
  ]
}

Here filters_build_allow_list_took is the largest slice, and filters_ids_matched is over ten million. The filter is broad, so building the allow-list is the cost. This is a cardinality problem, not a disk one: rethink the filter so it selects less, or apply the wide condition differently rather than as a pre-filter over the whole set.

A compressed index where rescore hits disk:

{
  "shards": [
    {
      "name": "5c4b3a2fshard",
      "node": "weaviate-0",
      "searches": {
        "vector": {
          "details": {
            "total_took": "39.7ms",
            "vector_search_took": "35.1ms",
            "knn_search_layer_0_took": "9.2ms",
            "knn_search_rescore_took": "25.4ms",
            "hnsw_flat_search": "false",
            "objects_took": "3.8ms"
          }
        }
      }
    }
  ]
}

The graph traversal at layer 0 is fine. Almost all of vector_search_took is knn_search_rescore_took, the stage that reads full-precision vectors back for the compressed candidates. That points at disk latency during rescore rather than at the graph, so the investigation moves to storage and to the compression configuration.

Summary​

Query profiling has become one of the first things our solution engineering team reaches for when a customer reports a slow query. Instead of enabling a log, waiting for the query to be slow again, and stitching node logs together, you set one flag, run the query once, and read the breakdown across the whole cluster. The guesswork about where the time went is gone, and what is left is a specific stage to fix.

If you want help reading a profile or working out what to change based on one, reach out. Our solution engineering team looks at these breakdowns with customers on a regular basis, so if you are a customer, your usual Weaviate contact or support channel is the fastest way to get us the details. If you are running the open-source project, ask in the community forum and we will help you work through it there.

To go deeper:

• Query profiling in the docs
• Slow query logging
• The Weaviate 1.37 release post

Ready to start building?​

Check out the Quickstart tutorial, or sign up for a free Weaviate Cloud account.

Two capabilities reach general availability in this release: the HFresh disk-based vector index and the built-in MCP Server. Async replication has been rebuilt to run cluster-wide from a single scheduler, and it now runs by default on every replicated collection. Two new previews join them: the Boost API for query-time rescoring and Nested Object Filtering.

Here are the release highlights!

• HFresh Vector Index - General Availability
• MCP Server - General Availability
• Async Replication, Everywhere
• Boost API (Preview)
• Nested Object Filtering (Preview)
• Performance Improvements and Fixes
• Community Contributions
• Summary

HFresh Vector Index - General Availability​

HFresh, the disk-based vector index we introduced as a technical preview in v1.36, is now generally available. It's inspired by the SPFresh algorithm: instead of keeping every vector in memory like HNSW, HFresh groups vectors into on-disk regions called postings and keeps a small in-memory HNSW index over their centroids to decide which regions to read. Memory stays low and latency stays predictable as a collection grows into the billions, which makes it a good fit for streaming workloads where data changes continuously rather than being loaded once.

How it works​

HFresh is selected per (named) vector, the same way as any other index. In v1.38 it's no longer behind a preview flag — you enable it by configuring a vector to use it:

from weaviate.classes.config import Configure, VectorDistances

client.collections.create(
    "Article",
    vector_config=Configure.Vectors.text2vec_weaviate(
        name="default",
        source_properties=["title", "body"],
        vector_index_config=Configure.VectorIndex.hfresh(
            distance_metric=VectorDistances.COSINE,
        ),
    ),
)

HFresh has RQ-1 quantization built in: postings are stored compressed on disk, and final ranking rescores against the uncompressed vectors for accuracy. It supports the cosine and l2-squared distance metrics.

Because the index rebalances incrementally — splitting oversized postings, merging undersized ones, and reassigning vectors as the boundaries shift — it keeps up with continuous updates without the periodic full rebuilds that other on-disk indexes depend on.

MCP Server - General Availability​

The built-in Model Context Protocol (MCP) server, introduced as a preview in v1.37, is now generally available. It lets LLMs, IDEs, and AI agents work with Weaviate directly — inspecting schemas, running hybrid searches, and writing objects back — with no glue code. The server is a Streamable HTTP endpoint at /v1/mcp on the same port as the REST API, authenticates with a Bearer / API-key token, and respects Weaviate's standard RBAC permissions.

The server exposes four tools:

• weaviate-collections-get-config — inspect a collection's schema and configuration
• weaviate-tenants-list — list the tenants of a multi-tenant collection
• weaviate-query-hybrid — run a hybrid (vector + keyword) search
• weaviate-objects-upsert — insert or update objects (only when write access is enabled)

How it works​

You enable the server with MCP_SERVER_ENABLED, and optionally expose its write tools with MCP_SERVER_WRITE_ACCESS_ENABLED. What's new in v1.38 is that both flags are runtime-configurable: rather than only being read at startup, Weaviate now picks up changes to them from its runtime-overrides file while the cluster is running.

# Runtime-overrides file — applied without a restart
mcp_server_enabled: true
mcp_server_write_access_enabled: true

So you can grant or revoke an agent's write access on a live cluster, with no rolling restart.

Async Replication, Everywhere​

Async replication is the background repair process that keeps replicas in sync on collections with a replication factor greater than 1. In v1.38 it has been re-architected to run cluster-wide from a single scheduler, rather than being configured and run separately per collection. It also now runs by default on every RF > 1 collection, where previously it was opt-in per collection.

How it works​

One scheduler coordinates async repair across all replicated collections, drawing from a single shared worker pool instead of a separate pool per collection. That makes repair behavior consistent across the cluster and simpler to operate at scale.

With the move to a central scheduler, the per-collection maxWorkers and enabled settings are gone. Two cluster-level controls replace them:

# Size of the shared async-replication worker pool
ASYNC_REPLICATION_SCHEDULER_WORKERS: '<n>'
# Kill-switch — pause all async replication, no restart needed
ASYNC_REPLICATION_DISABLED: 'false'

ASYNC_REPLICATION_SCHEDULER_WORKERS sizes the shared pool, and ASYNC_REPLICATION_DISABLED is a cluster-wide kill-switch you can flip at runtime.

Boost API (Preview)​

Sometimes you want to nudge results without removing any. A filter is too blunt for that — it drops everything that doesn't match — when what you really want is to rank fresh articles a little higher, or favor in-stock products, while keeping the full result set. The new Boost API does exactly that.

How it works​

Boost runs after the primary search. It re-scores the candidates by blending their original score with one or more boost conditions, then re-sorts them — promoting or demoting results without dropping any. Conditions can be based on:

• Filter matches — promote results that satisfy a filter
• Property values — rank by a numeric property's value
• Time decay — favor more recent (or near-a-date) objects
• Numeric decay — favor objects closer to a target number

In the Python client (v4.22.0+), you build a boost and pass it to any query via boost=:

from weaviate.classes.query import Boost, Filter

# Softly promote in-stock products without dropping the rest
response = collection.query.hybrid(
    query="wireless headphones",
    limit=10,
    boost=Boost.filter(
        Filter.by_property("in_stock").equal(True),
        weight=0.3,
    ),
)

The weight (0–1) sets how much the boost shifts the final score: the result is (1 - weight) of the original score plus weight of the boost score. Boost is gRPC-only — there's no REST or GraphQL equivalent — and a single query can apply at most 20 conditions.

Nested Object Filtering (Preview)​

Weaviate v1.38 adds a preview for filtering on nested object properties. Until now, object and object[] properties were stored but couldn't be filtered on directly.

How it works​

You filter on a nested field by referencing it with a dotted path — for example, cars.make to filter on the make field inside a cars object property. The feature is off by default and gated behind a preview environment variable:

WEAVIATE_PREVIEW_NESTED_FILTERING: 'true'

Once enabled, the dotted path goes wherever you'd normally supply a property name, including from the clients:

from weaviate.classes.query import Filter

response = collection.query.fetch_objects(
    filters=Filter.by_property("cars.make").equal("Toyota"),
)

This works for data nested inside both object and object[] properties.

Performance Improvements and Fixes​

Beyond the headline features, v1.38 ships a long list of improvements. A few worth calling out:

• Production-ready replica movement: Moving a shard's replicas between nodes — for rebalancing and scaling — graduates to production-ready, backed by a change-capture log that keeps writes flowing during the move.
• Default vector index type: A new cluster-level setting picks the default vector index for new collections (including named vectors), instead of always defaulting to HNSW.
• Usage guardrails: Operators can set server-side limits on the number of objects, collections, tenants, and shards, plus allow-lists for vector-index and compression types.
• New module — text2vec-digitalocean: Generate embeddings through DigitalOcean's inference platform.
• Backup reliability: Backups no longer pause compactions, and object-storage listing is faster — both help large collections back up more reliably.
• Fractional BM25 property boosts: Keyword-search property boosts now accept fractional values (e.g. title^2.5), not just integers.
• Deterministic tie-breaking: Vector searches break ties between equal-distance results deterministically, for stable, repeatable ordering.
• Faster startup and an improved cache for compressed vector indexes.

Community Contributions​

Weaviate is open source, and this release includes work from several first-time contributors. Thank you to:

• @dillonledoux — the new text2vec-digitalocean module (#11298)
• @anishesg — inverted-index and HFresh fixes, including correct handling of negative zero and pre-1970 dates (#11120)
• @msnandhis — fractional BM25 property boosts (#11471)
• @3em0 — reject duplicate static API keys (#11393)
• @kedar49 — collision check for DB user identifiers (#11381)
• @SAY-5 — HFresh stability fix during async init (#11087)

If you'd like to contribute, check out the contributor guide and the good-first-issue label on GitHub.

Summary​

Weaviate v1.38 brings two capabilities to general availability — HFresh and the MCP Server — alongside a rebuilt async replication path and two new previews.

Key highlights:

• HFresh (GA) — The disk-based, SPFresh-inspired vector index for streaming workloads, selected per named vector with vectorIndexType: "hfresh" and built-in RQ-1 quantization
• MCP Server (GA) — The built-in Model Context Protocol server at /v1/mcp, with its enable flags now runtime-configurable
• Async Replication, Everywhere — Cluster-wide async repair from one scheduler and a shared worker pool, on by default for replicated collections, with a runtime kill-switch
• Boost API (Preview) — Query-time rescoring that promotes or demotes results without dropping any
• Nested Object Filtering (Preview) — Filter on object / object[] properties using a dotted path

Ready to get started?

The release is available open-source on GitHub and on Weaviate Cloud, where you can spin up a cluster on the free tier.

For those upgrading a self-hosted version, please check the migration guide for version-specific notes.

Thanks for reading, and happy vector searching!

Ready to start building?​

Check out the Quickstart tutorial, or sign up for a free Weaviate Cloud account.

Most vector database pilots fail at ingest, not at search. You build a clever retrieval pipeline, you watch it work on a thousand documents, and then someone hands you fifty million rows. The next two weeks disappear into rate limits, partial failures, and three rewrites of your batch logic.

This post is the guide I wish I had the first time I imported a real dataset into Weaviate. It covers server-side batching, error handling, the data type decisions that cost you the most if you get them wrong, and how to ingest media and PDFs without standing up an OCR pipeline.

The ingest problem nobody warns you about​

A working prototype tells you nothing about what happens at scale. The problems that bite production teams almost never show up in tutorials.

Four bite hardest:

• Rate limits from your embedding provider: Most teams hit them within an hour of a real import, then write retry code, then write retry code for the retry code.
• HTTP 200 lying to you: A successful batch response does not mean every object made it in. Individual objects can fail silently behind a green status code.
• Duplicate work on retry: If you generate fresh IDs each time you re-run, you re-vectorize the same documents and pay for it twice.
• Memory blowups on media: Loading a million product photos into a Python list ends your script before your batch logic ever runs.

The rest of this post is what to do about each of them.

Server-side batching​

Server-side batching is a streaming import mode where the Weaviate server tells the client how much data to send next based on its own current workload. Instead of you guessing a batch size and a concurrency level, the server measures its queue depth and applies backpressure across a persistent connection.

This matters because the right batch size is not a constant. It depends on how many properties you have, the size of your text fields, whether you are vectorizing on the fly, what the vectorizer is doing under the hood, and what else the cluster is busy with. Hand-tuning it is brittle. The server has all of that information already.

Here is the pattern in the Python client:

import weaviate
from weaviate.classes.init import Auth

client = weaviate.connect_to_weaviate_cloud(
    cluster_url=WCD_URL,
    auth_credentials=Auth.api_key(WCD_API_KEY),
)

collection = client.collections.get("Products")

with collection.batch.stream() as batch:
    for row in iter_rows():
        batch.add_object(properties=row)
        if batch.number_errors > 10:
            print("Too many errors, stopping.")
            break

if collection.batch.failed_objects:
    print(f"{len(collection.batch.failed_objects)} objects failed.")

That is the whole pattern. No batch_size, no concurrent_requests, no tuning. The stream() context manager opens the persistent connection, the server sets the rate, errors stream back asynchronously without interrupting the flow.

Error handling and retries​

The most common bug in production import scripts is treating a 200 response as proof of success. It is not. A 200 means your request reached the server and was accepted. It does not mean every object was written. Vectorizer errors, schema mismatches, and rate-limit responses from upstream embedding APIs all show up as per-object failures inside an otherwise-happy batch response.

The Python client surfaces three things on every batch:

• batch.failed_objects — every object that failed, with the error attached
• batch.failed_references — every cross-reference that failed
• batch.number_errors — running count inside the context manager

Treat failed_objects as a queue. Write it to a file, retry it, and if it fails again on the same error, move it to a dead-letter location so the rest of your import does not stall behind one broken row.

Here is a retry-with-checkpoint pattern that holds up in production:

import json
from weaviate.util import generate_uuid5

with collection.batch.stream() as batch:
    for row in iter_rows():
        batch.add_object(
            properties=row,
            uuid=generate_uuid5(row["source_id"]),
        )

with open("failed.jsonl", "a") as f:
    for obj in collection.batch.failed_objects:
        f.write(json.dumps({
            "properties": obj.object_.properties,
            "error": obj.message,
        }) + "\n")

Two things make this safe to re-run. First, generate_uuid5 produces the same UUID for the same source_id every time, so a retry overwrites instead of duplicating. Second, errors land in a file you can re-import after fixing the underlying issue. No silent loss, no double-billing on embeddings.

Common failure modes and what to do about them:

Ingesting through the MCP server​

Weaviate ships a built-in MCP server (preview, added in v1.37.1) that lets an LLM or IDE assistant — Claude Code, Cursor, VS Code — read and write your instance over the Model Context Protocol. Enable it with MCP_SERVER_ENABLED=true, opt into writes with MCP_SERVER_WRITE_ACCESS_ENABLED=true, and the server exposes a weaviate-objects-upsert tool that creates or updates objects from inside a conversation. It runs on the same port as the REST API and respects RBAC, so there is nothing extra to deploy.

This is the right tool when an agent needs to write a few records as it works — persisting agent memory, syncing a small collection, or fixing up a handful of objects without leaving your editor.

It is not an ingestion pipeline. Every object is assembled by the model and handed over as a tool call, so you are bound by the context window and per-call latency, with none of the backpressure, streaming, or retry-checkpoint machinery from the sections above. Past a few dozen objects, reach for collection.batch.stream() (or your client's batch API) and leave the MCP server for the conversational, small-batch writes it is built for.

Choosing data types before you import​

Schema decisions cost ten times more to fix after the import has run. Get them right the first time.

The ones that matter most at import time:

• text with the right tokenization. Tokenization decides which BM25 queries match which records. The default is fine for English prose. For product codes, URLs, or anything where the literal string matters, switch to field tokenization. The tokenization tutorial walks through the trade-offs.
• uuid for foreign keys. Indexed for fast filtering, validated at insert time, and rendered as a real UUID in your client rather than a string.
• int vs number. Use int for counts and IDs. Use number for prices and ratios. Mixing them up forces casts in every query.
• Reference types for relationships you actually filter on. Do not flatten everything into one big nested object if you query the related fields independently.

The full list is in the data types reference.

blobHash: store the embedding, skip the bytes​

If you are importing media — images, audio, video, PDFs — this is the data type to know.

A regular blob stores the full base64 payload on disk. A blobHash does not. It sends the raw bytes through the vectorizer at import time so the model sees the actual media, then drops everything but a SHA-256 hash. The vector index keeps the embedding. The blob storage keeps a 32-byte fingerprint.

{
  "properties": [
    {
      "name": "product_image",
      "dataType": ["blobHash"]
    }
  ]
}

The practical impact: a 10 TB image corpus shrinks to a few gigabytes of hashes plus the vector index. Similarity search behaves exactly the same way it would with a blob. You just do not pay to store the original bytes inside Weaviate. Keep those in object storage where they belong.

There is one more nice property. When you update an object, the new base64 is hashed and compared to the stored hash before anything else happens. If the hash matches, Weaviate skips re-vectorization entirely. That alone pays for itself the first time someone re-runs an import pipeline by mistake.

PDF vectorization without the OCR pipeline​

For most readers, the practical question is "how do I ingest a folder of PDFs without writing an OCR pipeline." The shortest answer is to spin up a Weaviate Cloud trial and use Weaviate Embeddings.

Weaviate Embeddings has a multimodal model designed for image-based document retrieval. You hand it a page image, it produces a vector. No OCR step. No layout detection. No text extraction. Tables, charts, scanned forms, mixed-language documents all go in the same way. This is cloud-only, but it is the lowest-friction path for trying PDF retrieval on a real dataset and works well for collections up to a few hundred thousand pages without any architectural decisions on your part.

Another ready-made option is Google's multi2vec-google (with gemini-embedding-2 at 3072 dimensions), enabled by default on Weaviate Cloud. It follows the same workflow: you render pages to images and embed those. The module takes image input, not raw PDF files, so the rasterization step is the same as with Weaviate Embeddings.

If you are self-hosting at scale and document layout matters, look at the multi-vector ColPali recipe. It uses a vision-language model to produce multiple vectors per page and skips chunking entirely. More moving parts, but it is the state of the art for retrieval over visually rich documents.

All three paths live in the same place — the model providers reference.

Multimodal ingestion: text, image, audio, video​

Multimodal in Weaviate is not a separate product. It is a vectorizer module on the collection. You declare which model the collection uses, you import objects with media properties (ideally as blobHash), and you query across modalities with the same client you already have.

Coverage by provider:

A concrete scenario. You are building search for an e-commerce catalog. Every product has a name, a description, three photos, and a fifteen-second demo video. You want one query — "compact wireless earbuds with active noise cancellation" — to find the right product whether the relevant signal is in the text, the photo, or the video.

You declare one collection that uses multi2vec-google across named vectors: a text vector over the name and description, plus a separate blobHash vector for the product image and another for the demo video. Each blobHash property needs its own named vector — once Weaviate replaces the raw bytes with a hash, they can no longer be re-vectorized alongside other fields, so the schema keeps them apart. A single multi-target query then ranks across all three vectors at once: one collection, one query, three modalities — and the media bytes are never stored twice inside Weaviate.

Full setup details for every provider are in the model providers reference.

A checklist before you press go​

1. Pick data types deliberately. blobHash for any media you do not need to retrieve raw. field tokenization for any text where the literal string matters.
2. Pick the vectorizer at the collection level, not in your import script. Weaviate Embeddings is the easiest default on Weaviate Cloud.
3. Use deterministic UUIDs (generate_uuid5 from a stable source key) so retries are idempotent.
4. Use server-side batching via collection.batch.stream() if you are on the Python client.
5. Log failed_objects to a dead-letter file. Do not just print them.
6. Checkpoint progress for large jobs so a crash does not cost you the whole run.
7. If you are importing media at scale, keep the source bytes in object storage and let Weaviate keep the hash, not the file.

Do these seven things and you will not be the team rewriting their import script for the third time next quarter.

The fastest way to try any of this is a free Weaviate Cloud trial paired with Weaviate Embeddings. No infrastructure to manage, no embedding API keys, and every snippet in this post runs against it without modification. The import tutorial is a good next stop once you have a cluster up.

Ready to start building?​

Check out the Quickstart tutorial, or sign up for a free Weaviate Cloud account.

For years, the most common question we got was some version of "Does Weaviate have a free tier?" And for years, my sincere answer was a little awkward: Weaviate has always been free. It's open source, and anyone can run Weaviate on their local machines or own clouds without paying us a cent.

And people do, at an incredible scale. Today, we see many millions of active Weaviate databases running every single month, and our client downloads are rapidly approaching double-digit millions.

So whenever someone asked for a free tier on Weaviate Cloud, part of me wanted to say: “You already have one, go run it yourself.” For a long time, this felt like a complete and principled answer. We didn't want to build a watered-down hosted version just to have a "Free" button on the pricing page when the most powerful free option, the actual open-source database, was already sitting right there.

What changed​

Then we stopped being only a database.

Over the past two years, Weaviate grew into a platform. We built the Query Agent so you can ask questions of your data in natural language without orchestrating retrieval yourself. We built Engram, a managed memory layer so your agents can actually remember and improve over time. These aren't things you spin up from a docker run, but cloud-native services that we operate, scale and maintain.

So while "Just run the open source version" is sound advice for the database, it doesn't work for Query Agent or Engram because they are cloud services. And we introduced free tiers for these products so that all of our products are free to try. Despite this, the managed Weaviate database on Cloud remained without complete parity in this respect and offered a time-limited sandbox.

This didn’t quite sit right, because if we are going to build and scale a platform, the way in should be free across its entirety.

Free tiers across the whole platform​

So that's what we're announcing today. Weaviate Cloud is now free to start across the entire product suite. The Database, Query Agent, and Engram are all available as free tiers.

The Weaviate Cloud managed database is now genuinely free, without a credit card or time expiration. It’s the same Weaviate you know and love, with enough room to build a serious prototype, and stays on as long as you’re using it.

(If you're curious about the exact allowances, they're all on the pricing page.)

This is the parity we've wanted for a while across all of our products and we are ecstatic to share the change with you.

That shift from "free until the clock runs out" to "free as long as it's useful to you" is the right direction. A free tier should be a place you can actually settle into and build and not a sprint against an expiry date.

When you're ready for more​

At some point your project outgrows the free tier, with more data, traffic, and real users. When that happens, you can easily upgrade your free cluster to a pay-as-you-go cluster that can scale up. No migration or re-architecting is required, and you can ship what you’ve prototyped.

Start building​

If you've been waiting for a reason to try Weaviate Cloud in any of our products, this is the moment: Go build something. We can't wait to see what you make.

- Sign up for free
- Quickstart guide
- See what's included

Ready to start building?​

Check out the Quickstart tutorial, or sign up for a free Weaviate Cloud account.

We're thrilled to announce that Engram is now generally available. Engram is our managed memory and context service, purpose-built to help agents orchestrate workflows, learn from experience, and anchor decisions to trusted knowledge. If you've been following our work on memory for agents — from the conceptual framing in The Limit in the Loop to the architectural deep dive — today is the day that we open our doors for you to start building with Engram.

Memory is infrastructure​

Agents we build are supposed to compound in value over time. They should build up interactions, accumulate context, and get more useful the longer they run. In practice, however, this value compounding does not happen, and agent usage may even backfire, due to three failure modes:

• Long-context degradation. Sending whole conversations back to models on every turn drives up latency and cost. More importantly, this can cause answer quality to drop in the middle of long inputs even with state-of-the-art context windows.
• Messy raw data. User interactions are noisy and facts evolve over time. Piling raw events into a data store and asking an LLM to reconcile them at query time pushes the hardest part of the problem to the worst place for solving it.
• Multi-agent context fragmentation. The moment a single request crosses agents, built-in memory patterns collapse. Instead shared memory that's persistent and scoped is required to orchestrate workflows beyond single-agent loops.

These problems sit on the critical path to success for any production-grade agent and are deeply structural. The solution is not a patch at the prompt layer, but rather systematic memory and context management. Memory mustn't be a superficial bolt-on but should be treated as a deliberate infrastructure component in the same way that storage, retrieval, and observability are.

What Engram is​

Engram is a managed service that turns raw, noisy agent events into structured, durable, scoped memories, and serves them back through Weaviate's hybrid semantic and keyword retrieval. It is a memory layer you can trust that inherits the maturity of the Weaviate database.

Asynchronous pipelines run in the background to extract relevant information, reconcile it against what's already known while handling deduplication, preference changes, and time-evolving facts, and persist a clean memory state. Use-case templates for personalization are available day one with templates for continual learning, and multi-agent state available in the following weeks. Teams that outgrow them can drop down to direct pipeline control without leaving the platform. For the architecture in detail — pipelines, topics, scopes, and buffers — see the Engram deep dive.

The road from preview to GA was shaped by real-world use cases; putting Engram into different situations surfaced the changes that define production-ready: more durable pipelines, more efficient extractions and transforms, and deterministic reconciliation that avoids memory drift. This hardening lies beneath everything you get with Engram:

• Actively maintained memory instead of an ever-growing context blob. Pipelines extract, deduplicate, and reconcile against what's already known, so the memory state stays clean as interactions accumulate.
• Fire-and-forget at the application layer. Memory pipelines run asynchronously and durably in the background; the hot path is never blocked on memory I/O. Backed by Temporal-grade durability so partial failures recover cleanly and commits stay atomic.
• Templates for the common case, primitives for everything else. Personalization, continual learning, and multi-agent state ship as ready-to-deploy templates. Teams that need more control drop into the underlying pipeline primitives without changing platforms.
• Built-in scopes from day one. Per-project, per-user, and per-property isolation is part of the primitive (not a feature flag bolted on later), so the right memories are visible to the right caller by construction.
• Unified retrieval on Weaviate. Memory inherits Weaviate's hybrid search, scaling characteristics, and operational track record. There's no parallel system to deploy, secure, or operate.

Who should use Engram​

Engram is for teams whose agents have outgrown a single turn: assistants that should remember a user across sessions, agents that should get better from feedback instead of repeating mistakes, and multi-agent systems that need to share scoped state. If you're building one of these, you've almost certainly built some version of memory yourself.

It usually starts as one of a few things: sending whole conversations back to the model on every turn, hand-pruning a MEMORY.md, storing raw events as memory directly inside a data store, or running a standalone memory provider alongside your retrieval stack. Each works for a window of complexity before breaking due to the reasons above: degrading context with growth, unreconciled raw data, and fragmenting memory across multiple agents.

Engram is what's on the other side of that break: active reconciliation instead of accumulation, durable pipelines instead of synchronous side effects, and one platform for memory and retrieval instead of two.

Get started with Engram​

Engram is now generally available in Weaviate Cloud. Start compounding your agents' value today with our free tier.

Spin up your first project in a few clicks:

• Read the Engram documentation
• For the full architecture story, see the Engram deep dive
• Subscribe to the Weaviate Agents newsletter for product updates and best practices

Ready to start building?​

Check out the Quickstart tutorial, or sign up for a free Weaviate Cloud account.

You can now assign more granular roles to users in your Weaviate Cloud organization. We are expanding role-based access control (RBAC) for the Cloud console with two new roles — Editor and Viewer — that add to the existing Owner and Admin roles, giving organizations more control over resource access.

Role-based access control is a security best practice and a standard feature in modern cloud platforms. It provides a structured way to grant, organize, and delegate permissions across the people and applications working with your cloud resources. RBAC reduces the risk of accidental changes, limits the blast radius of mistakes, and gives security and platform teams the clarity they need to scale Weaviate Cloud usage across an organization.

By assigning Editor or Viewer roles instead of sharing full access, organizations can apply the principle of least privilege, ensuring team members have only the access they need to do their jobs. This applies whether you're a small team of developers or an enterprise rolling out Weaviate across multiple business units.

Weaviate Cloud roles and use cases​

Within a Weaviate Cloud organization, every user can be assigned one of four roles. Each role grants a specific set of permissions across organization settings, billing, cluster management, and access to cluster data.

How to manage roles in Weaviate Cloud​

Managing roles in Weaviate Cloud takes just a few clicks.

1. Open your organization menu. At the top of the Weaviate Cloud console, click the Organization dropdown.
2. Select Organization settings. From the dropdown, choose Organization settings to open your organization's management page.
3. Manage users and roles. Under the Users and Access section, you'll see every member of your organization, their assigned role, and a description of what each role can do. From here you can:
   • Click + Add User to invite a new member and assign their role during invitation
   • Change an existing user's role using the role selector
   • Remove a user from the organization

Changes take effect immediately. Users will see their new permissions on their next action in the console.

Learn more​

If you're ready to start using granular roles in your own organization, sign in to Weaviate Cloud and head to your organization settings. To dive deeper, check out the product documentation.

Have questions or feedback? Join the conversation in our Community Forums or reach us at support@weaviate.io.

Last week I asked Claude Code to implement something relatively trivial in my codebase. Three turns in, the conversation used up >80K tokens and Claude was still missing some crucial information I'd forgotten to include. That's the loop you fall into without retrieval: paste too little and the agent guesses, paste too much and pay for context the agent isn't using.

Most teams solve this with RAG over the codebase. The typical setup is a vector database plus a custom MCP server process bridging the two. Weaviate simplifies this: the MCP server is built into the database, at /v1/mcp on the same port as the REST API. One env var enables it. The same hybrid search you'd use for any other Weaviate workload powers code retrieval, with the BM25 half keeping function identifiers like connect_to_local matchable and the vector half finding semantic intent like "how do I init a client."

This post walks through building a coding assistant on top of that built-in MCP server: ingest a codebase, ingest its docs, connect Claude Code, Cursor, and VS Code, and run real queries. Topics covered:

• Why your coding assistant needs more than its training data
• Why Weaviate MCP fits this job
• Step 1: Run Weaviate with MCP enabled
• Step 2: Design the schema
• Step 3: Chunk and ingest the codebase
• Step 4: Chunk and ingest documentation
• Step 5: Connect Claude Code, Cursor, and VS Code
• Try it out
• Agent runbook: autonomous setup

Why your coding assistant needs more than its training data​

LLMs ship with a fixed cutoff and zero knowledge of your private code. The naive workaround is to dump files into the prompt. That has three problems.

• Cost: Tokens in context are billed. Every turn. A 200-file Python project doesn't fit, and even the parts that do are billed continuously while the agent reasons.

• Stale context: Once a file is in the prompt, it's frozen. If the agent changes a function and then needs to read it again, it has to reload the whole file. There's no live link between the model's view and the on-disk truth.

• Wrong granularity: Even when files fit, the model spends attention on the wrong parts. Imports. Module-level boilerplate. The function the agent is actually editing competes for context with a hundred lines of from x import y.

Retrieval solves all three. Index the codebase once, store the chunks in a vector database, and let the LLM client pull only what it needs per query. That's RAG. Coding assistants haven't had a clean way to talk to such a database without a custom shim. That's where MCP comes in.

Why Weaviate MCP fits this job​

The Model Context Protocol (MCP) is the standardized way for LLM clients like Claude Code, Cursor, and VS Code to call out to external tools. Weaviate v1.37.1 exposes its core operations as MCP tools directly, on a Streamable HTTP endpoint at /v1/mcp. Four tools are surfaced:

• weaviate-collections-get-config — let the LLM inspect what collections exist and what properties they have
• weaviate-tenants-list — list tenants when you're using multi-tenancy
• weaviate-query-hybrid — run hybrid (BM25 + vector) search
• weaviate-objects-upsert — write objects back, only when write access is enabled

Hybrid search is the most concrete reason this stack works for a coding assistant. Code is a mix of identifiers and intent. BM25 nails the identifiers. Vectors nail the intent. A query like "where do we handle retry on 429?" wants both at once: vectors find the semantically related retry code, BM25 anchors on 429 as an exact token. Pure-vector retrieval drops the integer match. Pure-BM25 misses any wording the user didn't already know. Hybrid wins on this kind of mixed-intent query.

Operational simplicity is the second reason. Competing stacks run an MCP server alongside the vector database. That's a second service to watch in production. Weaviate ships the MCP server inside the database, on the same port, with the same auth. The thing you have to monitor is just Weaviate.

The third reason is multi-tenancy. One Weaviate instance can hold many codebases, each isolated as a tenant. For an organization with multiple repos, that's one cluster instead of one-per-team.

Weaviate MCP vs function calling comes up as a natural question. Function calling is per-LLM-API. MCP is transport-level: any client that speaks MCP can call any server that speaks MCP, no rewrites. Build the retrieval once, use it from Claude Code, Cursor, and VS Code without translating.

Step 1: Run Weaviate with MCP enabled​

The MCP server is disabled by default. Two environment variables turn it on:

# docker-compose.yml
services:
  weaviate:
    image: cr.weaviate.io/semitechnologies/weaviate:1.38.8
    ports:
      - '8080:8080'
      - '50051:50051'
    environment:
      MCP_SERVER_ENABLED: 'true'
      MCP_SERVER_WRITE_ACCESS_ENABLED: 'true'
      AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'
      DEFAULT_VECTORIZER_MODULE: 'text2vec-openai'
      ENABLE_MODULES: 'text2vec-openai'
      OPENAI_APIKEY: ${OPENAI_APIKEY}

MCP_SERVER_ENABLED exposes the read tools (config, tenants, hybrid query). MCP_SERVER_WRITE_ACCESS_ENABLED adds the upsert tool, which lets the agent write findings back. Skip it if you only want retrieval.

Honestly, I'd skip it for a while even if you think you want write-back. Read-only MCP covers most of what a coding agent actually does, and you sidestep a class of failure modes where the agent writes nonsense back into your knowledge base. Turn write access on once you have a specific use case that justifies the risk.

Bring it up and confirm the endpoint is alive. Streamable HTTP requires an initialize handshake before any other call, so the liveness probe sends one:

docker compose up -d
curl -sf -X POST http://localhost:8080/v1/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc":"2.0","id":0,"method":"initialize",
    "params":{
      "protocolVersion":"2025-03-26",
      "capabilities":{},
      "clientInfo":{"name":"curl","version":"1"}
    }
  }'

A live MCP server returns a JSON-RPC envelope describing the server's capabilities and sets an Mcp-Session-Id response header that subsequent calls must echo back. You don't need to parse the body for a sanity check — a non-empty response is enough. If you get a connection refused or a 404, MCP isn't enabled.

Step 2: Design the schema​

Two collections, one for code chunks and one for documentation chunks, sharing the same Weaviate instance:

import weaviate
from weaviate.classes.config import Property, DataType, Tokenization, Configure

client = weaviate.connect_to_local()

client.collections.create(
    name="CodeChunks",
    properties=[
        Property(name="content", data_type=DataType.TEXT,
                 tokenization=Tokenization.WORD),
        Property(name="symbol", data_type=DataType.TEXT,
                 tokenization=Tokenization.LOWERCASE),
        Property(name="file_path", data_type=DataType.TEXT,
                 tokenization=Tokenization.FIELD),
        Property(name="language", data_type=DataType.TEXT,
                 tokenization=Tokenization.FIELD),
        Property(name="repo", data_type=DataType.TEXT,
                 tokenization=Tokenization.FIELD),
    ],
    vector_config=Configure.Vectors.text2vec_openai(),
)

client.collections.create(
    name="DocChunks",
    properties=[
        Property(name="content", data_type=DataType.TEXT,
                 tokenization=Tokenization.WORD),
        Property(name="title", data_type=DataType.TEXT,
                 tokenization=Tokenization.WORD),
        Property(name="source_url", data_type=DataType.TEXT,
                 tokenization=Tokenization.FIELD),
    ],
    vector_config=Configure.Vectors.text2vec_openai(),
)

The tokenization choices matter. symbol uses lowercase so connect_to_local is one token instead of three. file_path, language, and repo use field so they match exactly. Prose properties (content, title) use word. If this section feels familiar, the tokenization post explains why each method belongs where.

Step 3: Chunk and ingest the codebase​

Naive line-based chunking destroys code. A function split across two chunks loses its signature on one side and its body on the other. The fix is to chunk along syntactic boundaries: one chunk per function, one per class, one per top-level statement.

Python's standard library is enough for Python code (no extra dependency). For other languages, tree-sitter is the standard choice (10+ languages, AST-aware, fast).

import ast
from pathlib import Path

def chunk_python_file(path: Path) -> list[dict]:
    """Emit one chunk per top-level function or class."""
    source = path.read_text()
    tree = ast.parse(source)
    lines = source.splitlines()
    chunks = []
    for node in ast.iter_child_nodes(tree):
        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
            start = node.lineno - 1
            end = node.end_lineno
            chunks.append({
                "content": "\n".join(lines[start:end]),
                "symbol": node.name,
                "file_path": str(path),
                "language": "python",
                "repo": "my-service",
            })
    return chunks

Ingest with server-side batching. data.ingest() takes any iterable, so a generator expression over the repo streams chunks to the server as they are produced, at whatever pace the server asks for:

code_chunks = client.collections.use("CodeChunks")

code_chunks.data.ingest(
    chunk
    for py_file in Path("./src").rglob("*.py")
    for chunk in chunk_python_file(py_file)
)

Weaviate vectorizes each chunk on insert via the configured text2vec-openai module, so there's no separate embedding step. Replace the vectorizer with text2vec-voyageai (Voyage's voyage-code-2 is purpose-built for code) or text2vec-cohere if you want a different embedding family.

Step 4: Chunk and ingest documentation​

Prose chunks differently. Headings are real boundaries. A useful default is "split on H2, then on H3 if a section is too long":

import re

def chunk_markdown(text: str, max_chars: int = 1500) -> list[str]:
    sections = re.split(r"(?m)^## ", text)
    chunks = []
    for section in sections:
        if len(section) <= max_chars:
            chunks.append(section.strip())
        else:
            for sub in re.split(r"(?m)^### ", section):
                chunks.append(sub.strip())
    return [c for c in chunks if c]

doc_chunks = client.collections.use("DocChunks")

doc_chunks.data.ingest(
    {
        "content": content,
        "title": md_file.stem,
        "source_url": f"https://docs.example.com/{md_file.stem}",
    }
    for md_file in Path("./docs").rglob("*.md")
    for content in chunk_markdown(md_file.read_text())
)

Two collections, two chunking strategies, one Weaviate instance. The MCP server exposes both through the same weaviate-query-hybrid tool. The agent picks which collection to query.

Step 5: Connect Claude Code, Cursor, and VS Code​

The MCP transport is HTTP, so client config is small. Each client has its own file. All three point at the same Weaviate endpoint.

Claude Code (~/.claude.json):

{
  "mcpServers": {
    "weaviate": {
      "type": "http",
      "url": "http://localhost:8080/v1/mcp"
    }
  }
}

Or via the CLI:

claude mcp add weaviate http://localhost:8080/v1/mcp --transport http

Cursor (~/.cursor/mcp.json or project-local .cursor/mcp.json):

{
  "mcpServers": {
    "weaviate": {
      "url": "http://localhost:8080/v1/mcp"
    }
  }
}

VS Code with Copilot (.vscode/mcp.json):

{
  "servers": {
    "weaviate": {
      "type": "http",
      "url": "http://localhost:8080/v1/mcp"
    }
  }
}

Restart the client. The Weaviate tools (weaviate-query-hybrid, weaviate-collections-get-config, etc.) should appear in the client's tool list. If they don't, check that MCP_SERVER_ENABLED=true is set and that the port is reachable.

Try it out​

Open Claude Code in any directory after the runbook below has finished. Ask something specific to FastAPI internals that a generic model would only paraphrase from training data:

"How does FastAPI handle dependency injection — show me the actual resolver."

Without MCP, Claude Code paraphrases the FastAPI dependency injection docs from training. With MCP, it calls weaviate-query-hybrid against CodeChunks, the BM25 half nails identifiers like Depends and solve_dependencies, the vector half pulls in nearby resolver code, and the answer cites real lines from fastapi/dependencies/utils.py.

Try a docs query:

"When should I use async def versus def in FastAPI route handlers?"

Same shape, different collection. The agent queries DocChunks, returns the relevant section from FastAPI's async def versus def guide, and answers with the actual recommendation rather than guessing.

The general pattern: the agent decides per-question whether code, docs, or both are relevant, and pulls the chunks that are. Context size stays bounded. The repo can be huge.

Agent runbook: autonomous setup​

The narrative above is for humans. If you are an agent (Claude Code, Cursor, or any MCP-aware assistant) executing this end-to-end, the dropdown below is the contract: ordered steps, full scripts, success criteria. Run them in order. Each step prints a marker the next step can check.

# Clone FastAPI as the demo target
git clone --depth=1 https://github.com/fastapi/fastapi.git /tmp/fastapi

export WEAVIATE_DIR="$HOME/weaviate-code-assistant"   # where docker-compose.yml lives
export CODE_DIR="/tmp/fastapi/fastapi"                 # FastAPI Python source
export DOCS_DIR="/tmp/fastapi/docs/en/docs"            # FastAPI English MkDocs content
export OPENAI_APIKEY="sk-..."                          # required for the text2vec-openai vectorizer

#!/usr/bin/env bash
set -euo pipefail

mkdir -p "$WEAVIATE_DIR"
cd "$WEAVIATE_DIR"

cat > docker-compose.yml <<'YAML'
services:
  weaviate:
    image: cr.weaviate.io/semitechnologies/weaviate:1.38.8
    ports:
      - "8080:8080"
      - "50051:50051"
    environment:
      MCP_SERVER_ENABLED: 'true'
      MCP_SERVER_WRITE_ACCESS_ENABLED: 'true'
      AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'
      PERSISTENCE_DATA_PATH: '/var/lib/weaviate'
      DEFAULT_VECTORIZER_MODULE: 'text2vec-openai'
      ENABLE_MODULES: 'text2vec-openai'
      OPENAI_APIKEY: ${OPENAI_APIKEY}
    volumes:
      - weaviate-data:/var/lib/weaviate
volumes:
  weaviate-data:
YAML

docker compose up -d

# Wait for the REST API to come up (max 60s)
for i in {1..30}; do
  if curl -sf http://localhost:8080/v1/.well-known/ready > /dev/null; then
    echo "STEP_1_READY"
    break
  fi
  sleep 2
done

# Verify the MCP endpoint is reachable. Streamable HTTP requires an
# initialize handshake first; tools/list then needs the Mcp-Session-Id
# header returned by initialize.
SID=$(curl -s -i -X POST http://localhost:8080/v1/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{
        "protocolVersion":"2025-03-26","capabilities":{},
        "clientInfo":{"name":"curl","version":"1"}}}' \
  | awk -F': ' 'tolower($1)=="mcp-session-id"{print $2}' | tr -d '\r\n')

if [ -z "$SID" ]; then
  echo "STEP_1_MCP_FAILED: no Mcp-Session-Id returned. MCP may be disabled."
  exit 1
fi

curl -sf -o /dev/null -X POST http://localhost:8080/v1/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "Mcp-Session-Id: $SID" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  && echo "STEP_1_MCP_OK" \
  || { echo "STEP_1_MCP_FAILED"; exit 1; }

#!/usr/bin/env python3
"""Ingest a codebase and its docs into Weaviate. Run after setup.sh."""
import ast
import os
import re
import sys
from pathlib import Path

import weaviate
from weaviate.classes.config import Property, DataType, Tokenization, Configure

CODE_DIR = Path(os.environ["CODE_DIR"]).resolve()
DOCS_DIR = Path(os.environ.get("DOCS_DIR", CODE_DIR)).resolve()
REPO_LABEL = CODE_DIR.name

client = weaviate.connect_to_local()
try:
    # ---- Schema (idempotent) ----
    if not client.collections.exists("CodeChunks"):
        client.collections.create(
            name="CodeChunks",
            properties=[
                Property(name="content", data_type=DataType.TEXT, tokenization=Tokenization.WORD),
                Property(name="symbol", data_type=DataType.TEXT, tokenization=Tokenization.LOWERCASE),
                Property(name="file_path", data_type=DataType.TEXT, tokenization=Tokenization.FIELD),
                Property(name="language", data_type=DataType.TEXT, tokenization=Tokenization.FIELD),
                Property(name="repo", data_type=DataType.TEXT, tokenization=Tokenization.FIELD),
            ],
            vector_config=Configure.Vectors.text2vec_openai(),
        )
    if not client.collections.exists("DocChunks"):
        client.collections.create(
            name="DocChunks",
            properties=[
                Property(name="content", data_type=DataType.TEXT, tokenization=Tokenization.WORD),
                Property(name="title", data_type=DataType.TEXT, tokenization=Tokenization.WORD),
                Property(name="source_url", data_type=DataType.TEXT, tokenization=Tokenization.FIELD),
            ],
            vector_config=Configure.Vectors.text2vec_openai(),
        )

    # ---- Code: AST-chunk every .py file ----
    code = client.collections.use("CodeChunks")
    code_count = 0
    with code.batch.stream() as batch:
        for py in CODE_DIR.rglob("*.py"):
            if any(part.startswith(".") or part in ("node_modules", "venv", ".venv", "__pycache__") for part in py.parts):
                continue
            try:
                source = py.read_text(encoding="utf-8")
                tree = ast.parse(source)
            except (SyntaxError, UnicodeDecodeError):
                continue
            lines = source.splitlines()
            for node in ast.iter_child_nodes(tree):
                if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
                    chunk = "\n".join(lines[node.lineno - 1:node.end_lineno])
                    batch.add_object(properties={
                        "content": chunk,
                        "symbol": node.name,
                        "file_path": str(py),
                        "language": "python",
                        "repo": REPO_LABEL,
                    })
                    code_count += 1
    print(f"STEP_2_CODE_CHUNKS={code_count}")

    # ---- Docs: heading-chunk every .md file ----
    docs = client.collections.use("DocChunks")
    doc_count = 0
    with docs.batch.stream() as batch:
        for md in DOCS_DIR.rglob("*.md"):
            if any(part.startswith(".") for part in md.parts):
                continue
            try:
                text = md.read_text(encoding="utf-8")
            except UnicodeDecodeError:
                continue
            sections = re.split(r"(?m)^## ", text)
            for sec in sections:
                sec = sec.strip()
                if not sec:
                    continue
                if len(sec) > 1500:
                    for sub in re.split(r"(?m)^### ", sec):
                        sub = sub.strip()
                        if sub:
                            batch.add_object(properties={
                                "content": sub,
                                "title": md.stem,
                                "source_url": f"file://{md.resolve()}",
                            })
                            doc_count += 1
                else:
                    batch.add_object(properties={
                        "content": sec,
                        "title": md.stem,
                        "source_url": f"file://{md.resolve()}",
                    })
                    doc_count += 1
    print(f"STEP_2_DOC_CHUNKS={doc_count}")

    if code_count + doc_count == 0:
        print("STEP_2_FAILED: no chunks ingested. Check CODE_DIR / DOCS_DIR paths.", file=sys.stderr)
        sys.exit(2)
    print("STEP_2_INGEST_OK")
finally:
    client.close()