← Back

Context Architecture

The payload my agent sessions load before they open a source file. Scored against five published criteria; three failed.

The resident payload

Every session I start reads a fixed payload first: an index of about sixty memories, eight rule files, the working agreement for whichever repo it landed in, and a list of skill descriptions. Only after all of that does it open a source file.

The payload accreted, one “remember this” at a time, over months and across five agent vendors. Nothing crashed. The payload just got bigger, and a bigger payload is not free in three currencies: money, because every resident token is re-sent on every turn; attention, because a model reading sixty facts weights each one less than a model reading six; and trust, because a fact with no date cannot be told apart from a fact that used to be true. A stale instruction still reads as an instruction.

A paper I read this month gave me the criteria to audit it: Context Engineering: From Prompts to Corporate Multi-Agent Architecture (arXiv:2603.09619). Five quality criteria for an agent’s context — relevance, sufficiency, isolation, economy, and provenance — and a frame of context as the agent’s operating system.

What was already there

Four structures, all of which predate those words. I am describing them in the paper’s terms after the fact.

Economy, traded against sufficiency

A resident index, with bodies on demand

Only the index is resident. Each line is a pointer: a name, one clause of what that memory settles, and a trigger phrase where one is load-bearing (“read before any font subsetting”, “never re-queue this”). The body is a separate file that loads when the pointer fires.

The tradeoff: a session does not know the fact. It knows the fact exists and where to get it. That is strictly worse for sufficiency and much better for economy, and it is the right side of the trade only as long as the pointers are good enough to fire. A pointer that does not trigger is a fact I paid to store and never read.

Provenance, at the rule layer

Dated rules, each carrying its founding case

A rule in my setup is not an assertion, it is an assertion plus the incident that produced it, with a date. The rule that findings default to deferred rather than to a mid-session question carries this: a scheduled audit finished in one paragraph, then a stale lock file noticed in passing became a three-hour project across three repositories, with two pull requests and a postmortem. Every step of that was consented to. Every consent was requested at the moment I was least able to refuse.

Why the case travels with the rule: a bare rule invites an agent to reason about whether it applies; a rule with its founding case hands over the shape of the failure, which is what recognising the next instance actually takes. It also keeps the rule falsifiable by me. If I cannot remember why a constraint exists, I cannot tell whether it has expired.

Isolation

Deferred work is a self-contained prompt, not a conversation

When a session finds a real problem outside its scope, it does not raise it. It files a prompt for a fresh session, and that prompt must lead with its blast radius (the repository, and the files it expects to touch) and close with an origin line (the date it was filed, the repository at a specific commit, and the evidence).

What each half buys: the blast radius lets the next session check for a duplicate before filing another one, so two queued sessions cannot silently collide on the same file. The origin line is provenance for work picked up cold, weeks later, possibly on another machine. A deferred task whose evidence has gone stale should be discoverable as stale, not re-executed on faith.

The same shape, one level up

Skills: description resident, body on demand

A skill is a packaged procedure. Only its one-line description sits in context; the procedure loads when the description matches the work. It is the memory-index trade repeated at the level of behaviour rather than fact, which is why reference material needed only while reasoning about a rule lives in a skill while the rule itself stays resident.

The audit, and the three it failed

I scored each surface against all five criteria. Isolation and sufficiency held. The other three did not.

Criterion Verdict The finding
Relevance Failed Every rule file loads into every session, unconditionally
Sufficiency Held Pointers fired; bodies carried the detail
Isolation Held Deferred prompts stand alone; one concern per session
Economy Failed Index lines had grown into changelogs
Provenance Failed Not one index line carried a date

Provenance was the worst of them, and it was total. Not a single index line said when it was written or last touched. So a session reading the index had no way to tell a fact recorded yesterday from one recorded in June and quietly superseded in July. Every line asserted itself with exactly the same confidence.

Economy failed in a way that fed the first. Three lines had absorbed body-file detail rather than pointing at it, the worst of them running to roughly 230 words in a file whose entire job is to be pointers. An index line that reads like a changelog is no longer a pointer. It is the shape most likely to go stale, because appending to it is easier than editing the body.

Relevance failed too, and I did not fix it. None of the rule files are path-scoped, so a session renaming a CSS token still reads the multi-vendor routing doctrine in full. I left it alone because the alternative failure is silent and worse: scope a rule to a path, guess the path wrong, and the session that most needed the rule is the one that never loaded it. A rule that fails to load looks exactly like a rule that was followed. I would rather pay tokens than take that trade before I can measure it.

What shipped this week

Three conventions and one hook.

Every index line now ends with a compact date stamp, and says so rather than guessing where no date is determinable. Every line is capped at 25 words, with displaced text merged down into the body file rather than deleted, under one explicit carve-out: compression removes detail, never a verdict and never a trigger. “Read before touching X” is the load-bearing part of a line, and a shorter line that dropped it is worse than the long one. Deferred prompts now close with the origin line above.

All three of those are prose. The fourth is a hook.

Reversed. A prose rule promoted to a mechanism

The guard that covered the surface its author enumerated

One of my oldest rules is that an agent stages explicit paths and never git add -A, because parallel sessions leave dirty working trees and a wildcard stage scoops up another session’s in-flight work. Prose is a weak place for that rule to live, so it had already been promoted to a hook that inspects the command before it runs.

Auditing the hook found two commands that walked straight past it. Both stage the entire tree. Both were driven through the guard on standard input, and both were allowed.

The sharp part: the same guard’s commit branch had already solved the combined-flag problem, because it scans the letters of a flag like -am individually. The two branches were written on the same day. The second one never got the treatment the first one had. A matcher covers the surface its author enumerated, not the surface that exists.

The fix matches the operation rather than the spelling, and the widening is bounded rather than eyeballed: no other git add short option uses those letters, so a letter match cannot collide. The test suite went from 24 cases to 32, and the added ones are split deliberately between closing the bypasses and pinning the near misses that prove it did not widen too far. The change is public.

The staging rule is now enforced by something that cannot be persuaded. The three conventions that shipped alongside it are not. Nothing fails if a date stamp is wrong, or absent, or invented. The context is legible. It is not yet checkable.

The same gaps in production surveys

LangChain’s State of Agent Engineering survey puts numbers on where teams running agents in production are actually stuck. 32% name quality — accuracy, consistency, hallucination — as their top barrier. Among organisations over 2,000 people, security is second at 24.9%. And the adoption gap in the same report is the one I recognise most: around 89% have implemented observability, while 52% have implemented evaluations.

Those map onto this architecture. Quality is what provenance and economy are for. An agent acting on a fact that expired in July produces a confident, well-formed, wrong answer, and no amount of model capability fixes an input that is no longer true. Security is what isolation is for. The redlines in my setup are enforced per vendor, mechanically, at tool-call time. A constraint written in a document is a request, and five vendors with different harnesses will honour a request differently.

The observability-versus-evaluation gap is the same weakness in my own work. I can read my context. I cannot yet fail a build over it.