flowchart LR
  SYS["System + instructions"] --> WIN
  TOOL["Tool definitions"] --> WIN
  RAG["Retrieved docs
ranked"] --> WIN
  HIST["Conversation history"] --> WIN
  USER["User's new message"] --> WIN
  WIN["🪟 Context window
one flat token string"] --> M{"Model"}
  M --> OUT["Output
needs room too"]
  classDef in fill:#DCEBFE,stroke:#1F2937,color:#0E1726;
  classDef win fill:#D6F5E3,stroke:#1F2937,color:#0E1726;
  classDef m fill:#EEE6FF,stroke:#1F2937,color:#0E1726;
  class SYS,TOOL,RAG,HIST,USER in;
  class WIN win;
  class M m;
        

context engineering = deciding the contents of that one box

every one of these gets worse as you add tokens, not better

If retrieved context is eating the whole bar, you're retrieving too much, or not ranking it. That's the rest of tonight.

// text → vector → compare by angle, not keywords
const a = await embed("cancel my flight");
const b = await embed("how do I get a refund?");

cosine(a, b); // 0.82 — close in meaning, 0 words shared

function cosine(u, v) {
  const dot = u.reduce((s, x, i) => s + x * v[i], 0);
  return dot / (norm(u) * norm(v)); // 1=same, 0=unrelated
}

a vector DB just stores these and finds the nearest points fast

flowchart LR
  Q["Query"] --> RW["Rewrite / expand
optional"]
  RW --> H(("Hybrid
retrieve"))
  H --> RR["Re-rank
keep best few"]
  RR --> AS["Assemble window
dedup, order, trim"]
  AS --> M{"Model"}
  M --> A["Grounded answer"]
  classDef s fill:#DCEBFE,stroke:#1F2937,color:#0E1726;
  classDef m fill:#EEE6FF,stroke:#1F2937,color:#0E1726;
  class RW,RR,AS s;
  class M m;
        

// ❌ Naive RAG — embed, top-k, stuff, hope
async function answer(query) {
  const qvec  = await embed(query);
  const hits  = await vectorStore.search(qvec, { topK: 8 });
  const ctx   = hits.map(h => h.text).join("\n\n");
  return llm(`Context:\n${ctx}\n\nQuestion: ${query}`);
}
// No keywords → misses exact terms (codes, names).
// No re-rank → dumped in raw similarity order.
// No trim    → whatever 8 chunks weigh, that's your bill.

every comment is a stage we're about to add

flowchart TB
  Q["Query"] --> D["Dense / vector
semantic match"]
  Q --> S["Sparse / BM25
exact keyword"]
  D --> F(("Fuse
+ dedup"))
  S --> F
  F --> R["Ranked candidates"]
  classDef a fill:#DCEBFE,stroke:#1F2937,color:#0E1726;
  classDef b fill:#D6F5E3,stroke:#1F2937,color:#0E1726;
  class D a;
  class S b;
        

Pure vector search silently fails on "error code E-4021" or "the Q3 Whitfield contract." Keywords save you there.

function rrf(lists, k = 60) {
  const score = new Map();
  for (const list of lists)
    list.forEach((doc, i) =>
      score.set(doc.id, (score.get(doc.id) ?? 0) + 1 / (k + i + 1)));
  return [...score].sort((a, b) => b[1] - a[1]);
}

const dense  = await vectorStore.search(await embed(query), { topK: 50 });
const sparse = await bm25.search(query, { topK: 50 });
const fused  = rrf([dense, sparse]); // one ranked, de-duped list

default to hybrid; drop a lens only when you've proven you don't need it

function chunk(doc, { size = 800, overlap = 120 } = {}) {
  const sections = splitOnHeadings(doc.markdown); // semantic units first

  return sections.flatMap(sec =>
    slidingWindow(sec.text, size, overlap).map(text => ({
      text,
      meta: {                        // travels with the chunk everywhere
        title:   doc.title,
        section: sec.heading,
        url:     doc.url,
        updated: doc.updatedAt,      // lets you break "clash" ties by recency
      },
    })));
}

overlap keeps a fact and its context from landing in different chunks

flowchart LR
  Q["Query"] --> RET["Retrieve top 50
high recall"]
  RET --> RANK["Re-rank by relevance
cross-encoder / LLM"]
  RANK --> TOP["Keep top 5
high precision"]
  TOP --> W["Into the window"]
  classDef s fill:#DCEBFE,stroke:#1F2937,color:#0E1726;
  classDef ok fill:#D6F5E3,stroke:#1F2937,color:#0E1726;
  class RANK s;
  class TOP,W ok;
        

Recall in the first stage, precision in the second. Skipping the re-rank is the single most common RAG mistake.

const cands  = fused.slice(0, 50);                   // recall from hybrid
const scored = await reranker.rank(query, cands); // precision: cross-encoder
scored.sort((a, b) => b.score - a.score);

let budget = 2000, picked = [];               // token budget for context
for (const c of scored) {
  if (c.score < 0.2) break;                    // relevance floor — drop the tail
  const t = countTokens(c.text);
  if (budget - t < 0) break;                 // stop at budget, never overflow
  picked.push(c); budget -= t;
}
// picked = the minimum sufficient context, in ranked order

a relevance floor AND a token cap — whichever hits first wins

build a 20-question gold set now; it pays for itself by Thursday

flowchart LR
  Q["Question"] --> M{"Model
need to look it up?"}
  M -- yes --> SR["Search + read"]
  SR --> M
  M -- "enough" --> A["Grounded answer"]
  classDef m fill:#EEE6FF,stroke:#1F2937,color:#0E1726;
  classDef ok fill:#D6F5E3,stroke:#1F2937,color:#0E1726;
  class M m;
  class A ok;
        

const tools = [{
  name: "search_docs",
  description: "Search the knowledge base. Call again to follow up.",
  input_schema: { type: "object", properties: { query: { type: "string" } } },
}];

let messages = [{ role: "user", content: question }];
for (let hop = 0; hop < 4; hop++) {        // cap the loop — cost is unbounded
  const res = await llm({ messages, tools });
  if (!res.tool_calls) return res.text;    // model says it has enough
  for (const call of res.tool_calls) {
    const docs = await search(call.args.query); // your hybrid+rerank pipeline
    messages.push(toolResult(call.id, docs));
  }
}

the search tool is everything you just built — reused, not thrown away

function buildContext(history, facts) {
  const recent = history.slice(-6);              // last 6 turns, verbatim
  const older  = history.slice(0, -6);
  const brief  = older.length ? summarize(older) : ""; // compress the rest

  return [
    systemPrompt,
    facts.length && `Known facts:\n${facts.join("\n")}`, // externalized memory
    brief && `Earlier, in brief:\n${brief}`,        // summarized memory
    ...recent,                                    // working memory
  ].filter(Boolean);
}

summarize runs in the background; a turn never waits on it