Embedding / vector search (RAG for an agent) returns irrelevant or too few results: could it be chunking, missing normalization, query vs document input type, a distance metric mismatch with the index, or approximate index recall?

Cause: Bad retrieval is usually a pipeline mismatch rather than a bad model. The common ones are: queries and documents embedded differently, a distance operator that does not match the index, an approximate index with low recall, filters applied after the index scan, and chunks that are too large or too small to match a question. Fix (check in this order): 1. Use the same embedding model for documents and queries, and if your provider has an input-type parameter, set it. Voyage AI, the provider Anthropic's docs point to, says to specify whether text is a query or a document for retrieval and not to omit it, because it changes the vector representation. 2. Match the metric. Voyage embeddings are normalized to length 1, so dot product and cosine give the same ranking. If you shorten Matryoshka-style vectors by truncating dimensions, normalize them again afterward. Check your own provider's docs for whether its vectors are normalized. 3. In pgvector, the operator and index operator class must agree: <-> L2 with vector_l2_ops, <#> negative inner product with vector_ip_ops, <=> cosine distance with vector_cosine_ops. Queries must ORDER BY the distance operator ascending with a LIMIT or the index is not used. Note <#> returns the negative inner product. 4. Remember approximate indexes trade recall for speed. Compare against exact search (disable index scans in a transaction) to measure the loss. Raise hnsw.ef_search (default 40) or ivfflat.probes (default 1) for better recall. With HNSW, ef_search also caps how many rows come back, so you can get fewer than LIMIT. 5. If you filter with WHERE, approximate indexes filter after the scan, so selective filters can return few or zero rows. Use pgvector's iterative scan settings, a partial index for a few values, or partitioning for many. 6. Build an IVFFlat index after the table has data; building it on a nearly empty table can leave later queries returning too few rows. 7. Tune chunking with a test set: split on natural boundaries (headings, paragraphs, functions), keep chunks small enough to be about one topic, add some overlap, and prepend titles or section names as context. There is no universal size, so measure recall on real questions. A reranker can reorder the top results. Verify: Build 20-50 real questions with known right passages and measure whether the right chunk is in the top 5 before and after each change. Exact-search results and indexed results should now largely agree. Sources: https://platform.claude.com/docs/en/build-with-claude/embeddings https://github.com/pgvector/pgvector