What Is CLAUDE.md? The File That Stops Claude Forgetting
What is a CLAUDE.md file? A plain text note Claude Code reads at the start of every session — so your rules and preferences finally survive between chats.
Evgenii Arsentev · PhDReviewed for accuracy by Evgenii Arsentev, PhD · 2026-06-12
Here's a frustration everyone hits a few weeks into building with Claude Code: every session starts fresh. You told it yesterday to keep your data in one file, to answer in your language, to never touch the photos folder — and today you're typing it all again. If you took my course, you know why: the AI's working desk is wiped between conversations. What the course didn't cover is the fix — and it's embarrassingly simple.
What is a CLAUDE.md file for?
In your project folder there can live a file called CLAUDE.md. It's not code — it's a plain text note. Claude Code reads it at the start of EVERY session, automatically, before you say a word. Whatever rules you write there, Claude starts the day already knowing. That's the entire mechanism: a note on the fridge, except the fridge is your project and the reader never skips it.
Do I actually need a CLAUDE.md?
If you only ever ask Claude one-off questions, no. The moment you notice you're typing the same instruction a second time — that's the signal you need one. The file pays for itself the first morning you open the project and Claude already knows your language, your data file and your no-go folders without a single reminder.
What belongs in a CLAUDE.md file?
What belongs in it (the test: 'I keep re-explaining this')
- 1Rules you repeat: 'always answer in Russian', 'keep all data in data.json', 'dark theme everywhere'.
- 2How to run your tool: 'open index.html to test' — so Claude checks its own work the right way.
- 3Boundaries: 'never touch the photos folder', 'don't change the design unless I ask'.
- 4Anything you've corrected twice. Twice means it belongs in the file.
How do I make a CLAUDE.md file?
Creating it requires zero ceremony. You don't even have to write it yourself — just tell Claude: 'add this to CLAUDE.md: always keep my data in data.json'. It creates the file and writes the rule. There's also a command that builds a starter file for you: type /init in a session, and Claude studies your project and writes one.
How does CLAUDE.md work with auto memory?
Recent versions of Claude Code added auto memory — and it's on by default. As you work, Claude quietly saves notes for itself: how your project runs, mistakes it shouldn't repeat, preferences you've corrected. You'll occasionally see 'Writing memory' flash by — that's it learning. The division of labor: CLAUDE.md holds YOUR rules, auto memory holds what Claude figured out on its own. Both load at the start of every session.
How do I see what Claude remembered?
Want to see what it remembered? Type /memory in a session — it lists every note file and lets you open, edit or delete any of them. It's all plain text. If Claude memorized something wrong, delete the line; if there's a rule you want it to keep forever, say 'remember this' and it lands in its notes.
Where does CLAUDE.md reside?
Two places, and the difference is the whole trick. The project file lives in the project folder and applies only to that project. A second, personal one lives at ~/.claude/CLAUDE.md and applies to EVERYTHING you build on this computer. You almost never go hunting for either path by hand — you tell Claude which one you mean and it edits the right file.
A CLAUDE.md in the project folder applies to that project. But there's also a personal one — at ~/.claude/CLAUDE.md — that applies to EVERYTHING you build on this computer. Put your language and your general taste there once ('answer in Russian; explain like I'm not a programmer'), and every future project starts pre-trained. Ask Claude: 'add to my personal CLAUDE.md: …' — it knows where it lives.
How long is too long for a CLAUDE.md?
First: keep the file short — under ~200 lines. A bloated note gets followed worse, not better (just like with people). Second: these are instructions, not iron laws — Claude follows specific rules ('store data in data.json') far more reliably than vague ones ('do everything nicely'). If a rule seems ignored, type /memory and check your file is actually listed there.
Five minutes, permanent upgrade
0/5This is the cheapest upgrade in all of vibe-coding: one plain text file, written once, and the assistant that used to forget you every morning starts feeling like a colleague who's been on the project for months.
Free course
Stop reading about AI — start building with it
The free Claude Code course: your first site, tool or game — no coding. No upsells, no cross-sells — nothing to buy here.
Start free →References
Selected peer-reviewed papers and preprints on the AI research behind this topic.
- [1]Wang et al. (2023). Augmenting Language Models with Long-Term Memory. arXiv:2306.07174
- [2]Zhong et al. (2023). MemoryBank: Enhancing Large Language Models with Long-Term Memory. arXiv:2305.10250
- [3]Gutiérrez et al. (2024). HippoRAG: Neurobiologically Inspired Long-Term Memory for Large Language Models. arXiv:2405.14831
- [4]Wan et al. (2025). StoryBench: A Dynamic Benchmark for Evaluating Long-Term Memory with Multi Turns. arXiv:2506.13356
- [5]Shen et al. (2025). TALM: Dynamic Tree-Structured Multi-Agent Framework with Long-Term Memory for Scalable Code Generation. arXiv:2510.23010
- [6]Jonelagadda et al. (2025). Mnemosyne: An Unsupervised, Human-Inspired Long-Term Memory Architecture for Edge-Based LLMs. arXiv:2510.08601
- [7]Shen et al. (2026). Mem2ActBench: A Benchmark for Evaluating Long-Term Memory Utilization in Task-Oriented Autonomous Agents. arXiv:2601.19935
Author
Evgenii Arsentev
PhD · Chief Executive Officer, digital health
Reading is a good start
Want to actually build this?
Guides explain. The free course transforms — personalized, gamified, and built to get you shipping fast.
Start the free course →