About
About this site and its sources
What this site is, what it is not, where its ideas come from, the sister sites, and how the facts and the SQL were checked.
This is a knowledge site about retrieval for agentic software: how the rows and passages a language model reads are found. It starts from a plain SELECT ... WHERE and climbs through full-text search, vectors computed by hand, embeddings, storage layouts, exact search, approximate indexes, pipelines, hybrid search, reranking, grounding, evaluation and production choices. At every step it asks one question: which rows did we find, and how do we know they are the right ones? It is written for engineers and architects who build agent systems, and for backend and database engineers who know SQL well and meet vector search for the first time.
One example runs through every page. An insurer receives a broker's request for a quote. An underwriting agent searches three corpora: the insurer's written guidance, past applicant profiles and underwriter precedents. It writes a recommendation with citations, and a human underwriter decides. The model recommends; a person decides.
What it is and is not#
| It is | It is not |
|---|
| A ladder: one idea per step, each term in plain English with a tiny example before it is used | A standard, or the only way to build retrieval |
One running example with the series cases UW-004, UW-005, UW-007 and this site's own cases UW-R01 to UW-R10 | A record of any real insurer. The cases, rules, fields, vectors and numbers are invented |
| A demonstration of mechanism: how a vector column, a distance, a filter, an index, a fusion step and a citation fit together | A measurement of any model, database or product. No page reports how good a real system is |
| Code and SQL that were run: a standard-library Python example, SQL on a throwaway PostgreSQL, sqlite-vec in a throwaway environment, with their real output | A framework to install, or a benchmark. Costs are counted as distance computations, never as milliseconds |
| Products described from their own documentation, read on 2026-11-18, by what each does for retrieval | A ranking or a buying guide. No product is ranked above another, and no price is quoted |
What is original here and what is not#
| Part | Status |
|---|
| Retrieval-augmented generation, embeddings, cosine similarity, BM25, HNSW, IVF, reciprocal rank fusion, recall@k, MRR, nDCG | Established methods, described from their papers and documentation (listed below). This site explains them; it did not invent them |
| PostgreSQL, pgvector, SQLite, sqlite-vec, vec1, the Google Cloud products, the vector databases on the ecosystems page, LangChain and LlamaIndex | Products and libraries, described from their own documentation as read on 2026-11-18 |
| The first primitive as stated on every page (one vector per row, compared, ranked, nearest k, the model reads only what was returned) and the four separations (layout, algorithm, model; model, dimension, index, metric; reindex, re-embed; budgets, table size) | A teaching framing written for this site |
| The decision guide, the storage decision flow and the eight-step scaling playbook | Designs proposed on this site, assembled from common database and search practice. They contain no row-count thresholds on purpose |
The toy encoders, the three corpora, the policy fixture, the cases UW-R01 to UW-R10 and the failure scenarios | Written for this site. All synthetic |
| The example code, its tests, the SQL files and the interactive labs | Written for this site. The labs' logic is a second implementation of the Python code, and a test fails if the two differ |
Where a page takes an idea from a source, the page says so. Where this site proposes something, it calls it a design.
How the facts were checked#
| Kind of claim | How it was checked |
|---|
| A named product, library, standard or paper | Read in its own documentation on 2026-11-18. A source pack of 377 claim rows, each with its address and date, was built first (docs/facts/_sources/ in the repository); every item that looked surprising, such as a renamed product, a moved page or a non-default constant, was fetched a second time, and an independent second reader re-fetched the most consequential ones. Each page then logs its own claims in docs/facts/<page>.md, re-reading a source the same day when the pack did not cover a claim. Where the documentation is silent, the page says so |
| The example | Run. Every command shown from examples/rag-uw/ was executed in a copy of the folder, and the output on the page is the output it printed. run_demo.py passes 13 of 13 cases and 8 of 8 debugger scenarios; python3 -m unittest runs 61 tests, all passing; two runs print the same bytes |
| The SQL | schema.sql, seed.sql and queries.sql ran unchanged on a throwaway PostgreSQL 16.14 with pgvector 0.8.3, in a disposable container started for the run, on a database created before it and dropped after it. The recorded output is examples/rag-uw/sql/OUTPUT.md, and only that output is presented as run. Plans and row counts are one run on one laptop, toy data; not a benchmark |
| SQLite | sqlite_exact.py (standard library, SQLite 3.53.4) was run in a copy of the example. sqlite_vec_demo.py ran with sqlite-vec 0.1.9 installed into a throwaway virtual environment outside the repository; its output is examples/rag-uw/SQLITE_VEC_OUTPUT.md |
| The labs | They read data generated from the example. node scripts/test_rag_core.mjs runs 304 checks that the JavaScript gives the same results as the Python, from vector math and BM25 to the chart filter of the ecosystems lab |
| Other code | A block that was not run says so, for example "documented shape; not run here". Every Python block on the site compiles in the build |
| Links and structure | A build step checks every internal link and anchor, every diagram, every glossary reference and every JSON block before the site is published |
Documentation changes, and in this field it changes monthly. By the day these pages were read, Google Cloud's documentation presented Vertex AI as part of Gemini Enterprise Agent Platform and had renamed several retrieval products, LangChain's documentation had moved to a new address, and the langchain-postgres README deprecated a class that LangChain's own integration page still shows. Treat every statement about a product as true on the day it was read, and read the product's page again before you build on it.
What the example does not show#
The series example is an illustrative reconstruction for teaching. Cases, rules, fields, vectors and every number are invented. Nothing here reports the quality of a real system or model. Example roof thresholds are synthetic, not insurance practice.
| In the example | What it really is |
|---|
| The embedding model | Toy encoders (toy-a@1, toy-b@1, toy-a@2) that map words to 16 named concept dimensions and normalize. They behave like an embedding model in the ways the site teaches and are not a model. Real models produce 384, 768 or more dimensions |
| The answer writer | A script that builds the prompt, cites, abstains and applies precedence. No model is called. There is no network and no key |
| The cross-encoder | A deterministic stand-in whose scores are not probabilities |
| HNSW and IVF | Toy implementations with fixed seeds, measured in distance computations. Their numbers say how the mechanism trades work for recall, not how fast any library is |
| The corpora | 18 guidance passages, 240 applicant profiles and 40 precedents, all synthetic; precedents are marked simulated: true and are never history |
| Metrics | Computed on synthetic labels written for the example; they describe the example, not any model |
| Google Cloud, the vector databases, LangChain and LlamaIndex | Described from documentation; not run here |
The two builds the case studies come from#
Two projects by the author appear as case studies. Pages state only facts confirmed from their source on 2026-11-18, and say "in that build" or "in the code read".
The insurance build is a production-shaped insurance quote workflow with simulated vendors, a Java service (Spring, JDBC) on PostgreSQL 16 with pgvector. In that build, both retrieval corpora use all-MiniLM-L6-v2 at 384 dimensions, run in process through ONNX Runtime with no embedding API call; vectors are L2-normalized in code and compared by cosine distance. Its applicant-profile corpus embeds a fixed banded template, never raw numbers or personal data, and has an HNSW index (m = 16, ef_construction = 64, ef_search = 80). Its precedent corpus has no approximate index: a btree on provision, status and decision date plus an exact distance sort, because per-provision sets are small, then a reranker of 0.6 × matching bands + 0.3 × cosine similarity + 0.1 × recency. It insures homes in its own domain; the commercial-property example on this site is a separate, synthetic reconstruction.
Mnemos is the author's open-source, local-first personal RAG application (TypeScript, Next.js; version 0.21 read). In the code read, it keeps everything in one SQLite file with the sqlite-vec extension loaded, with vectors in a separate vec0 virtual table joined to its chunk table by id. It embeds locally with a 384-dimension model through ONNX in process, chunks with a recursive character splitter of about 1,000 characters and about 200 overlap, retrieves by dense search only, and by default sends nothing off the machine; an external model, if configured, receives the retrieved chunks only.
The sister sites#
This site is one of a series on AI-native engineering. Each owns one subject and links the others at the seams.
| Site | What it owns |
|---|
| prompt.sammuthu.com | Instructions: how they are written, composed and defended |
| context.sammuthu.com | What the model can see now: selection, retrieval, budget |
| memory.sammuthu.com | Durable information and saved execution state |
| a2a.sammuthu.com | Messages between agents; A2A versus MCP |
| observe.sammuthu.com | Logs, metrics, traces, audit events, replay |
| guardrails.sammuthu.com | Enforceable checks around a probabilistic agent |
| tools.sammuthu.com | Callable capabilities: schema, execution, MCP tools |
| mcp.sammuthu.com | Shared capabilities across teams: when MCP is justified, identity, authorization, governance |
| schema.sammuthu.com | Typed contracts: shape, validation, repair, evolution |
| orchestrate.sammuthu.com | The control plane: what runs next |
| reliable.sammuthu.com | Acceptable outcomes despite failures and load |
| harness.sammuthu.com | The runtime around a model call |
| eval.sammuthu.com | Measurement: graders, golden sets, release gates |
| diff-to-deploy.sammuthu.com | Shipping a change with coding agents |
Sources and reading list#
Each link below was opened on 2026-11-18. The fact logs in the repository list every claim with the exact page it came from.
Standards and papers#
PostgreSQL and pgvector#
| Source | Why read it |
|---|
| pgvector and its changelog | The vector type, operators, HNSW and IVFFlat, iterative scans, filtering. Latest release 0.8.7 on 2026-10-01; 0.9.0 unreleased |
| pgvector-python | Binding vectors from psycopg, SQLAlchemy and other drivers |
| PostgreSQL full-text search and EXPLAIN | tsvector, ranking, GIN indexes, and reading plans |
SQLite#
Google Cloud#
Other engines#
Frameworks#
Models and benchmarks#
Who wrote it#
Written by Sam Muthu, an engineer who builds agentic systems. The example follows the shape of a real project by the author; everything in it is synthetic. Corrections are welcome.