Keeping the logs, losing the lesson

The viral fix

A version of this advice has been making the rounds:

Tell your agent: set cleanupPeriodDays to 3650. By default it deletes your session logs after a year. Those logs contain your intent, your corrections, your reasoning — all of it. Stop throwing your work away.

The diagnosis is right. The fix is wrong. What that default deletes is not your work — it's a transcript of your work. Those are different things, and the difference is the whole point of memory infrastructure.

What 3650 actually buys you

A larger ~/.claude/projects/. JSONL files, accumulating linearly, one per session. Search becomes rg across tens of thousands of messages — half of them tool output, most of them irrelevant by the time you go looking. The file you need is the one whose name you don't remember, from a project you renamed in March, in a session you ran with a model that's been retired since.

And the part the post is quiet about: nothing in your next session reaches into that archive. The transcript sits there. The agent that started this morning has never heard of last March's correction. You can recover intent — if you remember to look, and you know what to grep for. You can't use it.

Retention is not memory

This is the category error worth naming. Retention is a property of storage: how long bytes stay on disk. Memory is a property of behavior: whether the next decision reflects what was learned before. They sound related. They are not the same thing.

A ten-year archive nobody reads is an expensive hard drive. A thirty-day memory that's actually consulted at the start of every session is a memory. The advice improves the first number and does nothing for the second.

What "remembering" actually requires

Three properties, not one:

• Curated. Out of the dozens of messages in a single turn, only some carry knowledge worth keeping — intent, corrections, conventions, repro scenarios. The rest is scaffolding. A useful memory layer keeps the first and discards the second.
• Addressable. Each fact lives at a path you can name. context.project.architecture. knowledge.technical.build. You can read it, blame it, overwrite it, diff it. A correction targets one slot; an unrelated lesson lands in another. Two facts never collide.
• Re-applied. The next session loads the relevant slice before it sees your first prompt. Not on request. Not via grep. Automatically, as part of starting up.

A JSONL transcript has none of these. It's the raw input, not the lesson — indexed by nothing, consulted by nobody.

The comparison nobody draws

The same problem, two answers:

                          cleanupPeriodDays=3650   memoir
                          ----------------------   ----------------------
storage growth            linear, forever          curated, bounded
addressability            none — grep your JSONL   paths, branches, diff
re-applied on startup     no                       yes (SessionStart)
correction model          append a new transcript  overwrite the path
shareable across hosts    no                       git-style push / merge
secrets exposure          full chat history, 10y   just the conclusions

The left column is what the popular advice buys you. The right column is what people actually mean when they say "I want my agent to remember."

What this looks like in practice

A Stop hook fires at the end of each turn. It reads the turn the way you'd read it: what was the user trying to do, what got established, what got corrected? It writes the answers as commits — small, typed, addressed.

The next time a session opens in this repo, the most recent decisions and the codebase:onboard snapshot flow in before your first message. The agent that didn't exist this morning starts with the same context the one you closed last night had. No retrieval prompt, no "remember when we…", no archaeology. The taxonomy is already loaded.

When you correct the agent later in the week, the correction overwrites the slot — the prior value isn't lost (memoir blame still shows it), but the current answer is the new one. The agent loading that path tomorrow gets the corrected version, not a stack of contradictions sorted by recency.

Why "more retention" is the wrong instinct

The instinct comes from a real fear: that the agent will forget something you wished it remembered. But that fear gets relieved by writing things down at the right granularity, in the right shape, not by hoarding more of the wrong thing.

Ten years of raw chat history is also ten years of half-formed thoughts, abandoned approaches, dead ends, and secrets pasted into prompts. The signal-to-noise ratio of a transcript drops the moment it's written. The signal-to-noise ratio of a curated path stays roughly constant — because something else has the job of pruning it.

The shift

Stop asking what did I say? Start asking what should the next agent know? The first question is satisfied by a longer log. The second is satisfied by a shorter, sharper one — distilled at write time, addressed by topic, replayed by default.

By all means, bump cleanupPeriodDays if you want a forensic record of how a project actually unfolded. Just don't confuse the archive with the agent's working memory. They are different problems. The gap between them is where most of the real value lives.

Give your agent a real memory

A decade of transcripts is a warehouse. A taxonomy the next session actually loads is a memory. Pick the one that changes behavior.