Claude Code can save notes for itself: small files it writes during a session so the next session starts knowing what this one learned. Theo, who runs the t3.gg channel and builds the agent app T3 Code, left that feature on for months across his machines, then sat down on stream to read what it had collected. He found 45 files on one project alone, written three times more often than they were read, and concluded on camera that the whole store was garbage. This guide walks through what he found, how to run the same audit on your own machine, and where each lesson should live instead.
01Run the audit
The audit takes two prompts, and the order matters. First ask the agent to check its own transcripts: how many past sessions wrote a memory, how many read one, and which files were never read. Count before opening anything, because the reading you are about to do gets recorded too, and it would mark every file as read. Then ask what memories it has saved about your project, and read every one.
Theo’s numbers from the counting prompt: across 355 sessions on one machine, 80 sessions had written or edited a memory while only 19 had ever opened one. Of the 45 files, 26 had never been read back at all.
“The memories get written far more than they get read.”
Theo (t3.gg), “Turn off Claude Code's Memory” · 21:26That ratio is the whole verdict. A memory system earns its keep when a future session reads a note and avoids a mistake. A store that is written three times more often than it is read is a diary, not a memory, and each unread file still costs something: it sits where a session might load it, and what it says drifts further from the truth every week.
02Three ways a saved memory rots
Reading his 45 files, Theo sorted the rot into three piles:
| Category | Example from his audit | Why it hurts |
|---|---|---|
| Duplicates of the instruction file | Ten files repeating rules from the instruction file every session already reads | Two copies of one rule drift apart; the agent reads the stale one |
| Records of finished work | Twelve shipped feature designs, complete with the pull request numbers | The work is finished; the note keeps presenting it as open |
| Snapshots of a moment | An out-of-date tool that has since been updated, a leak that has since been fixed, a comparison of two plans from three months earlier | The moment passed; the note still steers the agent by it |
The pattern across all three: the agent saved what happened, not what stays true. A pull request number, a bug that got fixed, a plan that shipped. None of it is knowledge a future session needs, and the third pile is the dangerous one, because a session that loads it inherits a picture of the codebase that is months old.
03The code is already the record
The clip that opens Theo’s video comes from Armin Ronacher, the creator of the Flask web framework, in conversation with Mario Zechner, who built the minimal coding agent Pi.
“For coding, I don't want a memory system. Code is the ground truth.”
Armin Ronacher, “Turn off Claude Code's Memory” · 3:22His argument: a codebase is already a complete, current record of how the project works, and it is the one record that cannot go stale, because it is the thing itself. Every extra store of facts about the code is a second surface to maintain, and every fact written twice can drift. Code comments show the failure in miniature: a comment explains why a line works a certain way, the line changes, the comment stays, and now it misleads every reader. A memory store is that problem multiplied by every file in it.
Ronacher’s ceiling for project memory is a map: a list of folders with short descriptions, cheap for the agent itself to maintain. Beyond that, he argues, current models read a file or two and pick up the structure and style on their own. Fancier machinery, indexing the codebase so relevant pieces can be fetched for the agent by meaning, does not survive his test either: he wagers that nobody adding it has measured whether it improves output, and that it does not.
04Four homes for one lesson
The audit tells you what to delete. The harder question is where each surviving lesson should live, and the video’s answer is a ladder Theo borrows from an engineer at Cursor: when you correct your agent, work out how to never make that correction again, trying the strongest home first.
- The code itself. Restructure so the mistake cannot happen. Shared types between backend and frontend remove a whole category of mismatch bugs; T3 Code shares one data layer across web, desktop, and mobile so a change cannot break one platform quietly.
- An automated check. When the code cannot forbid the mistake, a lint rule, a test, or a check that runs on every proposed change can catch it. Theo capped how much data his app may send to load one conversation, as a check on every change, after repeated regressions; now his agents hit the failing check and fix the regression before telling him the work is done.
- A rule or skill. Only when both fail does the lesson go into an instruction file or a skill, and skills fit process best: how to deploy, how to reach a server, things outside the code’s reach. Turn repeated fixes into rules covers writing these well.
- A human review. The last resort, and a sign the first three rungs have not been tried hard enough.
Automatic memory does not appear on the ladder at all. Every lesson it captures belongs on some rung, chosen deliberately, and the rungs enforce themselves in a way a saved note never can: a type error blocks the build whether or not anyone reads it.
One more steer for rung three. Theo’s instruction files spend fewer lines on prohibitions than on direction: what the product is, what makes it different, what he refuses to compromise on. A model told that the app must work over remote connections tests that case without being asked. He quotes Robert C. Martin’s line that imposing human discipline on an agent is probably a mistake, but imposing human values is not. Brief the model like a brilliant new hire makes the same case from the prompting side.
05What deserves to survive
The audit and the ladder leave a small pile worth keeping: lessons that are not in the code and cannot be put there. A quirk of one machine’s setup. The reason a dependency is pinned. Where the deploy credentials live. For that pile, the failures Theo found suggest three tests, applied at write time:
- Would a fresh session find this by reading the code? Then the code is the home, and the note is a future duplicate.
- Does it describe a moment or a standing truth? Moments rot; only standing truths go in.
- Did a person approve the save? Theo’s slop accumulated precisely because the agent decided alone what was worth remembering.
A memory that passes all three does better committed to the repository than hidden in a per-machine store, so it travels with the project and shows up in review like any other change. Every new repo starts with your lessons builds that committed layer, and Keep a growing knowledge base accurate covers catching the drift in what remains. For agents that need long-lived stores at scale, Give your agent a memory covers designing and pruning those stores.
Memory also keeps a defensible role outside coding. Ronacher runs a Slack bot that appends every exchange to one log file and searches it on demand, and Theo grants that chat assistants benefit from recalling personal context, where no code exists to be the ground truth. The skepticism in this guide is scoped to codebases, where a better record already exists.
For codebases, the practice this video ends on is the one we recommend: turn the
automatic feature off. Theo closes the video disabling it across every machine he
owns. In Claude Code, run the /memory command and switch auto memory off, which
saves autoMemoryEnabled: false to your settings; the environment variable
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 does the same. The Claude chat apps keep a
separate switch, “Generate memory from chats”, for readers who want the same in
chat. Turning it off loses nothing the write-time tests would have kept, because
anything that passes them belongs in the repository anyway.
06Built to pass the audit
The video’s criticisms double as a checklist, and a harness can be designed against it. AI Firmware, the template this catalogue’s own lessons live in (Every new repo starts with your lessons covers it), answers each problem with a mechanism rather than a policy:
| Problem | The firmware’s answer |
|---|---|
| Memory hides in a per-machine file nobody reviews | Project knowledge lives in a committed reference folder inside the repo; every entry arrives as a reviewable change and travels to every machine |
| The agent decides alone what to save | A save passes three tests first: not findable by reading the code, a standing truth rather than a moment, confirmed by a person |
| Written three times more often than read | An audit script counts writes against reads for every reference file and skill from the machine’s own session history, and flags what is never read |
| Stale snapshots steer later sessions | Moments are banned at save time (pull request numbers, task status, tool versions); every entry carries its date, and stale ones are replaced rather than appended to |
| Rules pile up as prose | The post-task review prefers a check the machine enforces (a lint rule, a hook, a script) over a sentence asking the agent to behave; prose is the fallback, same order as the ladder |
| Instructions list don’ts instead of direction | Project setup asks what the product is and what it refuses to compromise on, and writes the answer at the top of the always-loaded file |
The same design keeps the harness small. Its always-loaded layer is measured, not guessed: a health-check script prints the token weight of everything that rides along every turn (about 3,500 tokens) and the per-skill share of it, and skills a project will never use are switched off so their descriptions stop loading. Everything heavier loads on demand, when a task matches it.
Durability is git doing what git already does. Each learning is one commit, so one step rolls it back; a lost machine loses nothing; and improvements flow back to the template, so the next repository starts with every lesson the last one paid for. The rule holding it together is the same restraint the audit teaches: a new rule, skill, or entry must earn its place, and pruning beats accreting.
Further reading
- Theo · Turn off Claude Code’s Memory, the video this guide distills
- Anthropic · How Claude remembers your project, the official docs for the feature Theo audited, including the auto memory toggle