We wrote the lesson down twice, and the mistake kept happening

You tell the agent, again, not to push straight to the main branch. It apologizes, says it understands, and maybe even writes the lesson into a notes file so the next session knows. A week later a fresh session does the exact same thing, and the note is sitting right there.

We assumed that was a writing problem: write the lesson more clearly and the next agent will follow it. Our Claude Code Stop hook asks for a memory when it sees an edit through its file tools or a commit, so we had plenty of lessons to check. In October we went looking for whether any of them had changed what the next agent did.

One lesson, written twice

The clearest case was about our own setup. A check that ran when the agent finished each reply was compiling our whole project every time, whether or not that reply had changed any code. That is wasted minutes, over and over.

• October 18: an agent noticed and wrote the lesson down.
• October 21: another agent noticed the same thing and wrote it down again.
• After that: the same check ran 160 more full compiles, adding up to about an hour of compiling across our agents.

The lesson was accurate both times. It was also just a note. Nothing about the check had changed, so the compiles kept happening.

What the audit found

The same thing had happened with bigger lessons. On October 3, Seth asked an agent to deal with our machines running low on disk space, and it wrote a full design with every check it would need. Later that afternoon Seth pointed out that this ground had been covered before: "You know we did actually address the resource stuff as part of the Claude harness." Four weeks later, none of the new design's checks had been built.

We read 30 days of our own agent sessions and followed 13 lessons about one kind of problem: disk space, memory and keeping the machine tidy. For 11 of them, the problem showed up again after the lesson was written.

Another one shows the trap from the other side. An agent designed a limit so that heavy builds wouldn't pile up on one machine, built it, and put it in a project folder. It was used 17 times. After October 20, 496 heavy builds ran over the next ten days, about 50 a day, and not one used it, because nothing required it. The fix existed and sat unused.

The pattern across the repeats was the same: the lesson said what to do, and nothing made it happen at the moment it mattered. (The evidence note lists all 13, including the two where we saw no repeat during the audit.)

The one line we added

Since October 30, a Stop hook in our Claude Code setup has checked the new feedback and resource memories it can identify from a session for one of two lines:

Enforced by: <the path of the hook, scheduled job or test that makes this true>
Automation impossible: <why no check can do this>

When a session tries to end, the hook checks the feedback and resource memories it can identify from that session. If one has neither line, or names a file that doesn't exist, it asks the agent once to build a real check or explain why none can run. The second attempt to stop is let through, so a session never gets stuck. That way the question "what will make this true next week?" gets asked while the lesson is fresh, by the agent that learned it.

The second line matters. Some lessons really are judgment, like matching a reply's tone to how upset a customer is, and a fake check would be worse than none. Writing the reason down keeps the gap visible.

Here is an illustrative lesson in the format step 3 uses. Replace the sample path below with the absolute or home-relative path of a check you have built and run:

---
id: 20261101152710
title: Late fees wait for the grace period
topics: [billing, lesson]
supersedes: []
author: agents
---

**Decision:** `Billing::ApplyLateFeeToOverdueInvoice` adds a fee only after the
grace period in `GRACE_PERIOD_IN_DAYS`.

**Why:** the contract gives customers ten days before a fee.

**Rejected:** a reminder in the README. A note alone is what we are replacing.

Enforced by: ~/your-project/spec/billing/apply_late_fee_to_overdue_invoice_spec.cr

What the line can't promise

Our gate checks that the line is there and that the file it names exists. It can't prove the check still runs next month. The build limiter above existed the whole time it was being skipped. So the line is a start, not a guarantee: it turns "remember this" into "here is the thing that checks it", and a person can look at that thing and see whether it is still switched on.

Try this today

Think of the last thing you had to tell your agent twice. Ask it: "Write a test, or a hook, that fails when this happens again, then run it once and show me it fails on the old behavior." If it can't be checked by a machine, write down why, next to the lesson. Step 3 of the lesson sets up the memories with engram, our open-source memory tool, and gives a three-line check that lists every lesson missing the line.

A lesson nobody runs is a note to a reader who may never open it.

How we tested it

• The audit: October 30, 2026. The Claude Code session records on our main development machine modified between September 30 and October 30: 165 sessions, about five a day, plus the helper agents they started. A Ruby script read each record and counted what the agents did (compiles, disk checks, cleanup commands).
• The lessons: the 13 lessons and designs about disk, memory and compute housekeeping written before or during that window. "Came back" means the transcripts show at least one more case of the problem after the lesson's date; it doesn't measure whether the problem got rarer.
• Limits: one team, one kind of lesson, Claude Code only. Lessons about code style or product choices may behave differently. The hour of compiling is summed across agents that ran at the same time, so it is more than clock time.
• What is published: engram 0.2.0 and its agent kit are public, and the kit already sends back a session that changed files without recording a memory. The Enforced by: check lives in our own setup and is not in the published kit yet; the shell check in step 3 does the listing part.

Next in the series: Would you send the reminder your agent just checked?