Picture a lab in Montreal. A man is tracing a star with a pencil, but he can see his hand only in a mirror. On day one the pencil wanders everywhere. By day three it barely slips. And every time, he is certain he has never done this before.
That man is Henry Molaison, H.M. In 1953 surgeons removed the front parts of both his hippocampi to stop his epilepsy. The seizures stopped. So did his ability to form new lasting memories of facts and events. But his hand kept learning, something his mind never knew it had practised.
You know this picture from your terminal. Every morning, in a fresh context window, your assistant sees the repo for the first time. Yesterday's two-hour talk about why the integration tests need a local Redis? Gone.
So what can a brain, a jay and a nutcracker teach us about memory across sessions? Lesson one: "memory" isn't one device. It's a label on a dozen of them. (The Claude Code translations below are mostly proposals, not features; where I describe what exists, I rely on the October 2026 docs.)
Twelve letters and a sieve
- George Sperling flashes twelve letters for a fraction of a second. You name three, maybe four. Yet if a tone right after the flash points at one row, you read it almost perfectly. All the letters were there. They just faded faster than you could say them. Sensory memory isn't a store. It's a sieve.
In Claude Code the sieve is raw tool output: logs, stack traces, API responses. Compaction clears old tool results first, and that's fine: a file on disk can be read again. So nothing raw goes into memory. A note keeps the conclusion ("test X is flaky because it depends on the timezone"), not the log.
A workbench for about four things
Now sit at a workbench. It's small. Nelson Cowan counted that it holds about four things at once, not the seven of the old saying. The only cheat is packing small things into one bundle you understand.
For an agent, the workbench is the context window. MemGPT's researchers had the model raise the alarm at seventy percent full, to save what mattered before it was pushed out. Keep task state in a file that survives compaction, with a tabu list of "what I checked and ruled out", like a rat that knows which maze arms it has visited. And send big reading jobs to subagents: they return one bundle instead of fifteen facts. That's chunking.
The jay and the larva
The western scrub jay buries food: a larva that spoils fast, a nut that keeps. In 1998 Nicola Clayton and Anthony Dickinson showed that the jay remembers what it hid, where and when. If the larva has waited too long, the jay doesn't go back for it. It goes for the nut. The researchers carefully called this episodic-like memory, since nobody can show a bird relives anything. Hold on to that caution.
"The build is green" spoils within an hour. "Migrations live in migrations/" keeps for months. Claude Code stamps memory files with when they were written. What's missing is "good until": give each episode a shelf life, use absolute dates ("next Thursday" means nothing in December), and keep a log of what didn't work. Zep stores episodes losslessly, yet by vendor-reported numbers it scores 17.7% worse on questions about what the assistant itself said.
Knowledge without a memory
You know Warsaw sits on the Vistula. You don't remember the lesson. That's semantic memory: knowledge that forgot where it came from.
Frederic Bartlett had English listeners retell a Native American legend. "Canoes" became "boats"; whatever didn't fit vanished or got straightened. So the most precious lines in project notes are the exceptions, and they're the first to go.
In Claude Code, semantic memory is CLAUDE.md, and the docs' criterion is pure cognitive science: add an entry when Claude repeats a mistake. Write the why, not just the what. When a decision changes, don't delete the entry; mark it invalid as of today. Newer wins, history stays.
The hand knows better
Back to the mirror. H.M.'s hand learned with no memory of practice. That's procedural memory, and for agents it pays best. Voyager, a Minecraft agent with a library of skills stored as code, collected 3.3 times more unique items.
Claude Code splits this in two. Recipes go into skills, loaded when needed. What must happen every time goes into hooks, which run at fixed points no matter what the model decides. The docs say it plainly: CLAUDE.md is context, not configuration. The model reads it. It isn't obliged to obey.
A hook is the hand tracing the star with no consciousness involved. So sort rules by the cost of breaking them: must never fail, a hook; needs judgement, CLAUDE.md; long recipe, a skill.
The library on your way home
An overdue book sits in your bag. You forget it all day, until you walk past the library. That's prospective memory: memory for what you still have to do. Its enemy is interruption: in one study, two out of a hundred interrupted people thought about their intention during the break. For an agent, the break is the end of a session.
Here's the surprise. The research review behind this piece found no agent system that evaluates prospective memory as its own kind. Yet Claude Code has the mechanism: a rule with a paths: field loads exactly when Claude touches a matching file. The path is the library. Write intentions as "when you touch X, do Y", and delete the rule in the commit that does the job.
Moved sticks
The nutcracker hides over thirty thousand seeds and finds them up to nine months later. Researchers shifted the landmarks by about twenty centimetres, and the bird dug with exactly the same shift. It remembers places relative to the sticks.
Auto memory is a nutcracker's estate: MEMORY.md is the cache map, topic files are the seeds. At startup only the first 200 lines or 25 KB of the index load. Past that line nothing is "remembered faintly". It simply isn't there. Put important lines on top, pin facts to a path and a symbol, and after a refactor grep for orphaned anchors.
Sleep that reviews the day
You fall asleep, and the hippocampus replays the day, weaving it slowly into old knowledge, because writing it in directly would smash what's there. But sleep also adds false "gist": meanings nobody said.
Claude Code has the first pieces: /doctor prompt-audit hunts contradictions and stale entries. What's missing is replay. Imagine a nightly timer running a consolidation skill on a separate branch: for each fresh episode, add, update, invalidate or nothing, and a diff waiting for morning approval. A proposal, not a write, because sleep invents gist too. And sleep-time compute research found only moderate savings on code. Do it for hygiene, not cheaper tokens.
A memory open for editing
In 2000 Karim Nader showed that a recalled memory briefly turns unstable; a drug given right after recall erased it, six hours later it didn't. Elizabeth Loftus showed that information after an event contaminates memory; in "lost in the mall" studies about a third of people formed a partly or fully false one.
A note the model rewrites on every read drifts like a story told twenty times. So edit an entry only after checking it in code, keep raw episodes untouchable, and keep memory in git, where git diff shows reconsolidation in black and white.
The matriarch and the fruit fly
The fruit fly forgets on purpose: the dopamine that writes a trace can erase it. Forgetting is a filter. Yet in 1993, when drought hit a park in Tanzania, herds led by old matriarchs fared better, an edge credited to memories of a drought over thirty years earlier.
File memory never fades. It's cut off hard. So let entries expire unless they've proved their worth, archive instead of deleting, and give runbooks for rare failures matriarch status: they never expire.
The jay that was watched
When a jay caches food while another jay watches, it later moves the cache, but only if it has stolen itself. It even remembers who watched. It keeps a ledger of sources.
An entry from a web page, an issue or a dependency's README is a cache someone watched. In the MINJA study, malicious records were planted in an agent's memory through queries alone, in 98.2% of attempts. So every entry should know its source and confidence. Trust order: human, agent, tool, and tool-sourced entries wait in quarantine.
The ant doesn't remember
A harvester ant colony lives twenty, thirty years; a worker, one at most. The colony remembers through traces left in its surroundings.
Your subagents are workers and the repo is the colony. But give seven subagents their own worktrees and a status file exists in seven copies: seven truths. Ants never edit another's pheromone. So keep status outside the worktrees, say in the shared .git directory, one file per agent. A SubagentStop hook won't let an agent leave without a trace, and entries unrefreshed for a day evaporate into "stale".
Where these analogies lie
- One workbench. A brain keeps its drawers in different structures. CLAUDE.md, auto memory and rules all land in one context window and compete; only hooks are truly separate.
- "Episodic" is a metaphor. A dated note has a "when" but no "I". Say "-like", as the jay researchers did.
- Designed, not inherited. Limits quoted here come from the October 2026 docs. Check before you build.
- Biology argues with itself. Consolidation theories still clash.
- Vendor numbers. Mem0, Zep and Letta dispute each other's benchmarks, none measured on programming tasks.
Credit where due: the docs admit text memory doesn't guarantee obedience, and point to what does.
Cheat sheet
| Memory | In nature | Claude Code today | Proposal |
|---|---|---|---|
| Sensory | sieve | tool output | nothing raw |
| Working | ~4 things | context window | state file, tabu list |
| Episodic-like | jay | auto memory, timestamps | shelf life, failure log |
| Semantic | knowledge without origin | CLAUDE.md, rules | "why", invalidate |
| Procedural | H.M.'s hand | skills, hooks | costly rules as hooks |
| Prospective | library |
paths: rules |
"touch X, do Y" |
| Spatial | nutcracker |
MEMORY.md, 200 lines |
anchors, top first |
| Consolidation | sleep | /doctor prompt-audit |
nightly diff to approve |
| Reconsolidation | recall reopens | markdown | verify first, git |
| Forgetting | fly, elephants | hard cut | archive, matriarchs |
| Metamemory | watched jay | none | provenance, quarantine |
| Collective | ant colony | worktrees | status outside tree |
Tomorrow morning
-
Check what loads. Run
/context. Memory that doesn't load doesn't exist. -
Move gates into hooks. "No push without approval" is a
PreToolUseblock, not a sentence. - Measure the workbench. Main CLAUDE.md under 200 lines.
- Task state to a file that survives compaction.
- Pin one intention to a path.
- Schedule sleep. Fifteen minutes a week, in a calendar.
Six ideas from fresh eyes
A separate agent got the research review and one request: six mechanisms that aren't in it, no invented facts. It discarded its typical first thoughts, like a vector store. All six can be built today. None has been tested in practice.
1. Questioning the witness. Teams remember who knows what (Daniel Wegner's transactive memory). SessionEnd logs topic and session ID to who-knows.tsv, and a skill resumes that session as a fork (claude -p --resume <id> --fork-session) with one question: what did you learn about X, and why? It fails when transcripts are cleaned up, and the witness knows only that day's code.
2. A thymus for rules. The thymus kills cells that attack the body's own tissue. A candidate hook is replayed against old tool calls, counting how often it would have blocked successful sessions, and rejected above a threshold. If "self" includes a chronic bad habit, it rejects the very rule meant to fix it.
3. A bet before the test. Dopamine neurons fire for surprise, not for the expected. A hook refuses to run tests without a bet, green or red, and only mismatches become memory candidates. The agent may learn to bet defensively, and nobody checked that tool results carry exit codes.
4. Desire paths. People wear shortcuts into grass; paving only the worn paths is an anecdote the agent admits it can't document. A hook logs which files successful sessions read together and proposes paths: rules. Unfiltered, it also paves getting lost.
5. A soil seed bank. Seeds sleep for years and sprout after fire or ploughing. Archived episodes keep normalised error signatures; when a new error matches, a hook surfaces the old fix. Too coarse wakes false seeds, too fine wakes none, and messages change with library versions.
6. Mason's marks. Medieval masons carved marks into stone, usually read as accounting for work, though interpretations vary; either way, the information travelled with the block. Commits carry Why: and Gotcha: trailers that a hook surfaces through git blame before an edit, so memory follows the code through refactors. Squash merges and full rewrites break the chain, yet this is the one the agent would start with.
Coda
H.M. helped science for half a century without remembering one of its thousands of studies. His hand remembered the star. Your agent has one advantage over him: someone can write it a note.
The best memory knows how to forget. But it knows what it must never forget.
Originally written in Polish for the Kodownik reading room: https://kodown1k.github.io/czytelnia/sojka-orzechowka-i-claude-md/ — with hand-drawn diagrams and the full source list.
Main sources: Claude Code docs on memory and hooks; Memory systems of the brain (arXiv 2009.01083); Cowan 2001; MemGPT; Episodic-like memory; Nader et al. 2000; MINJA.
Top comments (0)