Skip to content
Alex Reynolds
← Tools & resources

Memory

Should you remember this?

A long-lived AI agent fails more often by remembering too much than by forgetting. Every permanent rule costs tokens and attention forever. Run these six questions before adding another one.

The core principle

A memory is only worth its permanent cost if removing it would cause the agent to make mistakes. Everything else is noise that dilutes the signal in the rules that matter. When in doubt, don't write it. Wait for a second occurrence.

The six questions

Run all six before writing to memory or config. Any "no" is a reason to stop and reconsider.

1

Catalog conflict

Does this fight or duplicate something the agent already knows? Search the existing rules first. If it's already covered, update that entry instead of adding a second one. Two rules on the same topic drift apart and contradict each other over time.

2

Maintenance tax

Will this still be true and useful in six months? Is it a reaction to one bad session, or a recurring pattern? One-off mistakes don't need permanent rules. If it's a single occurrence, note it and wait. Write the rule only if it happens again.

3

Compounder

Does this make other rules or behaviors work better? Rules that interact with and reinforce each other earn their place. A rule that sits alone, referenced by nothing, is a candidate for deletion later. That's also a sign it may not be worth adding now.

4

First run

Is the application concrete and immediate? Can you point to a specific moment where this rule would fire? If the scenario is hypothetical ("this might come up someday"), defer it. Speculative rules accumulate faster than real ones and are rarely triggered.

5

Right location

Where does this actually belong? Always-loaded rules, an on-demand knowledge file, project-specific state, and credentials each have a home. Putting a rule in the wrong tier either wastes the token budget of the always-loaded layer or buries it where it'll never load. Decide the destination before you write.

6

Budget

Is there room for it? Give the always-loaded layer a fixed ceiling and let a script measure it. That layer is bigger than it looks: the rules, the main instructions file, the descriptions of every skill, and any tool definitions that load up front, since all of those ride along in every request.

A ceiling works better than a one-in, one-out ratchet, which fires on ordinary work and teaches everyone to reset the counter. With a ceiling, you don't have to remove something to add something, and the check stays quiet until you get close. When it does speak, a real trim is due.

Applying the gate

If: Fails catalog conflict

Then: Update the existing entry instead of creating a new one

If: Fails maintenance tax

Then: Don't persist it yet. Note it in the project's running notes file and wait for a second occurrence

If: Fails right location

Then: Move it to the correct tier before writing

If: Fails budget

Then: Trim or merge something in the always-loaded layer first, or move this to a file that loads on demand

If: Passes all six

Then: Write it, with a one-line justification of why

What running the gate taught me

1

A broken rule needs a better home, or code

When a rule keeps getting broken, the instinct is to make it louder. That's the one fix that reliably backfires. Current models already follow a plain statement, so ALL-CAPS "CRITICAL" and "YOU MUST" make them over-trigger. They start applying the rule in places it was never meant for.

Two things worked. The first was a short scope note at the top of the rule saying where it really applies, because the file's name had been telling the model the rule covered much less. The second was enforcement in code. One prose rule about where files belong was broken a dozen times in four months. Now a hook refuses the write, and a model can't forget a hook. Code beats a better-placed rule, which beats a louder one.

2

Give first occurrences a cheap home

Question two says to wait for a second occurrence, which raises a fair question: where does the first one go? The first time something goes wrong, it gets a line in the project's running notes file. The second time, it graduates to a rule. That file only gets read when someone works in that project, so it costs the always-loaded layer nothing.

3

Set a budget you actually enforce

A budget nobody enforces is worse than none. I once set a memory budget, went four times over it, and kept adding. All it taught was that budgets here were decorative. The fix was a number we could actually live with. Now, over budget means merge or delete before adding anything new.

The test

Before saving, ask: "Would removing this cause the agent to make a mistake?" If not, cut it. A lean memory of rules that all earn their keep beats a sprawling one where the important rules are lost in the clutter.

Updated October 2026

← Back to Tools & Resources