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.
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 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
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 engineering | Context engineering | |
|---|---|---|
| Scope | The instructions | The whole window: instructions, tools, documents, memory, history |
| Unit of work | A prompt | The state the model sees at one step |
| Lifecycle | Written, then tuned | Curated again on every call |
| Debugging | Reword and retry | Ask 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.
| Failure | What happens | Usually comes from | Typical fix |
|---|---|---|---|
| Context rot (too much) | Recall degrades as the window fills | History, tool results | Summarize old turns, clear stale tool output, restart |
| Poisoning | An error enters the context and keeps being reused | History, a wrong stored memory | Correct or remove the bad entry; start clean |
| Distraction | The model over-focuses on a long context | History | Compress, select what matters |
| Confusion | Irrelevant content lowers answer quality | Too many tools, noisy retrieval | Prune tools, retrieve less |
| Clash | New information conflicts with what is already there | Memory vs a new instruction, two documents | Decide 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.
- Write what matters outside the window: notes, instruction files, saved memory. Anthropic calls this structured note-taking.
- Select only what is relevant for this step, by retrieving just in time instead of loading everything up front.
- Compress what is old: summarize a long thread, drop tool output you no longer need. Anthropic calls one form of this compaction.
- 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.
Durable memory → Select → Context window → Model
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.
- Pick a task you repeat and note when answers go wrong: early, or only deep into a long thread.
- List what loads into a typical session: instructions, tools, memory, files.
- Trim instruction files. Remove anything the model does without being told and anything you never check.
- Remove tools you do not use. Merge ones with overlapping purposes.
- Move durable facts out of the chat and into memory or a notes file.
- Read your stored memory. Fix anything wrong, stale or duplicated.
- Retrieve documents on demand instead of pasting them in up front.
- Summarize or restart long threads before they drift. Start a clean one for an unrelated task.
- 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§
- Anthropic, Effective context engineering for AI agents, 29 September 2025.
- LangChain, Context engineering for agents, 2 July 2025.
- Simon Willison, Context engineering, 27 June 2025.
- Drew Breunig, How Long Contexts Fail, 22 June 2025.
- Chroma, Context Rot, 14 July 2025.
- Claude Code documentation, How Claude remembers your project.
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 →