Context is infrastructure

SplitKit, the race-day platform whose build I described in "From idea to production with AI in the loop", is ten repositories built and operated by one person, no team, with AI agents doing most of the typing. The agents are stateless. Every session starts blank, and a blank session in repository seven knows nothing about what was decided last month in repository two, or why, or what was already tried and abandoned. The thing that makes a stream of blank-slate sessions behave like one continuous engineering organisation is a tiered project wiki that hands each session its context up front. I call it infrastructure without irony: it has size budgets, load paths, eviction, and enforcement, and it earned each of those the usual way, by failing without them.

Early in the build I adopted an off-the-shelf memory plugin for the agent tooling. Its reflection hook carried one instruction: at the end of every session, write a summary of roughly five hundred words. There was no ceiling on the file the summaries accumulated into, and no eviction policy. Each summary was individually reasonable. Together they compounded, session after session, until the always-loaded context cache reached 612 lines and 204 KB, and the loader began silently truncating it. Sessions were being handed an arbitrary prefix of the project's history. Memory had stopped working, and nothing said so.

That failure has a familiar shape: quiet degradation under growth, no alarm, discovered by symptom.¹ It is a capacity incident, and it got the capacity-incident treatment: budgets, monitoring, eviction, and load paths designed on purpose. The rebuild is the subject of this entry.

One framing decision precedes all the mechanics, because it settles what the memory is for. The codebase answers "what is". The wiki answers "why", "what was decided", and "what already failed". An agent can grep ten repositories and learn what the code does today. It cannot grep out the reasoning behind a decision made in a session two months ago, the approach that was tried and reverted, or the incident whose fix looks obvious now precisely because the incident happened. Facts like those survive only if something is built to hold them.

1.0What goes in

The wiki is four tiers and an audit log, each with a job and a maximum size.

Tier 0 is the hot cache: a rolling seven-day file of one-line bullets, hard-capped at 150 lines and 20 KB, injected into every session by a session-start hook. One line per recent event, and every line points at the file that holds the detail. It answers "what has been happening around here" for the price of a page of text.

Tier 1 is six core files with fixed names, each under 5 KB, read on demand: the project brief (what this is and who it is for), system patterns (architectural rules and invariants), current state (what is shipped and what is gated), decisions (settled calls, sorted by topic), key numbers (metrics, targets, and costs), and open questions. Those six names cover the questions a fresh session actually asks.

Tier 2 is the atomic layer: per-topic concept notes, entity notes, and incident write-ups, each under 15 KB, found by search rather than by fixed name. Tier 3 is the unbounded archive: folded rollups of old log entries, plus snapshots of in-flight reasoning captured before context compaction. Rarely read, never lost.

Alongside the tiers runs an append-only log with a fixed, machine-parseable heading format, two or three sentences per entry at most, periodically folded into the archive. It is the audit trail, and its enforced brevity matters in a moment.

With ten repositories, the default would have been per-repo documentation. Each repo does keep its own specs, but the "why" layer sits above all of them, deliberately, because decisions do not respect repository boundaries: an incident in one repo routinely produces a rule that binds sessions in all ten. Ten READMEs would have meant ten partial copies of the truth, ageing at ten different rates.

2.0Budgets, pointers, and one grep

Three rules turn that folder structure into infrastructure.

First, the size budgets are service levels, and they are checked, not hoped for. The session-start hook warns when the hot cache is over budget, and maintenance tooling exists specifically to bring a tier back under its ceiling. The plugin failure is the reason: growth was silent and truncation was silent, so the ceiling has to be loud. A memory system's most dangerous state is not "empty"; it is "over the load limit and still apparently working".

Second, the cardinal rule: anything over three sentences does not belong in the hot cache or the log. Both are pointer layers. The detail goes into an atomic file, and the cache and the log carry one line that points at it. This single rule keeps the always-loaded layer readable at a glance and makes the atomic layer the place where links resolve.

Third, the discoverability invariant: the agent routing file at every level of the monorepo, the file each session reads first, names the six core files by path, so a brand-new session in any repository finds the durable context in one grep. No fact of record requires tribal knowledge to locate. That property matters more than it would on a human team, because here the new starter arrives several times a day, reads at machine speed, and reads only what it is pointed at.

There is measurement behind the shape, not just taste.² The A-MEM paper measured roughly 1,200 to 2,500 tokens per retrieval for atomic, tiered notes against roughly 16,900 per retrieval from a chronological blob. My own blob supplied a confirming detail: the old monolithic log had 38 inbound links pointing at the file and zero pointing at any section within it. Everything cited it; nothing addressed it. A write-only file.

3.0Capture is tooling, not discipline

None of this survives a busy fortnight if writing depends on remembering to write. So capture is mechanical: the plugin gave way to ten bespoke hook scripts that fire at the edges of every session.³

At session start, the hot cache is injected and its size is checked, and a catch-up step stages any transcript the previous session failed to capture. After any wiki edit, the change is auto-committed locally, so knowledge never sits uncommitted. Before compaction, the moment an agent's context window is squeezed and its in-flight reasoning would otherwise evaporate, a hook snapshots the full transcript. At session end, the transcript is copied into a raw staging folder for later batch ingestion, and a nudge fires when the staging pile grows. And at stop, one hook asks the question the whole culture hangs on, which the next section covers.

Behind the hooks sit the maintenance skills: one drains staged transcripts into the right tiers after the fact, one compresses the hot cache back under budget, one folds old log entries into the archive, and one scans recent activity for repeated themes worth promoting into doctrine, on the principle that one occurrence is noise and two is a signal.

Notice what the roster never relies on: the human remembering, or the human being in a conscientious mood. A session that crashes, or ends at one in the morning with no ceremony, still leaves a transcript in staging, and the staging pile still gets drained. Discipline is saved for the one job tooling cannot do, deciding what a fact means and where it belongs.

4.0Writing as part of done

The stop hook closes every session with one question: did the wiki change to match what happened? If the wiki changed, the hook prints a routing tree so the write lands in the right tier: a settled decision goes to the decisions file, a shipped feature to current state, a new metric to key numbers, a new concept to an atomic note, and it repeats the size ceilings while it is at it. If the session changed durable reality without a matching entry, it gets challenged before it ends. If nothing wiki-relevant happened, the hook stays silent, which is what keeps the challenge meaningful.

That one hook moved writing into the definition of done. Decisions, incidents, and gotchas land in the wiki by default, at the moment they are freshest, because ending a session without recording them is the path of most resistance.

Incidents become rules the same day. The production incident from "From idea to production with AI in the loop", where a blank date field the timing platform happily accepted exposed an assumption the code had no business making, produced written doctrine within hours, placed where every future session reads it: adapt to the vendor's reality, never the reverse. No handover meeting, no tribal transmission. The next session inherited the rule because the rule was in its load path.

And the wiki has more readers than the coding sessions. The nightly briefing agent, which composes a morning summary of where the project stands, clones only the wiki, nothing else. The race-day ops agent's deep-dive mode draws on the same memory when it reasons about a live event. Every consumer reads one artefact, so keeping that artefact accurate keeps all of them accurate, and the usual economics of documentation invert: an entry written today is typically read again within hours, by machines that act on it.

5.0If you're doing this yourself

Six rules, each with the gate that enforces it:

1. Separate "what is" from "why". The codebase already answers "what is", and agents can grep it. Memory is for decisions, failures, numbers, and open questions. Rule: if a fact can be regenerated by reading the source, it stays out; if it was settled in a conversation, it goes in.
2. Give every tier a size budget and enforce it with tooling. Budgets exist because the failure mode is silent: an oversized always-loaded file does not error, it truncates. Gate: if your always-loaded context doubled in size next month, what exactly would tell you?
3. Fixed names for the core, search for the rest. A handful of files with stable names, listed by path in the routing file of every repository. Gate: can a fresh session find the durable core in one grep, with no human in the loop?
4. Caches and logs point; atomic files hold. Rule: anything over three sentences gets its own file and leaves a one-line pointer behind.
5. Make capture mechanical. Hooks at session start, session end, and compaction; a staging folder and batch ingestion for everything that slips past them. Gate: if you stopped remembering to take notes tomorrow, would anything still get written?
6. Put memory in the definition of done. A session that changed reality answers for the missing entry before it ends. Gate: at the end of a session, what, other than good intentions, asks the question?

Context is the first input every agent session consumes, before it writes a line. Feed it from infrastructure and each session starts where the last one stopped. Feed it from goodwill and it works until the week you are too busy to write, which is exactly the week worth remembering.

Entry 03 · The memory system it describes has been running since May 2026