The memory problem in Claude Code
Here is the frustrating thing about working with Claude Code on a real project: every time you open a new session, Claude has no idea what you were building. Your stack, your naming conventions, your current progress, the thing you were halfway through last night - none of that exists in the new conversation. You start from scratch every single time.
On a one-hour project that does not matter. On a two-week build it becomes the biggest friction point. You spend the first ten minutes of every session re-explaining context, Claude makes decisions based on incomplete information, and you end up correcting things it would have gotten right if it had just known more about the project upfront. The memory bank is the solution to that problem.
What CLAUDE.md does
CLAUDE.md is a file you create in the root of your project directory. When you open Claude Code on that project, it reads this file before your first message. Everything in the file becomes context for the session - so if you wrote down that the project uses Next.js, the database is Supabase, and file names should be lowercase with hyphens, Claude knows all of that without you saying a word.
The effect is immediate and obvious. The first message in a session with a well-written CLAUDE.md feels like picking up with a collaborator who was with you yesterday. The first message in a session without one feels like briefing a contractor who just walked in. Both get the work done, but one costs you ten minutes of re-orientation every time.
Three things that belong in every CLAUDE.md
You do not need an elaborate CLAUDE.md to get most of the value. These three sections cover the majority of what makes re-orientation expensive, and you can write them in under ten minutes.
- Project description and stack. Two to four sentences: what the project does, who uses it, what framework it is built on, and what database or backend it connects to. This single block prevents dozens of wrong assumptions per session.
- Standing rules. The project-specific things Claude keeps getting wrong or that are important to get right: file naming conventions, which files are read-only, how errors should be handled, whether to write TypeScript strictly or loosely, which testing library to use. These are the rules you keep repeating - write them once here.
- Current state. A short note on what is built and what you are working on right now. Update this when the current task changes. It is the difference between 'we just finished the auth flow, now we are wiring up the dashboard' and having Claude re-ask where you are every single session.
The sub-memory pattern: splitting context across files
On larger projects, one CLAUDE.md can get unwieldy. There is a limit to how much context is useful in a single file before it becomes noise. The sub-memory pattern solves this: keep the main CLAUDE.md for always-relevant context, and create additional memory files in subdirectories for component-specific or module-specific rules.
For example: a main CLAUDE.md at the project root with the stack and global rules. A second CLAUDE.md inside the /api directory with notes specific to the API layer. A third inside /components with the component naming conventions and design system references. Claude reads the CLAUDE.md files relevant to the files it is working in, so the context stays focused on what matters for the current task.
- Root CLAUDE.md: project description, stack, global rules, current state.
- Directory CLAUDE.md files: rules specific to that part of the codebase - API conventions, component patterns, database schema notes.
- Keep each file short and specific. A 30-line CLAUDE.md that is always relevant beats a 300-line one that mixes context Claude does not need for the current task.
The live notebook: updating memory as the project grows
The memory bank is not set-and-forget. It is most useful when you treat it as a live document - updating the current state section as you finish tasks, adding rules when you find something Claude keeps getting wrong, removing stale notes that no longer apply. The fifteen seconds it takes to update the current state at the end of a session saves several minutes at the start of the next one.
A specific habit that pays off: when Claude makes a mistake and you correct it, ask yourself if that correction should go into CLAUDE.md as a standing rule. If Claude keeps confusing your auth middleware pattern, write the rule. If it keeps generating component names in PascalCase when you want kebab-case files, write the rule. The memory bank gets more valuable with every project rule you add to it.
Build longer, better projects inside Claude Code Club
We cover the full memory bank setup in the curriculum - including the exact CLAUDE.md templates I use for different project types, how to handle memory for subagent tasks, and the patterns that keep Claude accurate on long multi-week builds. Join us at [https://www.skool.com/claudecodeclub/about](https://www.skool.com/claudecodeclub/about) and bring your current project.
Short, practical drops on skills, MCP, agents, prompts, and more. No spam, unsubscribe anytime.
Frequently asked questions
How big can CLAUDE.md be before it stops working?
There is no hard technical cap, but practical experience shows that shorter, more focused CLAUDE.md files work better than long ones. Context you add has to be read and processed, and a 500-line CLAUDE.md full of outdated rules and notes is less useful than a 50-line one with current, relevant information. If your CLAUDE.md is getting long, apply the sub-memory pattern: move module-specific context into subdirectory CLAUDE.md files and keep the root one focused on the things that apply everywhere.
Does CLAUDE.md work in both the desktop app and the terminal?
Yes. CLAUDE.md is read by Claude Code regardless of whether you are using the desktop app or the CLI. Both read the file from the project root when a session starts on that project. The desktop app is the recommended starting point because it surfaces the project context in a way that is easier to see, but the memory bank works identically in both.
Can I have different CLAUDE.md files for different projects?
Yes - each project has its own CLAUDE.md in its own directory, and Claude reads whichever one corresponds to the project you are working in. Your projects do not share a single CLAUDE.md. This is actually one of the main advantages: each project's memory is completely independent, so a rule you add for one project never bleeds into another.
What is the difference between CLAUDE.md and the system prompt inside the app?
The system prompt in the Claude Code desktop app (the instructions you can add in project settings) and CLAUDE.md serve a similar purpose but at different scopes. The system prompt applies to that project in the app on your machine. CLAUDE.md lives in the project directory and gets committed to git, so it travels with the project and applies to anyone - or any machine - that opens the project in Claude Code. For solo builds they are equivalent. For team builds or anything that moves between machines, CLAUDE.md is the right choice because it goes where the code goes.
Last reviewed by David Iya on July 31, 2026


