Everything the model forgets between sessions

Every session starts with nothing, which is easy to underestimate because it doesn’t feel that way. Claude Code can read the whole project, so it can read and find out what any of the code does, and that looks a great deal like knowing what’s going on. But it has no idea why any of it is like that.

The code is the only thing that survives, and code records what was decided without recording that a decision happened at all. Comments and documentation help, but pretty much everything around it goes: the option that was better on paper and got rejected for a reason that isn’t written anywhere, the approach that was tried a few weeks ago and didn’t work, the choice that was deliberate but looks like an oversight, the constraint that only exists because of something a user did once and so on.

The decision that stopped existing

On the food journal I’d banned a word from the interface, because it promised more certainty than the app can deliver. It was replaced everywhere, and I went through the whole product to make sure none of it was left behind. But I forgot to write it down.

So, a few weeks later it was back, in new copy, written in a session that had no idea any of that had happened. Nothing had gone wrong in the usual sense: the sweep worked, the decision was right, the new copy was perfectly reasonable copy. It never contradicted the decision, because as far as it could tell there wasn’t one.

A model that argues with your decision is easy to deal with, since you can see it happening and say no. A model that has never heard of your decision produces something sensible that looks like ordinary work.

Deferred and forgotten look the same

The second thing that disappears is everything you decided not to do yet: the thing that has to happen before launch, the shortcut that was fine for now but has to be removed, the bug you looked at and chose to live with for now. After a couple of weeks, a deferred item and a forgotten item are indistinguishable, and the difference matters, because one was a judgment call with a reason attached and the other is a hole.

So I have a skill that I use after every session: it writes what happened into a running journal kept in the project, and those entries carry a line for each of these with the date it was first flagged. Something deferred once is a decision, and something still sitting there months later is telling me the reasoning has probably expired (or that I was wrong about how soon it would matter).

What it actually is

That session summary covers what was decided and what the alternatives were, tradeoffs with what was accepted in exchange, anything that broke and why, and what’s still open. Those daily files roll up into monthly ones. On top of that sit 2 narrative files covering the last 30 and the last 90 days, plus a separate index of where things live in the codebase and what the non-obvious parts are for. Next to them, I have a very compressed recent history that is injected at every session start.

The format matters much less than the fact that I don’t write any of it by hand. If it were manual I’d do it on the short tidy days and skip it after the long session where several things broke and I was tired, which is exactly the session worth recording.

The layering exists because a pile of session notes becomes unreadable fast. Nobody is reading months of daily entries to answer one question, and a model given all of them will spend its attention on the wrong ones. Compressed into a 30-day narrative it’s less than a couple of pages, which is cheap enough to read at the start of anything that touches old ground, and the daily file only gets opened when the answer needs that much detail.

What compression drops

Compression loses things too, and it loses them by judgment rather than at random, which means the details that get dropped are the ones that looked unimportant at the time, and that’s usually right and occasionally expensive.

And the whole thing rests on the summaries being accurate, which brings up a problem large enough for its own post: the summary is written by the same model that just did the work, and it is entirely capable of reporting that something succeeded when it didn’t.

Record decisions with their rejected alternatives rather than just their outcomes, date everything you defer, compress old notes rather than accumulating them, and make the writing as automatic as possible, because the sessions you’ll skip might end up being the ones you need the most.

The next post is about that last problem, which took me a bit to notice and fix.

I’d genuinely like to know how other people handle this, journals, memory files or anything else; I’m at @roland.leth.ro and @rolandleth.

The rest of the series is listed in What changed my mind about building with AI.