Context From First Principles

A context window tells us how much a model can receive. Context engineering decides what it should receive, in what form, in what order, and what must be left out.

Imagine an AI coding agent working inside a mature project.

It can see the conversation. The repository contains thousands of files. The project has instructions, architecture notes, tests, issue history, tool definitions, previous attempts, summaries, memories, search results, plans, and state accumulated over hours of work. The model can technically accept a very large prompt.

What should the system send?

One implementation keeps adding material until the window is nearly full. Another identifies the current task, preserves what must survive, removes stale and duplicated material, externalises bulky state, recalls only what becomes relevant, orders the surviving information deliberately, and records exactly what it assembled for the model.

Both systems may use the same model, and both may have access to the same information. They do not have the same context.

That difference is the subject of this book.

The window is not the context

A production AI system can draw on far more information than one model call should contain: system and developer instructions, conversation history, project rules, files, retrieved passages, tool definitions and results, execution traces, plans and hypotheses, summaries, memories, external documents, policies, cached state, and artefacts generated by the agent itself.

A context window defines capacity. It does not decide which information deserves admission, what can safely be removed, whether a summary preserved the fact that later becomes decisive, whether an old plan is stale, or which source wins when two disagree. And it does not tell us whether the resulting context improved what the model did.

Those are context-engineering problems.

A stricter definition

This book keeps several ideas separate.

Available information is everything the system could potentially access.

Session state is information persisted across turns or actions, whether or not it is currently shown to the model.

Context is the information made available to a model for a particular computation.

Context window is the capacity that bounds the invocation.

Context selection decides which candidate information enters.

Context representation decides the form in which admitted information appears.

Context assembly turns admitted information into an ordered, policy-compliant bundle.

Context engineering is the work around all of that: constructing the bounded working set, delivering it to a runtime, and evaluating whether it helped. Context is the noun, and context engineering is the process that has to be shown to work.

The separation matters because a larger window solves only one problem. A system can have abundant capacity and still build poor context. It can include the wrong evidence, preserve stale instructions, bury decisive information among thousands of merely related tokens, compress away a contradiction, retrieve something useful and fail to admit it, present the right information in a form the model does not use well, or let an untrusted source appear more authoritative than a project rule.

So the central question becomes:

Given more potentially useful information than a model can or should consume, what should it see right now?

And the book adds a second question that turned out to matter just as much: how would anyone know what was assembled, whether it arrived, and whether changing it helped?

Each stage can succeed without the next

The chain from information to behaviour has many links, and success at one does not certify the next:

available ≠ eligible ≠ selected ≠ represented appropriately
        ≠ assembled legally ≠ delivered ≠ used ≠ helpful

A context system can construct a structurally legal bundle, deliver it correctly, and still produce no measured improvement. The finished book contains exactly that result, and it shapes how everything else is presented.

Four dimensions instead of one

Chapter 1 describes a context bundle along four dimensions that ordinary practice collapses into one:

capacity        content         representation      time
how much?       which bits?     in what form?       when is it valid,
                                                    useful, or worth
                                                    keeping live?

A large window addresses capacity. It does not address selection, representation, freshness, authority, scope, provenance, ordering or usefulness.

These four are an early decomposition and not the whole architecture. The later chapters add authority, freshness, scope, dependencies, policy, assembly, transport and behavioural evaluation.

They also do not rest on equal evidence. Capacity is documented by providers and the long-context literature. What the book itself tests concerns content, representation and ordering as assembled and delivered, and only on small synthetic cases. Time, and much of what the middle chapters say about it, is argued from the literature and from engineering reasoning.

Time deserves emphasis because it turns a prompt into something else. Context grows, goes stale, is duplicated, is summarised, leaves the live window, is externalised into files, caches, memory or derived state, and sometimes returns. The agent also creates future context through plans, notes, summaries, tool traces and critiques.

Context is therefore not a static prompt. It is a changing working set.

Seven questions instead of a bag of tricks

The investigation is organised around seven practical questions:

1. What did the model actually receive?
2. What information matters to this task?
3. What must survive exactly, and what may be transformed?
4. What can leave the live window?
5. What should come back, and when?
6. How should the surviving information be ordered and represented?
7. Did changing the context change behaviour, and was the change useful enough to justify the machinery?

The sequence matters. Before changing context, observe it. Before compressing, decide what must survive. Before adding retrieval, memory or external storage, identify why information left the live window. Before optimising token count, check whether the cheaper context still supports the same behaviour. And before adding a sophisticated mechanism, demonstrate a failure the simpler system could not solve.

The last question separates influence from utility. A change of behaviour shows that context mattered. It does not show that it mattered for the better.

The method, and what was actually completed

The method is deliberately conservative: build the strongest simple baseline, measure it, stress it, find the failure, diagnose where it occurred, add only the mechanism the diagnosis requires, then rerun the same cases to check that nothing that worked has broken.

observe → baseline → failure → smallest intervention
   → controlled test → ablation → keep, revise or remove

Context engineering is full of plausible mechanisms. Longer windows, caching, pruning, summaries, retrieval, memory injection, structured state, tiered fidelity, externalisation, graphs and policy layers can all sound useful. But usefulness is conditional. A mechanism belongs in the final architecture only if it repairs a demonstrated problem at an acceptable quality, cost, latency, and complexity price.

That is the method the book advocates. It is not a claim that every mechanism completed the loop. Pruning, compaction, fading, externalisation, recall and cache-aware rewriting are argued from the literature and from engineering reasoning, and were not built and tested as separate passes. The book keeps them in the discussion and records them as conditional. Not built is not the same as shown unnecessary. Negative results stay in the argument when they remove machinery, and the system the book arrives at is smaller than the investigation that produced it.

How the evidence is presented

Two separate classifications run through the book, and they answer different questions.

The first is provenance: where does a claim come from? Established background is standard technical fact, taken from primary sources. A book hypothesis is a prediction or mechanism the book proposes to test. A book result is a claim about something we measured, stated with the population it covers and traceable to a frozen artefact.

The second is the evidence boundary: what kind of proposition does the evidence support? Structural evidence concerns whether an artefact satisfies declared constraints. Transport evidence concerns whether the intended artefact reached an observed runtime boundary. Behavioural evidence concerns whether a controlled change in context changed what a model did. Ecological evidence concerns how often any of this occurs in real work.

The text does not print commit hashes, run identifiers or software versions. Each result has a short name, and the identifiers, code revisions and published artefacts behind it are listed in the evidence register in the companion repository. If a later experiment changes what we believe, the text says what we thought earlier and what we think now; the register keeps the history.

More is not automatically better

One of the book’s central claims is intentionally modest:

Making more information available to a model does not guarantee better behaviour.

It is not the claim that more context makes models worse. Additional context can help. The claim is that quantity is an inadequate thing to optimise.

The support comes in layers. Outside the book, controlled studies show that performance can depend on where relevant information sits, and can fall as input length grows or distractors are added, though the size of the effect varies with model, task and test design.¹ Those studies do not show that a given production agent fails in the same way.

The failure modes specific to agents are, for now, engineering reasoning and hypothesis. Duplicate evidence consumes budget. Old plans may compete with current ones. Failed attempts may be read as instructions. A retrieved passage may be topically relevant and operationally useless. A summary may keep the theme and delete the exception. Chapter 5 states the agent-specific predictions as hypotheses.

The book’s own behavioural evidence comes in two small streams. In one, a local reader received frozen bundles on six constructed tasks. Moving from no context to the compiler’s bundle changed every full response and four of six chosen actions, and improved the score on two tasks, worsened it on one and left three unchanged. Several of the comparisons between assemblers turned out to involve identical bundles, and one control task was ambiguous, so those results are case evidence about what a reader did, not a general estimate. In the other, a live wave of 24 runs verified delivery on every run and found no improvement on the measured outcomes. Both are described below.

So token count is not a proxy for useful context. The test that matters is behavioural:

Hold the task and model fixed. Change the context. Does the model behave differently, and is the difference useful?

The context window is a budget

A window is not merely a size limit. It is a budget. Every admitted item consumes some combination of tokens, attention, latency, provider cost, cacheability, and competition with other information, so inclusion has an opportunity cost.

Preserving raw evidence may cost more than a summary but protect a distinction that matters. Inlining a large tool result may simplify access but crowd out source material. Keeping a stable prefix may improve cache economics while constraining how volatile material is arranged.

The engineering problem is not to maximise occupancy. It is to decide what deserves the budget, and a budget is a ceiling and not a target.

Remove before you compress

When context becomes too large, summarisation is an attractive first response. This book treats it as a later one.

Before rewriting information, ask whether it should remain live at all. Duplicates may be removable. Completed work may be retired. Failed branches may be externalised. Stale observations may be invalidated. Bulky artefacts may be replaced by stable references. Only then does lossy compression become the next step.

The ordering matters because the two operations make different claims. Removing irrelevant material can be lossless for the current task. Compression asserts that something can disappear without changing future behaviour, and that assertion needs evidence. A smaller prompt is not evidence that it succeeded.

Compression is information selection

A shorter summary is not automatically a better representation. It can preserve the gist while deleting a contradiction, a numerical constraint, an exception, an unresolved question, a failed attempt that must not be repeated, or the evidence that licenses a conclusion.

So the question is not only how many tokens were saved. It is which information survived, which disappeared, and whether the loss changed behaviour. Some information tolerates aggressive reduction. Some needs structure, some a pointer back to the source, and some must remain verbatim. Not all tokens are equal.

Context can leave without being forgotten

A bounded model input does not require a bounded system. Information can leave the live context while remaining available elsewhere:

Live context is temporary. Accessible state can be durable.

Externalisation creates a second problem. Once information has left the working set, how does the system know whether and when to bring it back? That is why retrieval appears here: not as the definition of context or of memory, but as one way of producing candidates for information that is no longer live. Retrieval identifies and ranks candidates. Context engineering still has to decide whether a retrieved item enters, in what form, under what standing, at what cost and in what order. The book takes only the boundary it needs and does not re-teach retrieval.

Memory is a context source

This book follows Memory From First Principles, but the two problems differ.

Memory asks how retained past experience remains capable of changing present behaviour. Context asks which information and state are actually made available to one execution. A memory system may retain years of project history; a context system decides whether any of it enters this model call.

Memory is therefore a source of context, alongside retrieval, the conversation, tools, files, policy and state the agent generated five seconds ago. Context engineering sits where those sources compete for admission.

The agent writes its own future context

Agentic systems have an unusual property: the model is both consumer and producer of future context. A plan written now may become input later. A summary may replace the messages it was derived from. A hypothesis may persist across tool calls, and a tool trace may become evidence.

context → model action → generated artefact or state
        → future context candidate → later model action

An agent does not merely consume context. It helps create the information environment that later executions consume. Poor context can then reproduce itself: a mistaken summary can outlive the raw evidence it replaced, a speculative plan can acquire authority through repetition, and a derived artefact can stay in circulation after its source changed. Generated context needs the same scrutiny as retrieved context.

Tools work the same way. From the model’s perspective they create context. Definitions consume tokens, outputs can be large and noisy, errors become state, and repeated observations accumulate. A system therefore has to decide which tools to expose, how much schema detail to include, which outputs stay live, and when to reread a source rather than trust an earlier summary. Tools do not only act on the world. They reshape what the model knows about it.

Representation is part of context

The same information can appear as raw prose, quoted evidence, a table, typed state, a graph edge, a structured record, a summary, a diff, or a compact reference. Those forms are not interchangeable. Representation changes token cost, which relationships are explicit, whether provenance survives, what can be omitted by accident, and possibly what the model notices.

Choosing the right source is therefore not the end of the job. The representation has to earn its place. Two distinctions matter. Content identity is not representation identity: one piece of information can have several forms. And those forms are not always substitutes. A summary beside an exact fragment, or an overview beside a pointer, can be complementary and not redundant. The book’s current compiler admits at most one form per content, which is an implementation limitation and not a law.

The book shows that representations differ in what they preserve and cost, and shows a compiler choosing among them under a policy floor. It does not establish, beyond small cases, which form a model uses best, and it treats numeric representation ranks as policy and not as a universal fidelity ladder.

Authority, freshness, and scope

Once several sources are assembled, relevance stops being enough. A retrieved document may be on topic and belong to the wrong project. A memory may preserve a decision since reversed. A tool result may contradict a cached summary. A project rule may conflict with an old conversation. A plan may complete, a dependency version may move, or the user may change direction.

The system needs enough provenance and policy to ask: where did this come from, is it raw evidence or derived interpretation, is it still valid, what scope does it belong to, which source has standing when two claims conflict, and can the original be reopened?

Authority, freshness and scope are therefore separate admission constraints and not extra relevance features. A richer judgement is projected upstream into a verdict, and the compiler enforces the verdict it is given. It does not discover whether a source is authoritative, current or in scope. The book’s builder implements narrow projections for the source classes it tests: scope by equality, freshness from a supplied status, authority from a source-class table. Those are policy, not truth verified against a real repository, and that is where the book’s open problem lies.

From information to a context bundle

By the later chapters, the central chain becomes explicit:

available information
      ↓
observations           (typed records, normalised)
      ↓
candidates             (forms of each, with projected judgements)
      ↓
Context Compiler  ←  request and policy
      ↓
bundle + decision trace        (or a named refusal)
      ↓
render and transport envelope
      ↓
runtime adapter injects it
      ↓
host model-context boundary
      ↓
separate read-only observer, and reconciliation
      ↓
- - provider and model path: not directly observed - -
      ↓
behaviour
      ↓
external evaluation

Every arrow can fail. Useful information may never become a candidate. A good candidate may be rejected. A stale candidate may be admitted because someone said it was fresh. A legal bundle may never reach the runtime, or may reach it twice. The model may ignore information that survived every earlier stage. The final answer may look correct while depending on the wrong evidence.

The candidate builder sits at the front. It does not discover sources. It takes typed records that a caller supplies, normalises them into observations, generates deterministic forms of each (a full text, a lossy truncation, an anchor, a pointer) and attaches the judgements the compiler needs. Discovery, observation, representation and eligibility projection are four different things.

The observation point sits at the host’s model-context boundary. The book did not capture the provider request, and it cannot see inside the model. Observed host context is not the provider request, and neither is evidence of model use.

Success at one stage does not certify the next. A correct answer does not show that every earlier stage worked. A correct bundle does not show delivery. Delivery does not show use, and use does not show benefit. Benefit on a benchmark does not show that the mechanism matters in real work.

That is why the book measures the path rather than scoring only the final output, and why it keeps apart the kinds of evidence each stage allows.

The Context Compiler

The middle of that chain is a Context Compiler, and the name is meant narrowly.

A compiler does not dump its entire input universe into the target. It takes defined input, enforces constraints, and emits a specific artefact for a specific execution, or refuses with a reason.

request (budget, active scope)
+ candidates (representations with costs, eligibility
              judgements, requirements, dependencies)
+ policy
        ↓
CONTEXT COMPILER
        ↓
ContextBundle + DecisionTrace     or     CompileFailure

The compiler decides membership, representation and order for one computation. It is deterministic. It enforces scope, freshness, authority and representation floors as hard gates, and it may refuse.

It does not discover scope, freshness or authority. It does not write summaries, decide whether a summary is faithful, or judge whether an answer was useful.

Three questions about a compiler need separate evidence. Soundness asks whether a returned bundle satisfies the enforced constraints. Completeness asks whether, if a legal bundle exists, the procedure finds one. Optimality asks whether it finds the best among legal bundles. The book’s evidence is uneven across them. The compiler matched its fixture expectations on all 42 conditions of a finite synthetic corpus, 34 expected successes and 8 expected refusals. That is conformance to a finite corpus, not completeness beyond it, and a constructed counterexample shows the greedy procedure can refuse a request for which a legal bundle exists. A refusal from the current compiler therefore does not prove infeasibility. Optimality is not claimed. Deterministic does not mean correct, and a second implementation that agreed with the first also reproduced its defects.

The compiler is where the book’s construction argument converges. Each of its rules is introduced as the answer to a failure the earlier chapters showed. The final chapters then ask what that construction proves, whether the artefact actually arrived, and whether changing it changed behaviour.

The current investigation

The book has twenty-seven chapters in five parts, and they follow one progression: see, reduce, externalise and recover, govern, compile, deliver, observe, evaluate.

Part I, see the thing (Chapters 1 to 7). Define context, observe what a model receives, and learn what capacity, order and the different natures of information demand.

Part II, capacity and reduction (Chapters 8 to 12). The main responses to a bounded window: a larger one, caching, pruning, compression, and fidelity that fades gradually.

Part III, context outside and around the window (Chapters 13 to 18). Externalisation and recall, the agent’s own generated state, memory, tools, and representation.

Part IV, govern (Chapters 19 to 21). Authority, freshness and scope: the judgements that decide whether a candidate may be considered at all.

Part V, compile, deliver, prove (Chapters 22 to 27). Why ranking is not assembly, the compiler that assembles, what a compilation does and does not prove, whether the result reached the observed boundary, whether it helped, and what the whole system looks like.

The four kinds of evidence are kept apart, and their state at the end of the book is uneven.

Structural evidence concerns the bundle as an artefact: membership, order, representation, budget compliance and determinism. It has a finite synthetic corpus, a separate checker that shares assumptions with the compiler, a second implementation that reproduced the first’s defects, and a completeness counterexample. It says nothing about whether a model received or used the bundle.

Transport evidence shows that the intended artefact reached an observable runtime boundary. It rests on one historical qualification for an earlier configuration, an instrumentation failure, and a later verified wave. It does not reach past the host boundary and does not show that the model relied on anything.

Behavioural evidence shows that changing the context changed measured behaviour under stated conditions. It has six constructed direct-reader tasks and a verified live null result. It does not show general usefulness.

Ecological evidence would show how often any of this matters in real use. The book has none: its corpus of real sessions is empty, and the final chapter says so.

Most of the mechanisms in Chapters 8 to 21 are argued from the literature and have not had their own experiment. What has evidence is uneven: a stronger structural core, narrow transport evidence, small behavioural case evidence, and no ecological evidence.

Two things are being built

The book builds a context runtime, and it builds the instrument required to distrust that runtime. A system cannot show that its context arrived by asking the component that delivers it.

The instrument begins before the advanced architecture does. A read-only observer records the context the host assembles for the model: the system material, messages, tool definitions and their order. It is a separate code path that never modifies what it reads, and it is not a separate failure domain, because it lives in the same package, process and hook framework as the component that injects. Alongside it, the experiment harness records the outcomes, token counts and grades of what the model did, and compares them when context is removed, restored, reordered, compressed or replaced.

The limits are stated. The observer sees what the host assembles for the model. It does not see authority, scope, repository state, provider-side rewriting or cache decisions, and it does not reach the model.

The reader meets that instrument as the Context Viewer, which develops alongside the Context Compiler through the book. It begins in Chapter 1 as a way to see what occupies an observed context, and gains one capability per chapter — budgeting, ordering, compression loss, freshness, compiler decisions, delivery verification, behavioural evidence — until Chapter 27 brings the whole lifecycle together. Every published figure is generated from the same scene data as its interactive example, and every scene states what was measured, what was inferred, what was simulated, and what remains unknown. The Viewer answers what was available, what was selected, what changed, what was observed, what might be wrong, and what evidence supports that conclusion. It does not answer whether the Compiler improves behaviour; that still requires controlled evaluation.

The book contains both kinds of failure needed to see a distinction that is easy to blur. A first live wave of 24 runs executed while its observer was not live, and it produced no valid observation on any run. Its pre-run checks had verified identities, versions and digests, all of which passed while the live path was dead. A silent instrument cannot show that a treatment was present or absent, so that wave supports no behavioural conclusion in either direction.

The lesson was applied. In a later wave of 24 runs, over eight fixtures each under no context, a matched distractor and the exact minimal evidence, liveness gates and per-run reconciliation verified transport on every run: absence in the no-context runs and the expected block exactly once in the others. The task score was zero out of eight under every condition, the evidence-use measure was zero under every condition, and the harm flag fell on the same two tasks in each. The scores sat at a floor, so the wave could not have shown a decline either. That is a valid, bounded null result on the measured outcomes for this reader, these fixtures and this instrument. It does not show that context has no effect.

executed inference + unverified treatment  =  no valid conclusion
executed inference + verified treatment + unchanged outcomes  =  a bounded null

A failed experiment and a negative result are different things, and the manipulation check is what separates them.

When the book claims that a mechanism helps, the claim is tied to behaviour and not to token count, and is limited to what the evidence covers.

What you should be able to do after reading

The aim is practical. By the end you should be able to look at the context of your own system, build small tools that improve it, and design the context for a task deliberately rather than by accumulation. The chapter notebooks are a place to start building.

You should also be able to ask harder questions than how large is the context window? What did the model actually receive, and what was available but excluded? Why did one item enter and another stay out? What had to survive exactly, and what did a transformation lose? What left the live context but stayed recoverable, and why did something return? What did the agent generate, what became stale, and what crossed a scope boundary? Which source had authority when two disagreed? Did changing the context change behaviour, did that help, and which parts of the architecture are measured results rather than attractive ideas?

Those questions turn context engineering from prompt craft into systems engineering.

The larger idea

The deeper argument is not that prompts should be shorter or longer, or that every system needs retrieval, memory, summaries or a giant window. It is that the bounded working state of one execution should be treated as something deliberately constructed from a larger information world, delivered through an observable runtime path, and evaluated at the boundary where its effects are actually claimed.

That construction has to decide what enters and what stays out. It has to preserve distinctions that matter, and keep stale or out-of-scope information from acquiring accidental influence. It has to move information out of the live window without making it irrecoverable, and bring it back without flooding the model. It has to preserve provenance and authority when sources compete, and respect a budget without mistaking fewer tokens for better context. And it has to be delivered and tested for whether it made the model behave better.

The destination is a system that can answer a more demanding question:

What information should be allowed to influence this computation, in what form, under what constraints, and what evidence would show that the choice helped?

Sometimes the answer will be a raw source passage, a structured record, a tool result, a memory, a compact reference, a summary or an instruction. Sometimes it will be nothing at all. The value is not in giving the model everything, and it is not simply in giving it less. It is in giving it the right information, in the right form, with the right standing, at the right moment, and being able to show why: what entered, what did not, in which representation, at what cost, whether it reached an observed boundary, and whether changing it changed behaviour.

The book is candid about how much of that is established. It demonstrates deterministic bundle construction on a finite synthetic corpus, records narrow transport evidence at the host model-context boundary, and reports both direct-reader case evidence and a verified live null result. It does not establish general behavioural benefit, the truth of the judgements that feed the compiler, or how often any of these failures occur in real work. Building trustworthy candidates in the first place, and showing that any of it matters on real workloads, are open.

The achievement is not a recipe for the perfect context. It is a way to separate the stages of context engineering so that each can be inspected, measured and falsified at the boundary where its claim is made.

Context engineering begins when a larger window stops being an answer.

Continue with What Context Means.

References

• Project Context evidence register (companion repository, evidence/README.md). Every measured result the book cites, by short name; identifiers, code revisions and artefact digests are held there and not in the text. The results referred to in this introduction are Compiler construction, Implementation parity, Instrumentation failure, Matched behaviour, Reader-transfer probe and Oracle leverage requalified run. The Live compile-to-observe qualification and the Earlier runtime qualifications are the transport results behind the transport claims. The completeness counterexample and the finite feasibility audit are exploratory and not yet frozen in the register.