Most AI agents fail because their builders treat context as one thing. It is four things. Identity is who the agent is. Knowledge is what it knows. State is what just happened. Task is what it is doing right now. Each layer lives in a different place. Each layer needs a different update cadence. The Context Pyramid is the framework that maps all four.
The four layers
Each layer answers one question. Each lives in a specific surface. Each has its own update cadence. Mix the cadences up and the agent rots.
| Layer | The question it answers | Lives in | Update cadence |
|---|---|---|---|
| Identity | Who is this agent? | System prompt | Updated rarely |
| Knowledge | What does it know? | RAG, files, semantic memory | Updated occasionally |
| State | What just happened? | Context window, scratchpad | Updated per turn |
| Task | What is it doing right now? | Current prompt | Updated per task |
Source: Product with Attitude. The Context Pyramid framework, May 2026.
The diagnostic loop
When an agent misbehaves, the symptom tells you which layer to fix. Seven steps. One layer per pass.
| Step | Action | Why |
|---|---|---|
| 1 | Reproduce the failure | Capture the prompt, the output, and the session history. No diagnosis without a reproducible trace. |
| 2 | Classify the symptom | One symptom maps to one layer. Identity, Knowledge, State, or Task. |
| 3 | Off-character or breaks rules → fix Identity | Wrong role, wrong tone, ignored guardrails. Patch the system prompt. |
| 4 | Makes things up or misses recent facts → fix Knowledge | Hallucinations, stale data, missing documents. Update RAG, files, or semantic memory. |
| 5 | Forgets what just happened → fix State | Lost thread, repeated questions. Compact the context window or write a session summary. |
| 6 | Solves the wrong problem → fix Task | Right knowledge, wrong target. Rewrite the current task prompt with constraints and success criteria. |
| 7 | Verify the fix, log the layer | Re-run the original prompt. Log which layer you patched. The log becomes your debug history. |
Frequently asked questions
What is the Context Pyramid?
The Context Pyramid is a four-layer framework for AI agent context engineering: Identity, Knowledge, State, and Task. Each layer answers a different question about what the agent needs, lives in a different place, and is updated on a different cadence.
How is the Context Pyramid different from a system prompt?
A system prompt is one layer — Identity. The Context Pyramid adds three more: Knowledge (what the agent knows), State (what just happened), and Task (what it is doing right now). Treating the system prompt as the whole context is the most common reason agents fail in production.
Which layer should I update first when an agent misbehaves?
Match the symptom to the layer. Off-character outputs map to Identity. Hallucinations or stale facts map to Knowledge. Forgotten thread or repeated questions map to State. Solving the wrong problem maps to Task. The Diagnostic Loop on this page formalises the mapping.
Where does RAG fit in the Context Pyramid?
RAG is one mechanism inside the Knowledge layer. The Knowledge layer is the abstract layer — what the agent knows. RAG is the implementation that fetches relevant documents from a vector index at query time. Other Knowledge implementations include semantic memory, attached files, and structured databases.
Why are cadences part of the framework?
Most context engineering frameworks ignore update frequency. The Context Pyramid maps each layer to its update cadence — Identity rarely, Knowledge occasionally, State per turn, Task per task — because the right cadence is what stops context rot and context window bloat.
Is the Context Pyramid an engineering framework or a product framework?
It is a product framework first, engineering framework second. Existing context engineering frameworks were written for engineers and ignore the product question of which context belongs where. The Context Pyramid is built for the AI PM deciding what context an agent needs and how often.
How does the Context Pyramid relate to Karpathy's context engineering?
Andrej Karpathy named context engineering as the discipline of designing what goes into the context window. Anthropic's engineering blog expanded it to multi-agent state. The Context Pyramid is the PM-shaped synthesis of both — four layers, four cadences, one diagnostic loop, with credit to both prior sources.