Memory System: Make it remember you across sessions

📚 Series Navigation: The previous article [24 Plugins] taught you how to package a bunch of fragmented configurations into plugins that can be installed and stopped with one click. This article talks about something more fundamental—how to make Claude remember you across sessions. It's not just the CLAUDE.md you handwrite, but also the "private notes" it accumulates while working. If you correct it once, it quietly writes it down, and automatically remembers it next time it starts working.

Let's start with a pitfall that beginners are particularly prone to stepping into.

When you first touch the "ability to make Claude remember things" feature, it's easy to treat it like a treasure and stuff everything into it: stuffing in a port number you successfully configured today, stuffing in a renamed temporary variable, even stuffing in one-off trivialities like "use 8081 instead of 8080 this time." The underlying logic is often "the more it remembers, the smarter it gets."

The result? When you open the project again two weeks later, it opens its mouth and mentions that long-abandoned 8081 port, along with a few "preferences" that even you forgot why you wrote. It remembered a brainful of useless things, while the things it truly should have remembered were drowned out.

This is when you'll finally understand: Memory is not a matter of stuffing as much as possible; it's about "remembering what should be remembered accurately, and leaving what shouldn't alone." Remembering wrong is worse than not remembering at all—it will use outdated information to mislead you with a straight face.

Earlier in [18 CLAUDE.md Usage Guide] we specifically talked about how to write CLAUDE.md, and [19 Context Management] also repeatedly mentioned that "auto-memory takes up context." But how exactly these two pieces mesh into a complete "memory system," and how that notebook Claude writes itself actually operates, was never fully explained. Today, we'll fill that gap.

After reading this article, you will get:

• What two sets Claude Code's memory is actually divided into: CLAUDE.md written by you vs "auto-memory" written by itself, and a table to see who manages what clearly
• Which file "auto-memory" is saved in, how it gets loaded into context, and how to audit and edit/delete it using /memory
• How to make it remember a specific item, where it lands after being remembered, and how it automatically takes effect next time, taking you through it step by step
• A checklist of "what to remember vs what not to remember" to help you avoid the "stuff everything" pitfall
• Whether the old shortcut # can still be used, and what the official correct practice is now

---

01 First distinguish: Memory is actually two sets, not one

Let's give the conclusion first: Claude Code's "memory" is two parallel systems, one written by you and one written by itself, each managing its own. When many people mention "memory," they only think of CLAUDE.md, but that's actually only half of it.

Analogy: Sticky notes stuck to the edge of the monitor. You often have two types of paper on your desk. One is the formal "work rules" you printed out and pinned to the partition with thumbtacks—project rules, submission workflows, written neatly for anyone to follow; this is CLAUDE.md. The other is a sticky note you casually tear off, write a sentence like "the bug last time was because the cache wasn't cleared," and stick it to the edge of the monitor, so you remember it at a glance next time—this kind of small note it casually writes for itself is "auto-memory." Both types of paper are right in front of your eyes, but one is "the rules I set," and the other is "the insights I noted down in passing."

The official documentation explains the division of labor between these two sets very clearly, organized into a comparison table—this is the most important one to remember first in this article:

Dimension	CLAUDE.md File	Auto-memory
Who writes it	You (manual writing)	Claude (writes it itself)
What it contains	Instructions and rules	Experiences and patterns it learned
Typical content	Coding standards, workflows, project architecture	Build commands, debugging insights, your preferences it discovered
When it's loaded	Every session, fully loaded	Every session, but only loads the first 200 lines or 25KB
Scope	User / Project / Local level	One copy per git repository (shared across all worktrees)

See the key difference? CLAUDE.md is "how you want it to do things," and auto-memory is "how it figured out to do things on its own." If you correct it with "running tests for this project requires starting local Redis first," it will remember it next time—you don't need to manually write this into any file, it saves it itself.

There's another cognition repeatedly emphasized by officials that you must thoroughly understand first:

Claude treats them as context, not mandatory configuration. To prevent an action, regardless of what Claude decides, use the PreToolUse hook instead.

What does this mean? Memory (no matter which set) is just a soft prompt that "affects what it wants to do," not a hard constraint that "locks down what it can do." This is consistent with the conclusion in the [20 Permissions Configuration] article—if you really want to block a certain action completely, you have to rely on permission rules or hooks; just writing "do not push" in memory won't stop it. Memory is responsible for "making it understand you better," not for "gatekeeping for you."

💡 One-sentence summary: Memory is divided into two sets—CLAUDE.md where you handwrite rules, and auto-memory where it writes insights itself; both sets are just soft prompts, and if you want to truly block an action, you must rely on permissions or hooks, as simply writing it into memory doesn't guarantee everything is fine.

This diagram draws the two memory paths side by side: on the left is CLAUDE.md (project rules) that you handwrite and is fully loaded into the context; on the right is the auto-memory (private notes) that Claude writes into MEMORY.md while working and reads back the first 200 lines for the next session. Both paths eventually merge into the "context window of the new session," letting it "remember you" as soon as it starts working.

---

02 The Position of CLAUDE.md in the Memory System

The writing method of CLAUDE.md has already been detailed in [18], so I'll just add one sentence about the role it plays in the "memory system"—it is that pinned, formal "work rule" that everyone must read.

Analogy: Still those two types of paper next to the monitor, CLAUDE.md is the pinned one. It's not a casually torn sticky note; it's a formal rule you seriously printed and pinned securely with thumbtacks. Therefore, it has a few characteristics that are completely different from auto-memory: written by you, version-controlled and shared by the whole team, fully loaded every session, and the content is "rules" not "insights".

The officials have clearly layered CLAUDE.md, and according to the load order (from broadest to most specific), it looks like this:

Level	Location	Who it manages
Managed Policy Level	macOS: /Library/Application Support/ClaudeCode/CLAUDE.md Linux/WSL: /etc/claude-code/CLAUDE.md	Issued uniformly by Enterprise IT, generally not involving individuals
User Level	~/.claude/CLAUDE.md	Your personal preferences across all projects
Project Level	./CLAUDE.md or ./.claude/CLAUDE.md	This project, shared by the whole team (committed to git)
Local Level	./CLAUDE.local.md	This project, only for yourself (added to .gitignore)

There is a key difference from auto-memory here that beginners should remember most firmly:

CLAUDE.md is fully loaded no matter how long it is, while auto-memory has an upper limit. In the official words—"CLAUDE.md files are loaded entirely regardless of length." That's why [18] repeatedly advised you to keep it under 200 lines: not because it can't be loaded, but because the longer it is, the more context it occupies, and the worse it actually complies. Auto-memory, on the contrary, has a hard limit (detailed in the next section), and the part exceeding it isn't loaded at all.

In practice, the division of labor can be very clear: "These are the hard rules you set" goes into CLAUDE.md, and "this is what it should figure out and accumulate on its own" is left to auto-memory. For example, an ironclad rule like "only use pnpm for dependencies" is handwritten into CLAUDE.md; whereas something it can discover itself like "tests for this project need to start Redis," doesn't need to be handwritten—correct it once and let it remember it itself.

💡 One-sentence summary: CLAUDE.md is that "pinned formal rule" in the memory system—written by you, shared by the team, fully loaded, and contains rules; its positioning is completely different from the auto-memory of "insights it casually notes down itself."

---

03 Auto-memory: The Notebook It Writes Itself

Here comes the focal point, which is also the main topic left for this article in [18]—auto-memory, the notebook Claude keeps for itself while working.

ℹ️ Auto-memory requires Claude Code v2.1.59 or higher and is enabled by default. Type claude --version to check your version; if it's too old, upgrade it (for upgrade methods, see [02 Installation]).

Analogy: An old partner you've worked with for a long time. With a partner you've collaborated with for a while, there are some things you simply don't need to explain repeatedly—he will remember them in his head himself: "This project build needs to run make build, not npm build," "the sporadic bug last time was because the timezone wasn't set correctly." The next time he encounters something similar, he recalls it himself. You don't need to explain; he accumulates knowledge as he works—auto-memory is this "proactive learning" ability of Claude.

What exactly does it record? The official checklist: build commands, debugging insights, architectural notes, code style preferences, and workflow habits. Notice a key design—it doesn't record everything into it every session, but rather "decides whether it's worth remembering based on whether this piece of information will still be useful in future conversations." It generally won't record one-off trivialities (this point exactly cures the "stuff everything" disease).

So how does it actually write them down? Two trigger methods:

First, you tell it directly to remember. Say in the conversation, "In the future, always use pnpm for this project, not npm" or "Remember that API tests require a local Redis instance," and it will save this into auto-memory. The official original text:

When you ask Claude to remember something, such as "always use pnpm instead of npm" or "remember that API tests require a local Redis instance", Claude saves it to auto-memory.

Second, it learns on its own from your corrections. You don't need to explicitly say "remember," as long as you correct it once—for example, it uses npm test and you say "this project uses pnpm test"—it judges that this will be useful in the future, so it writes it down itself. This is the sweetest part of auto-memory: you work normally, correct normally, and it silently accumulates in the background with zero extra effort.

How do you know it's currently recording? Look at the interface prompts. Officially, when you see "Writing memory" or "Recalled memory" pop up in the Claude Code interface, it means it's writing into or reading from that notebook.

💡 One-sentence summary: Auto-memory is the sticky notes Claude writes itself—you tell it to remember, or it self-learns from your corrections, only recording what will be "useful in the future"; seeing the "Writing/Recalled memory" prompt means it's taking notes or flipping through its notebook.

---

04 Where It Is Stored and How It Gets Loaded Into Context

This section solves two most practical questions: Which file is this notebook actually stored in? And how is it stuffed into the context to make Claude "remember"? The latter half exactly echoes context management covered in [19].

Storage location, the officials have fixed it dead—one independent memory directory per project:

~/.claude/projects/<project>/memory/
├── MEMORY.md          # Concise index, loaded every session
├── debugging.md       # Detailed notes related to debugging
├── api-conventions.md # API design decisions
└── ...                # Other topic files created by Claude itself

Let's break down a few key points:

MEMORY.md is the entry point and index. It's like the "table of contents" in the sticky notes; Claude uses it to track "what have I remembered?" It splits detailed content into topic files like debugging.md and api-conventions.md to prevent MEMORY.md from rolling on and getting too long.

This <project> name is calculated by git repository. So—all worktrees and subdirectories of the same repository share this single copy of auto-memory. This point is different from CLAUDE.md (CLAUDE.md is concatenated based on the directory tree).

It is local to the machine and does not sync across devices. What you remember on this computer won't be on another computer. Also, don't expect it to go into git—it just stays under your ~/.claude.

Next is the mechanism you should understand the most—how it gets loaded into context, which is strictly defined by the officials:

The first 200 lines or 25KB of MEMORY.md (whichever comes first) are loaded at the start of every conversation. Content beyond this threshold is not loaded at session start.

Translated into human terms, three layers of meaning:

1. Every new session automatically reads back the first 200 lines of MEMORY.md (or 25KB, whichever comes first). This is the principle of its "remembering across sessions"—what it remembered last time automatically enters the context at the start of this time.
2. The part exceeding 200 lines / 25KB is not loaded at the start. Therefore, Claude will proactively keep MEMORY.md concise, tossing details into topic files.
3. Topic files (like debugging.md) are also not loaded at the start; it reads them on-demand using file tools when needed—the same reasoning as the "on-demand loading of subdirectory CLAUDE.md" covered in [18].

Comparing the loading rules of CLAUDE.md and auto-memory together, the difference is obvious at a glance:

	CLAUDE.md	Auto-memory MEMORY.md
How much is loaded	Fully, loaded no matter how long	Only the first 200 lines / 25KB
Exceeding part	Still fully loaded (so you are advised to write it short)	Not loaded at start, read on-demand
Who maintains conciseness	You manually delete	Claude automatically splits

Understanding this upper limit, you will understand why it won't "burst" the context with memories—auto-memory inherently comes with a 200-line floodgate, whereas the floodgate for CLAUDE.md must be controlled by you.

💡 One-sentence summary: Auto-memory is stored in ~/.claude/projects/<project>/memory/MEMORY.md, divided by git repository, local to the machine, and shared by worktrees; every start it only reads back the first 200 lines / 25KB, and exceeding parts are split into topic files to read on-demand—so it has an inherent upper limit and won't burst the context.

---

05 /memory: Auditing, Editing, Toggling, All in One Command

The most reassuring thing about auto-memory is—since it writes it itself, what if it remembers wrong or remembers outdated things? (The pitfall with the 8081 port at the beginning came exactly from this.) The answer given by the officials is one command: /memory.

Analogy: A stack of sticky notes you can lift and look at anytime. The notes it takes itself are not a black box; you can lift them to read anytime and tear them off anytime you want. /memory is the action of "lifting up to look."

When you type /memory in a session, it does three things:

1. Lists all memory files loaded in the current session—including CLAUDE.md, CLAUDE.local.md, rule files, and auto-memory. If you suspect it "remembered something wrong," first use this to check what exactly was loaded.
2. Provides an entry to open the auto-memory folder—click once to enter the memory/ directory, and those files are all pure markdown; you can read, edit, and delete them at any time. For that piece it remembered wrong, just delete it directly.
3. Toggles the auto-memory switch—if you don't want it to automatically remember anymore, you can turn it off here.

Besides using /memory in the session, there are two official ways to "nail the switch dead":

Turn off auto-memory in settings.json (Project-level, takes effect long-term in the config file):

{
  "autoMemoryEnabled": false
}

Or turn it off temporarily using an environment variable (just set CLAUDE_CODE_DISABLE_AUTO_MEMORY=1).

It's worth cultivating a habit: Every once in a while, type /memory to lift open the notebook for your own project and scan through it. You can often clear out a few items that should have been deleted long ago—a swapped port, an abandoned interface convention, a "preference" that even you can't understand. It takes two minutes and saves it from misleading you with outdated information one day. This is exactly the lesson to be learned from that 8081 pitfall.

💡 One-sentence summary: The /memory command lays out the whole memory system—lists which files are loaded, opens the auto-memory folder to read/edit/delete at any time, and can toggle auto-memory; periodically lifting it up to scan and clear out outdated items is the simplest way to cure "it remembering wrong."

---

06 What to Remember and What Not to Remember: Don't Repeat the "Stuff Everything" Mistake

After explaining the mechanics, it comes down to the most practical judgment—what is worth making it remember, and what shouldn't be touched at all. This section is entirely made of lessons bought with hard-earned pitfalls.

The good news is that auto-memory is relatively restrained by default (only recording what will be "useful in the future"). But when you actively ask it to remember, you have to act as the gatekeeper yourself—if you say "remember xxx," it generally will truly remember it, and whether to gatekeep or not depends entirely on you.

Here is the comparison table directly, on the left are things you'll regret stuffing, on the right are things truly worth remembering:

❌ Don't let it remember (One-off / Will change / Sensitive)	✅ Worth remembering (Stable / Reusable / Project-specific)
"Use port 8081 this time" (One-off)	"The build command is make build, not npm build"
"Temporarily change this variable to tmp" (Temporary)	"Tests for this project need to start local Redis first"
"Just run it like this for this version" (Will change soon)	"The root cause of the sporadic bug last time was that the timezone wasn't set" (Debugging insight)
Database passwords / API keys / tokens (Sensitive!)	"Unify dates to use ISO 8601 format" (Convention preference)
"I am debugging the login page right now" (Temporary status for this time)	"Authentication logic is all in src/auth/" (Architectural fact)

Three judging principles, just remember these three words:

First is "will it change." Things that are one-off, about to change, or "just for now" should not be recorded at all—their shelf life is shorter than your current session, and recording them is just digging a hole for the future. That 8081 is a classic example; it's useful at the moment of successful debugging, but two days later it's misleading.

Second is "can it be reused." If it's only useful this time ("I am debugging X right now"), don't record it; only if it will still be useful next time, or the time after (build commands, architectural facts, pitfalls you stepped in), is it worth recording.

Third is "is it sensitive." This is a red line—passwords, tokens, API keys and the like must absolutely not go into any memory file. Auto-memory is stored in pure markdown plaintext on your hard drive, and recording secrets into it is equivalent to writing them to disk in plaintext. This aligns with global security constraints: sensitive information doesn't go into code, doesn't go into commits, doesn't go into logs, and naturally doesn't go into memory either.

Before letting it remember something, pass it through these three checkpoints in your mind: Will it change? Will it still be used in the future? Is it sensitive? Only let it remember if it passes all three. After gatekeeping like this, its notebook will be much cleaner, and it won't mislead you with outdated information anymore.

💡 One-sentence summary: Pass three checkpoints before remembering—don't remember things that will change, don't remember things used only once, and absolutely don't remember sensitive things; only remember those "stable, reusable, project-specific" facts and insights, and don't stuff everything into it.

---

07 The old # shortcut, can it still be used?

ℹ️ # is an early old practice, and new versions no longer use this interaction. Many old tutorials and videos still teach "use a # at the beginning to quickly append memory," just forget it. The correct entry point now: say "remember xxx" to save into auto-memory, say "add to CLAUDE.md" to save into git rules, and use /memory for auditing, editing, and deleting.

A pitfall beginners easily step into: Just saying "remember xxx", it defaults to saving into auto-memory (local to machine), which does not mean it went into CLAUDE.md (into git, shared by team). If you want the whole team to see a certain rule, you must explicitly say "add to CLAUDE.md." A difference of one phrase makes a world of difference in sharing scope.

💡 One-sentence summary: # is outdated, don't use it; "remember xxx" goes into auto-memory, "add to CLAUDE.md" goes into git—the two are not the same thing, if you want to share, say it fully.

---

08 Hands-on: Remember one item, see where it lands, and automatically take effect next time

Just reading without practicing doesn't count as knowing. Here, I'll take you completely through it once: Have it remember one item → Confirm it landed in the auto-memory file → Verify it automatically remembers next session. A minimal example all the way through, not relying on any complex environment.

ℹ️ Prerequisite: claude --version ≥ v2.1.59, and auto-memory is not turned off (enabled by default).

Step One: Create a toy project and start Claude (Mac / Linux)

mkdir memory-demo
cd memory-demo
claude

Expectation: Enter the Claude Code session interface, with an input box at the bottom.

Step Two: Let it remember one item

Type in the input box (using a typical, worth-remembering "build command"):

Remember: The build command for this project is make build, not npm build

Expectation: Claude responds that it has noted it, and a prompt like "Writing memory" will flash on the interface—seeing this prompt means it is writing into that notebook.

Step Three: Use /memory to confirm which file it landed in

Immediately type:

/memory

Expectation: The memory management interface pops up, listing all memory files loaded currently. You can see the entry for auto-memory, click into it, and you'll see MEMORY.md, which contains the record of that make build from just now. Seeing it in the file = this item has transformed from "just saying it in chat" to "a written note on disk."

If you want to confirm directly from the command line, open another terminal and type:

cat ~/.claude/projects/*memory-demo*/memory/MEMORY.md

Expectation: You can see the build command you just noted down in the output (the specific <project> name in the path depends on your directory, just use * wildcard). Pure markdown, readable at a glance.

Step Four: Verify it automatically takes effect in the next session

This step is the key—the meaning of memory lies in "cross-session". Exit the current session:

/exit

Then restart it, and ask it a question that would use that piece of memory again:

claude

After entering, type:

How is this project built?

Expectation: It will directly tell you to use make build (instead of blindly guessing npm build)—and you might see the "Recalled memory" prompt, indicating that it read back the content recorded last time from the notebook. It answered correctly in a brand new session = the cross-session memory ran completely successfully, congratulations!

Step Five (Optional): Clear this item and verify the deletion also takes effect

Type /memory, enter the auto-memory folder, delete that make build item, and save it to disk. The next time you ask "how to build", it will no longer assertively report make build—the wrongly remembered item, once deleted, is gone, and this is exactly the power of "lifting it up and tearing it off" given to you by /memory.

By running through these five steps, you have personally verified the entire chain of "remembering an item → saving to disk → automatically recalling cross-session → auditing/editing/deleting anytime". From now on, all gameplay related to memory is essentially built upon this set of mechanisms.

💡 One-sentence summary: Have it "remember xxx" → see the "Writing memory" prompt → use /memory or cat to confirm it landed in MEMORY.md → exit and re-enter, it "Recalled memory" and answers correctly automatically → use /memory to edit/delete when needed. Personally running through this chain is more useful than memorizing ten concepts.

---

09 Summary

This article has completely straightened out Claude Code's "memory system" from top to bottom—it is not one set, but two sets running in parallel; it is not the more you stuff the better, but remembering what should be remembered accurately.

Let's review the core points strung together:

What you need to clarify	Conclusion
How many sets of memory	Two sets: CLAUDE.md where you handwrite rules + auto-memory where it writes insights itself
How to distinguish the two sets	Who wrote it, does it contain rules or insights, fully loaded or has an upper limit—one table clarifies it
Where auto-memory is stored	~/.claude/projects/<project>/memory/MEMORY.md, divided by git repository, local to the machine
How it is loaded	It only reads back the first 200 lines / 25KB of MEMORY.md at start, and parts exceeding are split into topic files to read on-demand
How to audit, edit, and delete	/memory: list loaded files, open the folder to read/edit/delete, toggle auto-memory
What to remember vs What not to remember	Pass three checkpoints: things that will change, things used only once, and sensitive things—don't remember any of them
Can # still be used	It's outdated; now say "remember xxx" for auto-memory, and say "add to CLAUDE.md" for git

You should now be able to: Distinguish what CLAUDE.md and auto-memory each manage, where they are stored, and how they are loaded respectively; let Claude remember an item and confirm which file it landed in; use /memory to clear out wrongly remembered or outdated notes; and judge whether a piece of information should really be remembered or not. To put it bluntly—you can make Claude "remember what should be remembered, and forget what should be forgotten," rather than letting it accumulate a brainful of useless things that will end up confusing you yourself.

Memory, in essence, is Claude "passively remembering facts"—you correct it, and it accumulates. But what it can do for you goes far beyond just remembering.

---

Next article 26 "Agent Skills"—memory is "passively remembering facts", whereas Skills are "actively encapsulating abilities": packaging a set of tasks you repeatedly ask it to do into a "specialized skill" it can pull out on demand. If memory makes it "understand you better," Skills make it "know how to do more." Let me leave you with a little thought: Both are "having Claude prepare in advance", when do you think you should use "remembering a rule" and when should you use "learning a skill"?

---

Recommended Reading

• API Configuration: Subscription login or API key, how to choose, how to switch
• Practical Getting Started: Take a real requirement, walk the whole journey from starting work to delivery
• CLAUDE.md Usage Guide: Write project rules into its memory