Claude Code Memory: The Complete Guide to Persistent Context

Every Claude Code session starts the same way: no memory of yesterday. You spend twenty minutes explaining your API’s auth flow on Monday, and on Tuesday you’re explaining it again, because nothing about how the model works carries that forward on its own. That gap is the single most requested fix we hear from teams running Claude Code daily, and it’s also the most misunderstood, because “give Claude memory” isn’t one feature. It’s four mechanisms with different jobs, costs, and failure modes.

This guide sorts them out: what each layer actually solves, what belongs in which one, how to set up a memory skill like claude-mem, and the token math that explains why remembering is cheap while re-discovering the same facts every session is not.

The groundhog-day problem

A language model has no state between API calls. Every message you send includes the entire conversation so far, and when that conversation ends, so does everything the model “knew” about your project. Open a new session tomorrow and you’re back to a blank slate, whatever files happen to sit on disk notwithstanding.

That would be fine if sessions were short and self-contained. They aren’t. Real work spans days: you fix a bug on Monday, the same pattern shows up in a different file on Thursday, and the agent has no way to connect the two unless something outside the conversation carried that connection forward. Every session without it pays a re-discovery tax: reading the same files, re-learning the same conventions, occasionally repeating a mistake it already fixed.

The fix isn’t a bigger context window. Context windows are large already, and the problem isn’t capacity, it’s continuity. What you want is a place outside the conversation where facts and decisions survive, plus a way for Claude to load the right slice of that place back in when it matters. That’s memory, and Claude Code gives you four ways to build it.

The four layers of Claude memory

Layer one is CLAUDE.md: static project facts you write once, that load in full at the start of every session. Layer two is auto-memory, a directory of files Claude writes to itself, accumulating facts over time without you authoring them by hand. Layer three is memory skills, which capture and compress session context automatically and inject it back later. Layer four is the low-tech option: a plain notes file the agent reads and updates because you told it to.

They aren’t competing options. They solve different problems, and most serious setups run two or three at once.

Layer 1: CLAUDE.md, static facts that always load

CLAUDE.md is Claude Code’s oldest and simplest memory mechanism. It’s a markdown file Claude Code finds by walking up from your working directory, and it loads in full, every session, before you type anything. That makes it the right place for facts that are true almost always: how to run the tests, which package manager the repo uses, which folder is legacy and off-limits.

It’s the wrong place for anything that changes often or applies occasionally, because “loads in full, every session” is also its cost. A 3,000-line CLAUDE.md is roughly 30,000 tokens taxed on every request, whether that request needs any of it or not. We cover the full arithmetic and a real annotated example in our CLAUDE.md best-practices guide; the short version is that CLAUDE.md wants stable facts, not a growing log.

That’s also where CLAUDE.md runs out of road. It’s static: you write it, Claude reads it, and updating it is a manual chore you have to remember to do. The next three layers exist to handle facts that accrue on their own.

Layer 2: auto-memory and memory directories

The middle layer is a memory directory, often ~/.claude/memory/ or a project-local equivalent, where Claude writes structured notes about what it learns and reads them back at the start of future sessions. Unlike CLAUDE.md, nobody hand-authors most of these entries. The agent decides something is worth remembering, a decision you made, a preference you stated, a fact it had to dig for, and files it away with enough structure to retrieve later.

This is where the Memory Management skill lives, and it’s the highest-rated skill in this category on SkillProof: 9.2 out of 10. We ran it over a full week of real sessions, not a single demo run, and it held up under actual use. Claude reliably recalled project decisions and preferences it had stored, and recall precision stayed high even as the store grew, the part that usually breaks first in naive implementations.

What separates this layer from CLAUDE.md is that it’s selective on the way back in as well as the way in. A well-built memory skill indexes what it has stored and pulls the relevant slice for the current task, so the store can grow into the thousands of entries without every session paying for all of them.

Layer 3: memory skills, claude-mem and automatic capture

The third layer takes the idea further. Instead of Claude deciding mid-conversation what’s worth saving, a dedicated skill captures the whole session automatically, compresses it, and injects the relevant context back into the next one. Claude-mem is the clearest example of this pattern. Its pitch is “persistent context across sessions for every agent”: it watches what your agent does during a session, compresses that activity with an AI summarization pass, and surfaces the compressed version the next time it’s relevant, across Claude Code and, according to its own docs, several other agent runtimes.

We should be straight about where it stands in our testing. Claude-mem showed up through our GitHub crawler with 85,685 stars, which is why it’s queued for a full test rather than already carrying a verdict; we don’t publish a score until we’ve installed a skill clean and run it against real work, the same bar Memory Management already cleared. What we can say now is architectural: automatic capture removes the moment where you’d otherwise stop and decide, mid-session, whether something is worth remembering. The skill decides for you. Whether it holds up over a full week on a clean machine is what the test queue exists to answer.

Layer 4: plain files as memory

The last layer needs no skill at all: a plain markdown file, usually called something like notes.md or progress.md, that you ask Claude to read at the start of a session and update at the end. No indexing, no automatic capture, no scoring. You’re the memory system; the file is just where you write it down.

This layer gets underrated because it sounds too simple to matter. It isn’t. For a solo project with one contributor and a handful of ongoing threads, a notes file you actually maintain beats an automated memory system you never look at. The failure mode sits entirely with you, though: nobody prunes it, nobody flags contradictions, and it grows into a wall of text with the same blind spots any unmaintained document develops. It works exactly as well as your discipline about updating it, no better.

What belongs where: the decision table

Memory type	Best for	Loads	Maintenance
CLAUDE.md	Stable, always-true facts (build commands, conventions, gotchas)	In full, every session	Manual, edit by hand
Auto-memory / memory directory	Decisions and preferences that accrue over time	Selectively, on retrieval	Mostly automatic (skill-managed)
Memory skills (claude-mem)	Full session context, captured without you deciding what matters	Compressed, injected when relevant	Automatic capture, occasional review
Plain notes file	Solo projects, simple ongoing threads	Manual, you tell Claude to read it	Fully manual

Read that table by what changes, not by what’s convenient to set up. If a fact would still be true in six months, it belongs in CLAUDE.md. If it’s a decision made this week that might matter again later, it belongs in memory. If you can’t predict what you’ll need to remember and don’t want to decide in the moment, that’s the case for automatic capture. If none of that applies, a notes file still beats nothing.

Setting up claude-mem, step by step

The general pattern for an automatic-capture memory skill looks like this, using claude-mem as the concrete example:

1. Clone the skill. git clone https://github.com/thedotmack/claude-mem into a working directory, then follow the repo’s install script instead of copying files by hand. Memory skills usually need to register a hook, not only drop a SKILL.md into place.

2. Restart Claude Code. The install typically wires a session-start or session-end hook so capture happens without you invoking anything. A restart is what picks that hook up.

3. Run a normal session. Don’t test it with a toy task. Do real work; the point is seeing what it decides is worth remembering when nobody’s watching for the test.

4. Start your next session and check what came back. Ask Claude what it remembers about yesterday’s work before you say anything else. Something specific and correct means capture is working. Anything vague or wrong means check the config before trusting it with something that matters.

5. Set a review cadence. Automatic capture without review turns into automatic accumulation of noise. Give yourself a recurring ten-minute slot to skim what’s been stored (more on this under memory hygiene, below).

If you’d rather start with something already scored, Memory Management is the manual-but-tested route: install the skill folder into ~/.claude/skills/, and it creates its own memory directory on first use, no separate hook install required.

The token economics of memory

Here’s the math that makes memory worth the setup cost. Say a project fact takes 500 words to explain from scratch: the shape of your auth flow, why a certain table has two foreign keys, what the deploy script actually does. Explained fresh in chat, that’s roughly 650 tokens of input every time you re-explain it, on top of the time you spend typing it and the time Claude spends reasoning over it in that message.

Stored in memory instead, the same fact costs those 650 tokens once, to write. Retrieval afterward costs a fraction of that: a well-indexed memory layer pulls a compressed summary, often under 100 tokens, only when the current task touches that fact. Explain it in chat five times over a month and you’ve spent roughly 3,250 tokens re-teaching what memory would have cost 650 tokens to learn and 500 total to recall five times: a rough five-to-one gap that widens the more often the fact gets needed.

Compare that with cramming everything into CLAUDE.md instead: a fact relevant one session in twenty still gets loaded on the other nineteen, with no selectivity to reclaim that cost. The fixed preamble your setup carries on every turn (CLAUDE.md, tool schemas, memory injections) competes directly with your actual work for space and attention. We measured this in more depth, with real before/after token counts, in our token cost guide; memory is one line item in that bigger picture, often the cheapest fix relative to what it saves.

Memory hygiene: the review ritual

A memory system that only accumulates isn’t a feature, it’s a slow leak. Stale entries don’t fail loudly; nothing crashes when Claude recalls a decision you reversed three weeks ago. It just quietly acts on outdated information, and you burn debugging time figuring out why the agent is confidently wrong about something you know you fixed.

Run a monthly pass, ten minutes, the same discipline as the CLAUDE.md review ritual we recommend elsewhere. Open the memory store. For each entry that looks load-bearing, ask whether it’s still true, whether a decision it describes got reversed since, and whether it’s specific enough to act on. Delete anything that fails. A memory store you’re proud of is smaller a year in than it was three months in; the growth should be in precision, not volume.

The most reliable trigger for a review isn’t the calendar, though. It’s the moment Claude does something wrong because of a stale memory. Treat that like a bug: fix the entry in the same breath as the mistake, not on your next scheduled pass.

Privacy: what gets captured, where it lives

Memory skills read what happens in your sessions, so the honest question is what gets captured and where it ends up. For file-based memory, Memory Management, claude-mem, and the plain-notes approach alike, the answer is usually the same: everything is written to plain files on your own disk, typically under ~/.claude/ or a project-local memory folder, not to a third-party server. Nothing leaves your machine unless you commit those files to a shared repo or a skill explicitly documents a remote sync feature.

That’s good news for control and bad news for assuming it’s automatically safe. A memory file is a plaintext record of what you worked on, and it can include credentials mentioned in passing, client names, or architecture details you wouldn’t want in a public repo. Read what’s actually in a memory directory before committing it alongside your code, and before installing any memory skill, check its source for what “captures everything your agent does” really means, including whether command output containing secrets gets swept in too. Automatic capture earns the same scrutiny as any tool that reads your terminal.

FAQ

Does Claude Code have built-in persistent memory?

Partially. CLAUDE.md gives you static, always-loaded memory out of the box, and it’s genuinely built in, no install required. Anything beyond static facts, memory that accrues, gets indexed, and gets selectively retrieved, currently comes from a skill rather than a native feature.

What’s the difference between CLAUDE.md and a memory skill?

CLAUDE.md loads in full, every session, and you maintain it by hand. A memory skill writes and reads a growing store selectively, pulling only what’s relevant to the current task, and much of the writing happens without you doing it manually. Use CLAUDE.md for facts that never change; use a memory skill for facts that accumulate.

Is claude-mem safe to install right now?

We can’t give it a verdict yet. It’s in our test queue, not scored, despite its large following on GitHub. Install it the way you’d install anything unscored: on a project you can afford to experiment in first, and read the source before trusting it with sensitive sessions.

How much does running a memory skill cost in tokens?

Less than the alternative in almost every case. Storage itself is nearly free since it lives on disk, not in context. Retrieval at session start typically costs far less than re-explaining the same fact in chat, and the gap widens the more times that fact would otherwise get re-explained.

Should I use more than one memory layer at once?

Yes, and most working setups do: CLAUDE.md for facts that never change, plus either a memory skill or a disciplined notes file for facts that accrue. Treat them as complementary rather than picking a favorite. The point is matching each type of fact to the layer built for it, not settling on one mechanism for everything.