Your Coding Agent Keeps a Diary. We Read Ours.

There is a file on my laptop, written by an agent, that says: “Ron pre-approves all install/update clicks during macOS releases; never ask, never wait.” No human wrote that sentence. Claude Code wrote it to itself at 22:34 on a Wednesday, after a release where waiting for one confirmation click cost it an hour and fifty-four minutes of a three-and-a-half-hour job. It filed the note under feedback, cross-referenced the skill document that owns release policy, and moved on.

That note is one of fifteen in a hidden directory Claude Code maintains for our repository. On my other Mac - same repository, same user, same product - the equivalent directory has about two hundred notes. Neither machine knows the other’s notes exist. Neither ever will.

We spent a week reading both diaries, measuring what they cost, and checking every note against our actual documentation. Some of what we found flipped our assumptions. Most of it applies to anyone running coding agents seriously, on any stack. This post is what memory actually is, what it actually costs (we measured, and the number embarrassed our hypothesis), and the one maintenance habit that we think matters more than all the token math combined.

The diary nobody mentions

If you use Claude Code, it has been taking notes on you since February. The feature is called auto-memory, it shipped on by default, and it works like this: as the agent works, it writes small Markdown files - one fact per file - into a per-project directory under your home folder. Build commands that worked. Bugs that took an hour to diagnose. The fact that your test database lives on a RAM disk and fills up. Your preferences, phrased back at you with slightly unnerving precision.

Each note gets a type: user facts, feedback corrections, project state, reference pointers. An index file - MEMORY.md - lists every note in one line each, and that index is the only part loaded into every session. The notes themselves stay on disk until something goes looking.

Three things about the mechanics that most write-ups get wrong:

1. The always-loaded part is capped. Only the first 200 lines or 25 KB of the index load at session start, whichever comes first. The notes behind it cost nothing until recalled. Whatever else memory is, it is not an unbounded per-prompt tax - the vendor bounded it by design.

2. The model writes the notes itself, inline. There’s a persistent claim that a hidden background process re-reads your whole conversation after every message and silently doubles your token bill. We went looking. In our transcripts, memory writes are ordinary tool calls the model makes mid-session - visible, attributable, small. The doubling claim traces back to one blog post, has never been confirmed by Anthropic, and on the machine where we could inspect flags, the background path was disabled. If someone tells you memory is secretly doubling your bill, ask them for their transcripts.

3. It prunes. The “append-only pile that grows forever” story is out of date. Our transcripts reference two notes that no longer exist - written, used, and deleted once the problem they described was fixed. Anthropic also shipped a consolidation pass (they call it dreaming: after enough sessions and a day of quiet, the agent merges duplicates and rebuilds its index) plus an official skill that does the same on demand.

So the scary version of the story - hidden, bloated, ever-growing, secretly expensive - mostly dissolves under inspection. What’s left is more interesting.

Memory is not a cost problem. It is a second source of truth problem.

Shipped first, governed later

The feature’s own timeline tells you where the gaps are. Auto-memory shipped in early February 2026 - quietly, on by default, with no way to turn it off. The /memory command that lets you disable or inspect it arrived three weeks later. Warnings when the index outgrows its load limit came in June. The “write over the limit and it errors instead of silently truncating” fix landed in July - five months after launch. Consolidation - the dreaming pass - appeared in May as an experiment.

None of this is a complaint; it’s the normal shape of a feature finding its footing, and the vendor has been fixing exactly the right things. But notice what the fixes have in common: every one of them is hygiene retrofitted after the fact, shipped in response to stores that had already grown wild in the field. Our 197-note machine grew to 197 notes during precisely this window - accreting under the early rules, now governed by the later ones, with nobody ever having looked inside.

There’s also a fork in the road worth knowing about. For enterprise teams, Anthropic now offers server-synced team memory - versioned, audited, shared across a workspace. It’s their own admission that the per-machine model fragments knowledge; their fix is a synced store, if you’re on the right plan, inside their ecosystem. For everyone else - and for anyone running more than one agent brand - the fragmentation is yours to manage. Which is why the audit below exists.

And it turns out the academic literature had already predicted our headline finding. An ETH Zurich study this year tested what happens when you hand coding agents context files that are redundant with documentation the repo already has: task success went down a couple of points, and cost went up more than twenty percent. Redundant context isn’t neutral - it actively taxes the agent. Keep that in mind for what we found next.

Two machines, two brains

Here is the finding that reframed the whole audit for us. My M4 has 197 notes for our repository. My M1 has 15. Same repo, same person, same work.

The difference isn’t the hardware - it’s age. The M1’s memory directory was created ten days ago; both machines accrete notes at the same pace, roughly two per active day. Every machine starts from zero and grows its own private brain. Rename the project directory? Zero again. Fresh CI sandbox? Zero, every run. New laptop? Zero.

And the brains diverge in ways that are almost comic. Two of the most-consulted notes on my M1 are facts about the M4 - which binaries are missing from its PATH, how small its Docker VM is. Knowledge about the M4, permanently stored where only the M1 can see it, because that’s where the session happened to be running when the lesson was learned. Meanwhile the M4 had to learn its own facts about itself, separately, the hard way.

The two stores don’t even share a file format. The older machine’s notes use one naming scheme; the newer machine’s use a different one, with structured front-matter the old files lack - the storage schema itself drifted between Claude Code versions, and old stores keep their old shape forever. We even found a third variant: our orchestrator subagent keeps its own memory directory checked into the repo, frozen in the previous format. Anyone building tooling against these files (as we now are) learns quickly to treat the schema as versioned and the layout as archaeology.

Multiply this by agent brand and it gets worse. Codex keeps its own memory in its own format (a SQLite pipeline, off by default - opposite default, opaque storage, same idea). Subagents each get their own directory, invisible to each other. The knowledge your tooling accumulates is sharded across a matrix of machine × project path × agent × agent role, and no cell of the matrix syncs with any other.

There is exactly one store in this whole picture that every machine, every teammate, and every agent brand can see: the repository itself. AGENTS.md, the docs, the checked-in skills. Git ships it everywhere for free. Keep that asymmetry in mind - the whole practical conclusion of this post hangs on it.

We checked every note against the docs

Our repo is unusually well documented - agents write session notes, maintain a knowledge base, keep per-topic skill files. Claude Code’s own memory instructions tell it not to save things the repo already records. So, does it?

The store was small enough to audit properly: read all fifteen notes, then search the repo for each fact. No filename heuristics, no similarity scores - actually read both sides and judge. The result:

• 40% of notes had a strong twin - the same fact, already documented, usually well.
• 27% were partial - the mechanism documented in the repo, the operational lesson only in memory.
• 33% were genuinely memory-only - real knowledge, written down nowhere else.

The 40% isn’t the model ignoring its instructions, exactly. It’s structural. When an agent finishes a piece of work here, repo policy tells it to write a session note in the docs. The memory habit also files a note about the same event. Same session, same fact, two stores - written minutes apart, by an agent following both rules correctly. Dual-entry bookkeeping, except nothing ever reconciles the books.

And unreconciled books drift. Two live specimens from our fifteen:

The diary contradicts the docs. We have a formatting hook that auto-runs prettier on files the agent edits. The session note that introduced it - in the repo, reviewed, canonical - says it “removes format-diff churn from PR reviews.” The memory note about the same hook says, in effect: this hook balloons a thirty-line change into an eight-hundred-line diff on any file that wasn’t already prettier-clean, and here is how to route around it. The memory is right. It’s the correction, learned in production, that never flowed back into the document everyone else reads. Every agent on my machine quietly knows the truth; every agent everywhere else reads the marketing version.

The diary cites the wrong law. That release-approval note from the opening? It carefully names the skill document that owns the policy - “authority: the stable-release skill.” The fact did land in the repo the same day… in a different skill file. The note points at a document that doesn’t contain it. Nothing checks cross-store references, so nothing will ever notice - except an agent, mid-release, following the pointer to an empty destination.

For fairness, the audit also found the pattern done right, and it’s worth naming because it’s the shape everything else should converge to. Our best note describes a test-database failure mode in three tight paragraphs - and cites the full repo session note that owns the details. Memory as a compressed pointer to canon: the agent recalls the gist in a few hundred tokens, and the single source of truth stays single. One note out of fifteen figured this out on its own. The other fourteen are why you audit.

Neither of these failure specimens is a token problem. Both are correctness problems, the kind that make an agent confidently do the wrong thing - and a wasted agent-hour costs more than every memory note we have ever stored, combined. Remember the ETH result: redundant context doesn’t just sit there costing nothing. It makes the agent slightly worse while costing slightly more, forever, invisibly.

Then we measured what memory actually costs

We assumed memory would at least be a meaningful line on the context bill. So we scanned every session transcript on the M1 - 66 sessions - and attributed every token that entered the model’s context through a tool: every file read, every command output, every screenshot, every memory recall through any channel.

Memory came to 0.19%.

Here’s the full ledger, and it’s worth staring at:

What enters the agent’s context	Share
Harness overhead (reminders, tool listings, bookkeeping)	~29%
Shell output (builds, tests, git)	~23%
Reading code - the agent sifting through your flows	~22%
Browser screenshots (429 of them)	~20%
Reading documentation	~6%
Memory notes - all channels combined	0.19%

The agent read code 120 times harder than it read its own memory. The scaffolding around the agent - the reminders and listings the harness injects to keep it on rails - outweighed memory by a factor of 150. Even our process documentation, the stuff we point agents at on purpose, cost thirty times more context than the diary did.

The documentation line hides its own lesson. When we ranked individual documents by context spent, the top of the list wasn’t product docs - it was our agent process files: skill definitions read nineteen times, one workflow guide read seven times for forty-two thousand tokens. The instruction layer you write for your agents is itself a context product, with hot paths and dead weight, and it earns its keep - or doesn’t - session after session. Nobody we know is measuring theirs. We weren’t either, until this table printed.

As for recall traffic on the memory side: across all 66 sessions, the model explicitly opened a memory note six times. Writes outnumbered reads four to one - a young store is almost all deposit, barely any withdrawal. But there’s a third channel most people don’t know exists: when a memory file changes, the harness pushes a snippet of it into other live sessions’ context uninvited. One note about a missing binary got pushed ten times that way, with no read call anywhere. If you ever instrument this yourself, count all three channels - the pull, the push, and the write - or you’ll undercount by more than half.

Two measurement traps we fell into so you don’t have to:

Bytes are not tokens. Screenshots live in transcripts as base64 blobs, and if you count bytes, images look like 76% of everything. They’re not - vision models bill images by dimensions, roughly 1,100–1,600 tokens per screenshot regardless of file size. Correcting that one error moved screenshots from 76% to 20% and reordered our entire priority list. Any context-cost analysis that hasn’t handled this is overstating images by twenty to thirty times.

Entry is not residency. A file read doesn’t cost once - it sits in the conversation and rides along with every subsequent request in that session, mostly at cached-input rates, until the session ends or the history gets compacted. A 500-token note recalled late is noise; a 28,000-token note recalled on turn two of a fifty-turn session is over a million cached-input tokens. Size-at-entry-time is the metric that matters, which is also why the one memory hygiene rule with real token stakes is: keep individual notes small. Our other machine has a single 28K-token note. That one file is a bigger context liability than both machines’ entire remaining memory combined.

One more number, because it points somewhere useful: during this audit we delegated two research sweeps to subagents. Inside their own contexts they burned through a couple hundred thousand tokens of reading. What our main session paid for both: 28K - just their final summaries. Subagent isolation, the same property that fragments memory, is also the cheapest context lever there is. The geometry cuts both ways.

The habit that actually matters

So memory is cheap, bounded, self-pruning - and quietly accumulating a private, per-machine fork of your team’s knowledge that nothing reviews and nothing reconciles. What do you do with that?

Not deletion. Deleting an agent’s memory to save tokens is optimizing the smallest number on the bill. The play is promotion:

Read the diary. Whatever deserves to be true everywhere, move into the repo. Let memory keep the rest.

The 33% of our notes that were memory-only were the most valuable things in the store - a test-infrastructure gotcha nobody had documented, a QA technique worth reusing, that prettier correction the docs never got. Every one of them was one git commit away from working on every machine, for every teammate, for every agent brand, forever. That’s the asymmetry: a fact in memory helps one agent on one machine; the same fact in AGENTS.md or your docs compounds across your whole fleet.

The concrete loop we’ve settled on, maybe monthly:

1. Open the directory and read it. ~/.claude/projects/<your-project>/memory/. It’s plain Markdown, fifteen minutes, and genuinely illuminating - it’s your agent’s honest opinion of your infrastructure.
2. Promote what’s durable. Machine-independent lessons go to the repo, in whatever form your team already reads. Shrink the memory note to a pointer at the doc, which is the one pattern from our audit where both stores stayed correct.
3. Fix what’s wrong. A stale note isn’t clutter; it’s a confident future mistake. Delete it or correct it on the spot.
4. Check the index headroom. The always-loaded index caps at 200 lines. Ours was at 127 on the old machine - close enough that new notes will soon start falling out of the agent’s awareness. Run the consolidation skill before you hit the wall, not after.
5. Leave the machine-local stuff alone. “This laptop’s Docker VM is too small” belongs in memory. It’s true here and nowhere else. That’s what the diary is for.

And if you want the numbers for your own setup instead of ours: everything we measured came from a sixty-line script reading the transcript files Claude Code already keeps on your disk - which files entered context, how many tokens, how often, which memory notes have never been recalled at all. No instrumentation, no API calls. An afternoon, and you’ll know whether your bottleneck is memory (probably not), screenshots (maybe), or your agent re-reading the same four-thousand-line file every session because nobody wrote the summary doc it actually needed (that one stung).

Why we care, beyond the diary

We build Ottto, an observability product for coding agents, so this audit was also us eating our own cooking - the memory view we prototyped here is landing in our Optimize page, next to the context-composition data we already collect per machine and per repository. But the takeaway stands on its own, no product required:

Your agents are already writing down what they learn. The writing is not the hard part anymore. The hard part is that knowledge now accumulates in places with wildly different reach - a private per-machine diary at the bottom, the shared repository at the top - and nothing in the toolchain moves lessons up the ladder. That’s a librarian’s job, and right now nobody has it.

Give someone the job. The diary is a good read.