Design intent when AI writes the code

Teaching the agent what it learned yesterday

9 min read

The hub of this series named four places design intent can live, and left one unwritten. Memory: where what the agent learned yesterday is written down for tomorrow. I said I would write it when I had numbers rather than worries.

The numbers are from my own setup. The platform the rest of this series measured never had this tier, so this is the one post with no archive receipt.

On 24 August I told the agent, in capitals, never to publish to my site unless I said so. It wrote that down. Two days later a post went live unreviewed, on the authority of an older note recalled as standing permission.

TL;DR:

  • Three written answers in eight days, two memory notes and one instruction-file line, to one question: may the agent make a post public. Each pulled a different way, and all three still load every session.
  • The note that says never to publish is filed under a name that says always. The name came first, the body was reversed later, and nothing checks that they agree.
  • 94 notes for one repository since June, 49 of them corrections to behaviour. Every failure in this post is in that half. The facts half has not failed.
  • A context diet cut this repository’s always-loaded rules by 83% and the memory index by 4%. An index line is also the key that finds the note, so memory resists trimming by design.
  • What held was a check. On 10 September the publish decision moved into the build as a date the nightly rebuild reads. The agent stopped being the one who decides.

Three answers, one question

A push to this repository deploys the site, so “when may a post go public” is a question with a cost. Here is how the memory tier answered it.

24 August. A draft was pushed on the strength of a note that said to commit and push finished work without asking. I reversed the note: never push unless told.

25 August. Two LinkedIn hooks fired at a post still unlisted and twelve commits behind. The session wrote a new note: scheduling the hooks means publishing the post, push included.

26 August. A stale note was read as standing permission, and a post was published before anyone had read it.

1 September. A request to rename a draft to its date was read as permission to publish it. A line went into the instruction file: a smaller, adjacent ask never grants publication.

Read the three together, as the agent does at the start of every session, and they disagree. One says never unless told. One says a scheduling instruction counts as being told. One says an adjacent instruction does not.

All three incidents put the decision in prose the agent had to weigh. Nothing in the pipeline could refuse.

The last post found three architecture records under one number, written by a team over a year. This is the same shape, written by one person, in a week.

A note written after an incident records that incident’s side of the argument.

The name says always

The never-push note is still filed as always-push-blog-repo. It was named when the rule was the opposite and reversed in place on 24 August. The index line is correct. The filename is not, and the filename is what six other notes link to.

Anthropic’s documentation describes the layout: an index with one line per memory, loaded every session, and one topic file per note. So one memory has three parts written at three different times: a name, an index line and a body. Nothing checks that they still agree. The last post called this supersession. Here it is inside a single note.

Written most, applied least

For one repository, June to September 2026: 94 notes on disk. By their own type tags, 49 correct how the agent should behave and 31 record project state. Nine point at credentials and dashboards, and five are other.

Every failure above comes from the behaviour half. The reference half has no failure I can point to, which is the pattern I would expect. Which port the browser listens on is a fact the agent looks up. Never push is a judgement it weighs against the instruction in front of it, every time.

The same shows up across projects. Twenty-one rules are shared by every profile on this machine. Nine of them open by counting how many times the lesson recurred before it was promoted, from two to six.

The sharpest: a rule about console encoding crashes already existed, and the crash hit six times in one session on 27 July. It hit twice more on 4 August, once in a script written that same session. What ended it was one line of code at the top of every script.

The vendor says the same thing without the anecdote. Both memory systems are “context, not enforced configuration”. To block an action regardless of what the model decides, you use a hook.

A note is advice the agent may take. A check is a decision it cannot make.

The bill a diet cannot cut

Everything the agent loads unasked at a cold start was measured on 4 August. For this repository plus the shared profile it came to 123,039 characters, before any work began. The instruction-file post had already argued this is a budget, so the rules went on a diet.

The repository’s rules lost 83%, from 65,556 characters to 11,325, by moving their bodies into files that load only when asked for. The shared profile’s rules lost 27%. The memory index lost 4%, from 18,100 to 17,322: four lines. The rest stayed, because an index line is both the summary and the key retrieval uses to find the note.

Grouped bar chart of four buckets of always-loaded text before and after the 4 August diet. The repository's rules fell from 65.6k to 11.3k characters, the shared rules from 20.7k to 15.1k, the memory index only from 18.1k to 17.3k, and CLAUDE.md grew from 13.0k to 13.6k

The diet took 83% off the repository's rules and 4% off the memory index. Each index line doubles as the retrieval key, so shortening it loses the note.

The hub worried that memory grows without bound. That was wrong about the bill. The vendor loads at most the first 200 lines or 25 KB of the index, more than twice this repository’s rules after the diet. Anthropic’s engineering post on context names the mechanism: context rot, where recall of any one token drops as the window grows.

The retro that nobody reads back

Memory is written by a loop. Every night a job replays the day’s sessions and proposes changes: 47 runs since 4 August, 92 decisions, 85 applied and 7 rejected. The rejected ones are kept, because an applied rate without its denominator is a vanity number.

The retro also wrote 164 learning cards for me, the human, most of them before the nightly job existed. A quiz to read them back was retired on 4 August after four months: zero invocations, 5 of 325 concepts ever asked. A card had to be remembered to be read, which is the failure of the tier it was recording.

Google’s SRE book describes this loop for humans in its chapter on postmortem culture: keep the record, keep it blameless, follow the action items through. The agent version has the first two. The record is the only thing the loop can produce on its own.

What I cannot rule out

  • One operator, one machine, 14 weeks. These are counts, not rates, and there is no setup without the memory tier to compare against.
  • I did not count the failures the notes prevented. A note that worked leaves no trace, so the reference half may be doing more than I can see.
  • My own instructions were part of the problem. Three phrasings of one rule in a week is a human writing under pressure, and the tier recorded it faithfully.
  • The check is four days old. Four days without an incident is not evidence of anything.

What I would do on Monday

  1. Tag every note as fact or behaviour when it is written. Review only the behaviour half, monthly. That is the half that fails.
  2. Count recurrences, not notes. The second time a lesson is written, link it to the first. The third time, stop writing and build a check that fails.
  3. Check that name, index line and body agree, mechanically, on every change to the memory directory. A mismatch is a supersession bug.
  4. Move any decision with an external consequence out of memory. Publishing, sending, spending, deleting: each becomes a field the build reads rather than a note the agent weighs.
  5. Keep the retro’s denominator. Record rejected proposals with the applied ones, or the loop reports only its successes.

Conclusion

The memory tier recorded what I told it, faithfully, including the three times I contradicted myself in a week. A better note would not have fixed that. Moving the decision into the build did.

What would change my mind: this post claims a behaviour note does not lower the repeat rate of the failure it describes. A check does. The publish decision became a date field and two lint rules on 10 September 2026.

If a post of mine goes public without a dated decision behind it before the end of 2026, the check was not the fix either. If none of the 49 behaviour notes records a repeat sighting in the same window, the tier works better than I have argued.

This closes the series. The hub has the four places side by side. Next in the measured series: the metric I never took, and why it could not be backfilled.

Methodology & limitations (click to expand)

Prior art

  • How Claude remembers your project, Anthropic. Two memory systems, both loaded every conversation and treated “as context, not enforced configuration”, with a hook as the way to block an action regardless. Also the index layout, one line per memory, and the load cap: the first 200 lines or 25 KB.
  • Effective context engineering for AI agents, Anthropic, 29 September 2025. Context as “a finite resource with diminishing marginal returns”, and the name context rot.
  • Postmortem Culture: Learning from Failure, chapter 15 of the Google SRE book. The human version of the loop: a blameless record, kept, with action items followed through.
  • MemGPT: Towards LLMs as Operating Systems, Packer et al., 2023. The research shape of what the vendor shipped: context managed the way an operating system manages memory, in tiers.

Data sources

  • One repository’s memory directory, counted 14 September 2026: 94 topic files plus the index (96 lines, 16,668 characters). Types from each file’s front matter: 49 feedback, 31 project, 9 reference, 3 learning, 1 user, 1 untyped. The 94 topic files total 31,182 words; only the index loads unasked.
  • Twenty-one shared rule files under the user profile, as of 14 September 2026. “Nine” counts the files whose header records two or more dated sightings of the same failure, counted by reading each file.
  • The diet is the measurement recorded on 4 August 2026 in this repository’s own playbook, in characters. The chart is generated from those figures by diagrams/di4-context-diet.py.
  • The retro loop’s run and decision logs, 4 August to 14 September 2026. The 164 cards are the whole learning directory, most written before the nightly job. The quiz figures are as recorded when it was retired.
  • Incident dates are the dates the notes and instruction-file lines themselves record.

What this does not show

  • No comparison. I did not run the same weeks without the memory tier.
  • No count of prevented failures. Only the failures that produced a note are visible.
  • The platform archive has no equivalent tier, so this post cannot be checked against the 20-month dataset.
  • The hub’s “grows without bound” was a claim about the bill, and that part was wrong: only the loaded slice of the index is capped, per the vendor’s documentation above. The index file and the topic files themselves are not.