About this site

Agent Context Explained is about context engineering: what goes into an agent's context window, and how an agent remembers beyond it. Nine chapters cover the window as working memory, the retrieval that fills it (BM25, dense retrieval, hybrid fusion and reranking, chunking), packing a token budget, compaction, memory across sessions, and when a long prompt beats retrieval. Every chapter is built around an animation. It is the third of a family of agent sites, after Agent Harnesses Explained and Agent Protocols Explained and followed by Agent Orchestration Explained, next to the LLM-systems sites (the Transformer Decoder Explainer, LLM Inference Explained, Inference Trade-offs Explained and others, all in the header's switch).

Measured, not asserted

Every retrieval number is measured on a fixed, openly licensed corpus: 6 articles of the SQuAD v1.1 development set (37,499 tokens) and 200 of their questions, sampled with a fixed seed from 1,160. Each question comes with its answer's exact position, so relevance needs no judgement: a chunk is relevant when it contains the whole answer. The data page lists the sources, licences, model revisions and checksums, and the full results.

Models ran once, offline

No model runs on this site or in its CI. An embedding model (all-MiniLM-L6-v2) and a cross-encoder reranker (ms-marco-MiniLM-L6-v2) ran once, on a CPU, in the engine's build script. What ships is their output: 8-bit embeddings of every question, sentence and chunk, and the reranker's scores for 6,226 question–chunk pairs. From those files the engine recomputes everything else: chunk boundaries, BM25, cosine similarities, fusion, reranked orders, recall@k, MRR and nDCG, the window task, packing, compaction, memory across sessions and the long-context costs. The only numbers that need the unquantised vectors, the float32 baselines, were recorded by the offline run and are labelled as such.

The engine, and how the animations are checked

The engine is Agent_Loop_Sim's context module (engine 1.11.1): a Python reference with a TypeScript port, vendored here at commit 46b445c with every file's SHA-256 recorded. It runs in a Web Worker. Agreement between the two languages is exact, with no tolerance: every chunk, score, ranking, metric and animation frame. Two details make that possible: all vector arithmetic is on integers (one square root and one division at the end, both correctly rounded), and BM25's logarithm is a shared transcription of fdlibm's, because the platform logarithms of Python and of browsers differ in the last bit for some inputs.

• In CI, the Python reference installed from the vendored commit regenerates this site's fixtures (everything each chapter animates), and the unit tests require the vendored TS engine to reproduce them exactly.
• Every number in the prose is computed by the engine when the page is built, never typed in.
• Every code block in a chapter is cut from the vendored engine, and every equation compiles; end-to-end tests play, step, scrub and reset every animation in light and dark mode at desktop and phone widths, and check its captions at key steps against the Python reference's frames.

What is illustrative

• The window task of chapter 1: a scripted agent, budgets scaled down to 1,000–3,000 tokens, and a summariser that keeps every fact by construction (a lossy option drops each line with an illustrative probability); the lossy summariser's loss rates in chapter 7.
• Chapter 6's position curve (shaped like the U of “Lost in the Middle”, with made-up numbers) and its chunk values (a rank gain, not a probability).
• Chapter 8's agent, its importance ratings and its fact extractor are scripted.
• Chapter 9's prices are dated list prices; sets larger than the corpus are hypothetical, latency is a round-number profile, and long-prompt surcharges and model limits are not modelled.
• The sentence splitter is a simple rule; the semantic chunker's threshold and the chunk sizes are choices.
• The 2-D map of chapter 3 is a projection for the eye; neighbours are found in all 384 dimensions.
• Token counts are Qwen2.5's (its tokenizer is vendored), not any other model's.

Accessibility

Every animation has keyboard controls (Space plays or pauses, the arrow keys step), a live caption read out by screen readers, and starts paused when the reader prefers reduced motion. Colours come from Okabe and Ito's colour-blind-safe palette, and nothing is told by colour alone: a relevant chunk is also ticked, a cut answer also hatched.

Source

The site's source is on GitHub (MIT). For the slides behind the retrieval chapters, see the RAG and retrieval series.