Context engineering: what it is, where memory fits, and a practical checklist

Context engineering explained: where the term came from, the parts of a context, how it fails, where durable memory fits, and a checklist for ten minutes.

The Esment Team

In short

  • Context engineering is deciding what goes into a model's context window at each step: instructions, tools, retrieved documents, memory, tool results and history. Prompt writing is one part of it.
  • The term was popularized in June 2025, not invented by one person. Anthropic, LangChain and Thoughtworks have since written it up as a discipline.
  • More context is not better context. Named failures are rot, poisoning, distraction, confusion and clash. Each has a different fix.
  • Durable memory is one input among several. It fits stable facts and decisions that must be correctable; it does not fit instructions, documents or one-off tool output.

Context engineering is the practice of deciding what a model sees before it answers: its instructions, the tools it can call, documents you retrieve, saved memory, tool results and the conversation so far. Anthropic's definition is curating the optimal set of tokens available to the model at inference time. Writing a good prompt is part of it. Most of the work is everything around the prompt.

It matters most when an assistant does long or repeated work, because that is when the window fills, drifts and starts to contradict itself. This post is the discipline in plain terms, a table of how contexts fail, an argument about where durable memory belongs, and a checklist. For the mechanics of the window itself, see the context window.

Where the term came from§

Nobody invented it. In June 2025 Shopify CEO Tobi Lutke wrote that he preferred "context engineering" to "prompt engineering", and Andrej Karpathy followed with a "+1" and a description of it as the delicate art and science of filling the context window. Simon Willison collected both posts on 27 June 2025 and does not claim anyone coined it. The honest summary is that the term was popularized over a few weeks in June 2025, for a practice many people already had.

In the same weeks Drew Breunig published How Long Contexts Fail, a list of failure modes we use below. LangChain wrote up write, select, compress and isolate on 2 July. Anthropic's Applied AI team published its guide on 29 September. The Thoughtworks Technology Radar listed the technique as Assess in November 2025 and moved it to Adopt in April 2026.

Jun 2025Lutke, Karpathy post22 Jun 2025Breunig: failures27 Jun 2025Willison collects it2 Jul 2025LangChain's four moves29 Sep 2025Anthropic's guideApr 2026Radar: Adopt

Jun 2025: Lutke, Karpathy post; 22 Jun 2025: Breunig: failures; 27 Jun 2025: Willison collects it; 2 Jul 2025: LangChain's four moves; 29 Sep 2025: Anthropic's guide; Apr 2026: Radar: Adopt

A term that spread within weeks and became a named discipline within a year. Dates are from the linked sources.

Context engineering vs prompt engineering§

Prompt engineering is writing and organizing instructions, especially the system prompt. Context engineering is the broader, repeated curation of everything the model sees on each call. Most sources, IBM's explainer included, treat the prompt as a layer inside the larger practice, not something it replaced.

Prompt engineeringContext engineering
ScopeThe instructionsThe whole window: instructions, tools, documents, memory, history
Unit of workA promptThe state the model sees at one step
LifecycleWritten, then tunedCurated again on every call
DebuggingReword and retryAsk what was in the window, and what should not have been

The last row is the useful one. When an answer is wrong, the question stops being "how should I phrase this" and becomes "what did the model actually have in front of it".

The parts of a context§

Every context is assembled from the same five kinds of input. They differ in who writes them, how long they live, and how they go wrong.

  • Instructions. The system prompt and instruction files such as CLAUDE.md or AGENTS.md. Written by you, loaded each session, and treated by the model as context, not as enforced rules.
  • Memory. Facts and decisions that outlive one conversation: your preferences, a project's constraints, what was decided and why.
  • Retrieved documents. Material pulled in for this task: files, notes, search results. It should arrive when needed and leave when not.
  • Tool results. What a tool call returned: command output, a file read, a query result. Often long, often needed once.
  • History. The conversation so far, including your corrections and the model's earlier mistakes.

Tool definitions sit beside these, since they also occupy the window. Anthropic's guide warns against bloated tool sets with overlapping purposes. A rough rule: instructions and memory should be small and stable, while documents and tool results should be large and short-lived. Most context problems come from a part living in the wrong place.

Why more context makes things worse§

The instinct is to add more, because a larger window feels safer. The evidence points the other way. Anthropic calls the effect context rot: recall accuracy declines as the window fills, so each added token spends part of a limited attention budget. Chroma's Context Rot report, from July 2025, tested 18 models, including GPT-4.1, Claude 4 and Gemini 2.5, and found performance becomes less reliable as input length grows, even on simple tasks.

So the goal is not the fullest window but the smallest set of tokens that makes the right answer likely. That is a design constraint, not a limit you wait for a bigger model to remove. For Claude Code specifically, what fills Claude Code's context walks through the parts and what each costs.

How context fails: five named failures§

Breunig named four failure modes. Add context rot and you have a map you can debug against. The "typical cause" and "typical fix" columns below are our own mapping onto the five parts, to organize the ideas. They are illustrative, not taken from one source.

FailureWhat happensUsually comes fromTypical fix
Context rot (too much)Recall degrades as the window fillsHistory, tool resultsSummarize old turns, clear stale tool output, restart
PoisoningAn error enters the context and keeps being reusedHistory, a wrong stored memoryCorrect or remove the bad entry; start clean
DistractionThe model over-focuses on a long contextHistoryCompress, select what matters
ConfusionIrrelevant content lowers answer qualityToo many tools, noisy retrievalPrune tools, retrieve less
ClashNew information conflicts with what is already thereMemory vs a new instruction, two documentsDecide which wins; the newer fact usually should

In plain terms, three of them are about too much (rot, distraction, confusion) and one is about conflict (clash). Poisoning is the nastiest, because a wrong fact that persists is worse than a missing one.

Four moves: write, select, compress, isolate§

LangChain groups the fixes into four moves, and Anthropic's techniques map onto them.

  1. Write what matters outside the window: notes, instruction files, saved memory. Anthropic calls this structured note-taking.
  2. Select only what is relevant for this step, by retrieving just in time instead of loading everything up front.
  3. Compress what is old: summarize a long thread, drop tool output you no longer need. Anthropic calls one form of this compaction.
  4. Isolate separate tasks in their own clean context, for example with sub-agents that return a short result.

Notice that "write" and "select" both depend on something durable existing outside the window. That is where memory comes in.

Where durable memory fits, and where it does not§

A context window is temporary. IBM's explainer notes that LLMs and the agents built on them have no long-term memory, so the window acts as short-term memory and continuity has to be engineered. Claude Code shows the pattern: each session starts with a fresh window, and CLAUDE.md files and auto memory carry knowledge across sessions. Durable memory decides what is available to select into context at all.

Durablememorystoredoutside anychatSelectchosenonly whatappliesContextwindowreadModel

Durable memory → Select → Context window → Model

Memory is a store, not part of the window. Selection decides what crosses over on each call.

Memory is the right home for things that are stable, small and correctable: that Alex Rivera, a product designer in Lisbon, prefers metric units and short answers; that Sam Okafor owns the billing service; that the team chose a queue over polling last month, and why. These are facts you would otherwise re-explain, and each one can be wrong later.

It is the wrong home for several things:

  • Instructions. Rules you want followed belong in an instruction file, kept short. Claude Code's docs recommend under 200 lines per CLAUDE.md, since longer files use more context and reduce adherence. Neither CLAUDE.md nor memory is enforced; to block an action, use a hook.
  • Documents. A spec or a codebase is retrieved when needed. Copying it into memory makes it stale the day it changes.
  • Tool results. Command output is for this step. Saving it clutters memory with things nobody will check.
  • Transcripts. A summary of a decision beats a thousand words of chat.

Memory also adds its own failures. A wrong fact can poison every future session, and an old fact can clash with a new instruction. So memory needs three properties: you can read it, you can correct it, and a newer fact can replace an older one. For the broader case, see long-term memory for AI agents, why assistants need memory, and CLAUDE.md vs a memory server for the instruction-file comparison. For a working example of loading memory into a session, see Claude Code hooks for memory, and for how memory answers go wrong even when search works, why AI memory answers fail.

A context engineering checklist you can run in ten minutes§

Run this against one task you repeat. Change one thing at a time so you can tell what helped.

  1. Pick a task you repeat and note when answers go wrong: early, or only deep into a long thread.
  2. List what loads into a typical session: instructions, tools, memory, files.
  3. Trim instruction files. Remove anything the model does without being told and anything you never check.
  4. Remove tools you do not use. Merge ones with overlapping purposes.
  5. Move durable facts out of the chat and into memory or a notes file.
  6. Read your stored memory. Fix anything wrong, stale or duplicated.
  7. Retrieve documents on demand instead of pasting them in up front.
  8. Summarize or restart long threads before they drift. Start a clean one for an unrelated task.
  9. Re-run the task and compare the result with step 1.

Two habits help beyond the list. When something goes wrong, ask "what was in the window" before rewording the prompt. And write down the fix: a correction that lives only in the chat will be gone next session.

Further reading§

Questions, answered§

What is context engineering in simple terms?

It is the work of choosing what a model sees before it answers. That includes your instructions, the tools it can call, documents you retrieve, saved memory, and the conversation so far. Anthropic describes it as curating the best set of tokens available at inference time.

Who coined the term context engineering?

No single inventor is documented. The term spread in June 2025, when Shopify CEO Tobi Lutke said he preferred it to "prompt engineering" and Andrej Karpathy added a "+1", as Simon Willison recorded on 27 June 2025. "Popularized" is accurate; "coined" is not.

Is context engineering the same as prompt engineering?

No. Prompt engineering is writing and organizing instructions. Context engineering covers everything the model sees, including tools, external data and message history, and it is repeated on every call. Most sources treat prompts as one layer inside it.

Is context engineering just RAG?

No. Retrieval fetches knowledge, and it is one input. Context engineering decides the whole set of what the model sees at once, including instructions, tool results, memory and history. Retrieval done badly can itself fill the window with noise.

What is context rot?

Context rot is the decline in a model's recall as its window fills. Anthropic uses the term in its September 2025 guide, and Chroma's July 2025 report tested 18 models and found performance becomes less reliable as input grows, even on simple tasks.

How do I start with context engineering?

Audit what loads into a typical session, trim instruction files, remove tools you never use, move durable facts out of the chat, restart or summarize long threads, and test changes on a task you repeat. Change one thing at a time so you can see what helped.

Pass it on →

Keep reading

all posts →
Agents & context8 min

AGENTS.md vs CLAUDE.md: what it is, who reads it, and how to use both

AGENTS.md explained: what it is, which coding agents read it, how it differs from CLAUDE.md, how to keep one file, a copyable template, and why it isn't memory.

#AGENTS.md #CLAUDE.md
Agents & context8 min

Claude Code hooks for memory: load a brief, save notes, survive compaction

Use Claude Code hooks to add memory: load a brief at SessionStart, save notes at PreCompact and SessionEnd, re-inject after compaction. Scripts included.

#ClaudeCode #memory
Esment Lab8 min

Why AI memory answers fail: retrieval or reading?

We read the wrong answers from Esment's memory search. Most had the evidence in front of the model, which points at how memories get written, not found.

#memory #retrieval

a note for you

New posts, by email.

Fixes, guides and Lab notes on AI memory — about two a month. No product news, unsubscribe in one click.

Or follow the RSS feed