Context engineering is the practice of deciding what an AI agent can see, when it can see it, where that information came from, and how long it remains valid. The prompt is one input. The operating context also includes durable records, the current task, tool results, policy constraints, prior decisions, and the evidence needed to explain an action later.
That distinction becomes concrete as soon as an agent works across real systems. A useful answer may depend on a customer record, a recent approval, a rule captured weeks ago, and the live state of a tool. Loading everything creates noise and accidental disclosure. Loading too little produces confident work from an incomplete picture. Context engineering is the discipline that keeps those two failure modes visible.
The goal is a context packet with a reason for every item. Each item should have an owner, a source, a scope, and a point at which it becomes stale. When the system cannot establish those properties, the gap should travel with the task. Silence turns missing context into false certainty.
What context engineering controls
Good context engineering answers a small set of hard questions before execution begins. Which business or person owns the information? Which records are relevant to this task? Which source is authoritative for the claim being made? What may the agent carry into another room or session? What should be fetched live because a stored copy can drift?
These questions shape behavior more than a polished instruction block. An agent can follow a beautiful prompt and still fail because it used yesterday's state, crossed a client boundary, or treated an old summary as live evidence. The context layer has to make those mistakes difficult.
A practical context packet usually contains several kinds of material:
- The task contract states the requested outcome, allowed changes, and forbidden actions.
- Durable memory supplies stable preferences, decisions, and lessons that should survive a session.
- Live evidence covers current state from the system that owns it.
- Policy context explains which actions need approval and what must be recorded.
- Working notes hold temporary reasoning that can expire when the task ends.
The categories matter because they age differently. A communication preference may remain valid for a long time. A delivery status can change while the agent is reading. A tool result may be authoritative for one channel and irrelevant to another. Context engineering gives each category its own handling rule.
Context engineering starts with boundaries
The first design problem is isolation. A system serving several businesses, clients, or personal domains needs explicit walls between them. Retrieval should begin inside the correct scope. Cross-scope access should happen only when the task contract calls for it and the policy layer permits it.
This sounds administrative until a realistic task arrives. Imagine a request to prepare a customer update. The agent may need the current order state, the approved communication style, and the latest conversation. It has no reason to load accounting records from another business or private notes about the owner. A broad search can produce relevant-looking material from the wrong domain. A scoped search removes that possibility before ranking begins.
Boundaries also improve quality. Smaller, well-owned collections contain fewer misleading near-matches. The agent spends less attention rejecting irrelevant text. Review becomes easier because the evidence trail shows where each item came from.
Start with ownership, then retrieval. A sophisticated ranking method cannot repair a collection that mixes unrelated domains.
Durable memory and working context serve different jobs
Working context is assembled for the current task. Durable memory exists so a verified lesson or decision can constrain future work. Combining them into one undifferentiated transcript makes retention accidental. Some details disappear when the session closes, while temporary guesses may linger far longer than they deserve.
A durable memory record should be narrow enough to retrieve by meaning and clear enough to review without reconstructing an old conversation. It needs a descriptive name, a reason it matters, and links to related records. The source should remain identifiable. If a record expresses a policy, the policy owner and approval status should be visible too.
Gevurah's frozen source of record describes 867 durable records, 1,315 links, and 2,942 indexed chunks across 751 files. Those figures show the shape of the problem. A memory layer quickly becomes a network, and navigation depends on structure. Dumping the same material into a larger prompt would remove ownership and make updates hard to trace.
The practical question is simple: will another agent need this fact after the current session ends? If yes, store it in a durable, scoped record after verification. If no, keep it in the working packet and let it expire.
For a deeper view of the storage and retrieval design, read the persistent memory layer.
Retrieval needs an honest fallback
Retrieval systems fail in ordinary ways. A service times out. An index lags behind the files. A query returns a plausible match from an old record. Context engineering must specify what happens next, since the fallback becomes part of the system's behavior.
The current memory record exposes a useful example. Live queries fall back to lexical ranking after a 30 second timeout against a process that takes 33 seconds. The honest description is degraded retrieval. Calling that path semantic search would hide the actual state from both the operator and the agent.
A safe fallback has three properties. It announces that the preferred path failed. It preserves the scope and access rules of the original request. It labels the returned evidence so downstream work can judge its strength.
Fallbacks should reduce confidence. They should never create the appearance that the primary system succeeded. If a task depends on a precise relationship or a recent state change, lexical results may be useful for orientation while remaining insufficient for the final claim.
Build the context packet around the decision
Many systems assemble context around a topic. A stronger method assembles it around the decision the agent must make. Topic similarity can retrieve a large pile of related prose. Decision-oriented retrieval asks what evidence would change the next action.
For a draft, that might mean brand rules, the approved facts file, and the target page. For an outbound message, it also means the relationship state, recipient identity, channel policy, and approval status. For a code change, the packet needs repository instructions, the relevant source, nearby tests, and the current worktree state.
This approach creates a useful stopping rule. Once the agent has the evidence required for the decision, more context can become harmful. Extra documents compete for attention and increase the chance that a stale statement overrides a current one.
Write down the decision first. Then list the evidence classes required to make it. Retrieval becomes an implementation of that list instead of a broad search followed by hope.
Policy belongs inside the context layer
Policy cannot sit in a separate handbook that the agent may remember to consult. The applicable rule should arrive inside the task context and remain attached to any action it governs. That includes approval requirements, forbidden destinations, data boundaries, and the evidence needed before a claim can be made.
Gevurah uses four gates for outbound actions. The wider lesson is that policy context should be executable. A rule such as "human approval required before publishing" can become a status check that closes the path. A prose reminder leaves room for interpretation exactly when the action becomes consequential.
Context also needs negative evidence. If approval is absent, the packet should say so. If the live source could not be reached, the result should remain unknown. A missing field must never be translated into permission.
This is where context engineering meets restraint. The best packet sometimes leads to a refusal, a draft, or a request for review. That outcome can be more valuable than a fluent completion based on assumptions.
Preserve provenance at the item level
An agent should be able to answer where each consequential fact came from. A single bibliography at the end of a long packet is too coarse. The relationship between a claim and its source needs to survive summarization, delegation, and handoff.
Item-level provenance can be lightweight. A record may carry a source path, retrieval time, owner, and evidence class. Live tool output can include the command or connector that produced it. A summary can link back to the exact records it compressed.
Provenance changes review from a debate about confidence into an inspection task. The reviewer can open the source, test whether it supports the claim, and see whether the context was current enough for the decision.
It also makes correction possible. When a source changes, the system can identify dependent records and tasks. Without those links, stale context spreads quietly and every summary becomes a new source with uncertain ancestry.
Treat context assembly as a pipeline
Context engineering works best as a visible pipeline with named stages. Start by routing the task to an owner and a scope. Retrieve candidate records from that scope. Apply authority rules to prefer source records over summaries. Check freshness where the task depends on live state. Add policy constraints. Compress only after the important distinctions are preserved.
The final packet should expose its own limits. A short header can state which sources were unavailable, which evidence is historical, and which parts came from self-assessment. The agent then has a basis for deciding whether to continue, narrow the task, or escalate.
Compression deserves care. A shorter packet helps attention, yet a summary can erase caveats. Keep exact wording for policy, approvals, and measured claims when the source defines canonical language. Summarize explanatory material more freely. The difference should be encoded in the record type rather than left to taste.
Common context engineering failures
The most damaging failures often look reasonable in a demo. A global search finds a persuasive record from the wrong client. A summary omits the sentence that limited a statistic. A cached status is presented as current. An agent carries a sensitive detail into a room that never needed it.
Other failures come from convenience:
- A transcript becomes the memory store, so important decisions are buried inside conversational noise.
- Retrieval ranking is treated as authority, even though similarity says nothing about ownership or freshness.
- The packet includes policy prose without a machine-checkable gate.
- Tool failure produces an empty result that downstream code reads as a negative answer.
- A handoff includes conclusions while dropping the evidence that supported them.
Each failure points to a control. Scope before search. Attach provenance. Distinguish unknown from absent. Keep approval state explicit. Carry caveats with measured claims.
How to evaluate a context system
Evaluation should test whether the right evidence changes the outcome. Create cases where a tempting record exists outside the allowed scope. Include stale and current versions of the same fact. Make the preferred retrieval path fail and inspect the fallback label. Remove an approval and confirm that execution stops.
Review the packet itself. Can a human see why each item was included? Can they trace a public claim to its source? Does the packet expose missing evidence? Does a delegated task preserve the same scope and prohibitions?
Measure retrieval quality with task consequences in mind. A top-ranked passage can still be unsafe. A lower-ranked policy record may control the entire action. The useful metric is whether the assembled context supported the correct bounded decision.
Then test memory updates. A correction should replace or supersede the old record without erasing history. Future retrieval should prefer the approved version. The audit trail should show who changed it and why.
A workable starting design
Begin with a small schema and strict ownership. Give every durable record a scope, type, source, and description. Route every task before retrieval. Keep live checks separate from stored memory. Add an explicit policy section to the packet. Record which sources were used in the result.
Next, create failure cases before adding more retrieval sophistication. Test cross-scope leakage, stale state, unavailable tools, missing approvals, and summaries that lose caveats. These cases reveal whether the context layer governs work or merely decorates it.
Finally, make the packet inspectable. Operators should be able to see the task contract, evidence, policy, and gaps without opening an opaque trace. An agent can work quickly inside a system that explains its boundaries.
Context engineering is successful when the agent receives enough to act, knows what remains unknown, and carries the evidence needed for review. The result feels less magical. That is a strength. Real systems earn trust through visible limits and records that survive the session.