For most of the last year, the deal with AI coding agents was simple: they forgot everything. You'd spend a session teaching Claude your build commands, your test conventions, the one cursed workaround for that environment bug. The next morning it walked in like a new hire who'd never seen the place.
That deal is over. Claude Code now keeps notes. It writes them itself, organizes them while you sleep, and reads them before you've typed a word. This is a genuine upgrade. It is also the part of the system most likely to quietly lie to you, and almost nobody is reading the fine print.
So let's actually read it.
How it actually works
There isn't one memory system. There are four layers, and they do different jobs.
1. CLAUDE.md: the instructions you write. This is the original layer and the one most people already know. A plain markdown file Claude reads at the start of every session. You put your rules in it: "use pnpm, not npm," "write tests before implementation," folder structure, conventions. It's a briefing document. Claude treats it as context, not as enforced law. If you need something blocked regardless of what the model decides, that's a PreToolUse hook, not a memory file. Worth internalizing: CLAUDE.md is a suggestion engine, not a rule engine.
2. Auto Memory: the notes Claude writes itself. This is the new and interesting one. As Claude works, it decides what's worth keeping and writes it to disk without you asking. Build commands it discovered, debugging insights, your corrections, architectural decisions. It lives in plain markdown at ~/.claude/projects/<your-repo>/memory/, sorted into roughly four buckets: user (your role and preferences), feedback (your corrections), project (decisions and context), and reference (where things live). The distinction that matters: CLAUDE.md is your instructions to Claude. Auto Memory is Claude's notebook about you. It's on by default; /memory toggles it.
3. Session Memory: short-term recall. Conversation-level continuity so a session can pick up where the last one left off. The short-term layer sitting above the durable project knowledge.
4. Auto Dream: consolidation while you're away. This is the one with the neuroscience cosplay, and the name is not an accident. When Claude Code goes idle, by default after roughly 24 hours and at least 5 sessions, a background subagent runs a "dream": a reflective pass over the accumulated memory files. Its actual system prompt reportedly opens with a line about performing a reflective pass over memory. It runs a four-phase cycle (orient on the current project state, gather signal, consolidate, prune) that merges duplicate notes, resolves contradictions, and deletes stale entries, all while keeping the main index under a hard ceiling. You can trigger it by hand with /dream after a big change like a framework migration. You wake up and the memory file is shorter and sharper.
What a real one looks like
All of that is abstract until you actually open the file. Here's a representative MEMORY.md for a mid-sized TypeScript project, the kind of thing Claude assembles after a few weeks of use. Note that it's an index: the one-liners are the whole entry, and anything longer gets pushed into a topic file that only loads when Claude needs it.
# Project Memory: acme-dashboard
## User
- Prefers pnpm over npm. Never suggest npm commands.
- Wants tests written before implementation, no exceptions.
- Terse PR descriptions. No emoji, no "this PR..." preamble.
## Project
- Monorepo. Apps in apps/, shared code in packages/.
- Build: `pnpm -w build`. Type-check: `pnpm -w typecheck`.
- Auth flow lives in packages/auth. See auth.md before touching it.
- API routes are file-based under apps/web/src/routes/api.
- DB is Postgres via Drizzle. Migrations: `pnpm db:migrate`.
## Feedback
- 2026-05-02: Stop importing from src/ across package boundaries.
Use the package's public export. (corrected twice)
- 2026-05-09: Don't add try/catch around route handlers; the
framework already wraps them. See error-handling.md.
- 2026-05-14: I asked you to reuse the existing date helper in
date-utils.md, not write a new one. Check for helpers first.
## Reference
- Env vars and what they do -> env.md
- Deployment + rollback steps -> deploy.md
- Known flaky tests and why -> flaky-tests.md
- Drizzle gotchas we keep hitting -> drizzle-notes.md
That's a healthy file. It's short, every line earns its place, and the long stuff is offloaded to topic files behind pointers. The trouble is that a healthy file is the starting condition, not the steady state. Six weeks from now the feedback section has fifteen entries, two of them contradict each other, one references a file that's been deleted, and the whole thing is brushing up against the line limit. More on that below.
Put together: an instruction manual, a note-taker, short-term recall, and REM sleep. That's a recognizable cognitive architecture, assembled quietly over a few months. It's a real engineering achievement, and I don't want to undersell it.
What's genuinely good
The thing it fixes is the thing that made agents feel like demos instead of colleagues. Start a session on a months-old project and Claude already knows the build command, the test flags, the naming conventions, and the three corrections you made last week. That head start is not cosmetic. It's the difference between an agent that re-asks setup questions every morning and one that gets to work.
The corrections loop is the underrated part. You don't have to stop and document things. You correct Claude once, it writes the correction to the feedback bucket, and (in theory) it stops making that mistake. Knowledge accumulates from use rather than from discipline, which is good, because nobody actually maintains the docs.
And the whole thing is plain markdown on your disk. No vector store, no black box. You can cat it, edit it, delete entries, reorganize it. For a v1, that transparency is the right call. You can see exactly what your agent thinks it knows.
What's scary
Here's the part the launch posts skip.
The memory cliff is real, and it's silent. The main index, MEMORY.md, has a 200-line hard limit. Only the first 200 lines get loaded into context at the start of a session. The write path doesn't check against this. So Claude happily appends a new memory, you see "memory saved," and if that pushes the file past line 200, the entry exists on disk but is never loaded again. No error. No warning. It's documented now only because users filed bug reports after watching the model repeat mistakes that the memory entries were written specifically to prevent. The freshness warnings that are supposed to flag stale memories? They only fire for memories that got loaded. A truncated-out memory never loads, so it never warns. Claude doesn't know what it doesn't know, and neither do you, unless you go digging in the files.
Accumulated memory drifts away from truth. This is subtler and worse. Individual sessions feel fine. But over weeks, the notebook fills with contradictory corrections, fixes that reference deleted files, relative dates like "yesterday" that have lost all meaning, and self-referential notes about your preferences that nobody ever re-checks. There's no built-in expiry asking "does this correction still apply?" The gap between what Claude "knows" and what's actually true widens one quiet entry at a time. The agent gets more confident as it gets more wrong.
Dreaming is consolidation, not verification. This is the one I'd watch. Auto Dream's job is to make the memory coherent: prune contradictions, merge duplicates, reduce noise. But "coherent" is not "correct." If two notes contradict each other and one of them is wrong, a consolidation pass can resolve the contradiction by keeping the wrong one and deleting the evidence that would have flagged it. You've now laundered a mistake into clean, confident, well-organized memory. The cleanup that makes the notebook readable is the same cleanup that can erase the trail. And it runs in the background, on its own schedule, without showing you the diff.
None of these are exotic. They're the predictable failure modes of any system that writes to its own memory faster than anyone audits it. The agent that improves through use is, structurally, the same agent that degrades through use. Which one you get depends entirely on whether anyone is watching the files, and the entire pitch of auto memory is that you don't have to.
So what do you actually do
You don't turn it off. The upside is too real. But you stop treating the memory as ground truth.
Read your MEMORY.md occasionally. Actually open it, watch the line count, move detail into topic files before you hit the ceiling. Skim what /dream did instead of trusting it blind. Treat the feedback bucket like any other accumulating log: assume some of it is stale until proven otherwise. The same instinct good engineers already have about config files that drift out of sync with reality, where the file says one thing and the codebase does another, now applies to the agent's own head.
That gap between what the config claims and what's actually true is the whole reason I've been building Blume. It just turns out the agent's memory is now one more file that can quietly disagree with everything else.
The forgetful agent was annoying but honest. It never pretended to know your project. The remembering agent is far more useful and slightly more dangerous, because it will tell you with total confidence about a workaround for a file you deleted in March. Memory didn't make the agent smarter. It made it certain. Those are not the same thing, and the difference is now your job to manage.