What Is CLAUDE.md and Why Your AI Assistant Keeps Forgetting Everything

You open a new Claude session. You start typing. And almost immediately you realize you're re-explaining yourself — your stack, your tone preference, the thing you care about that Claude keeps getting wrong.

Again.

This isn't a Claude problem. It's a fundamental property of how large language models work. But there's a clean fix, and it lives in a single file.

What CLAUDE.md actually is

CLAUDE.md is a plain Markdown file that Claude Code reads automatically at the start of every session. It lives in your project root (or your home directory for global use), and its contents are injected into the system prompt before your first message.

That's it. One file. Read once per session. Shapes everything that follows.

When Claude Code starts, it:

1. Reads your global ~/.claude/CLAUDE.md (if it exists)
2. Walks the directory tree from your current folder upward
3. Loads every CLAUDE.md it finds at each level
4. Prepends all of that text to the system prompt
5. Starts the session with your first message — already briefed

No plugin. No configuration. No memory sync. Just a Markdown file in a directory.

Why AI assistants keep forgetting

The forgetting isn't a bug — it's how stateless architectures work.

Each Claude session starts with an empty context window. There's no persistent state across conversations, no database of your preferences, no journal of what worked last Tuesday. When you close a session and open a new one, the model has no memory of the previous one.

This is true of every major AI assistant. The session boundary is a hard reset.

For a lot of use cases this is fine. For people who work with Claude daily — engineers, consultants, writers, researchers — it means spending 5–10 minutes every session restoring context that should already be there.

CLAUDE.md is the hook point that changes this. Because Claude Code reads it at session start, before your first message, it becomes the one place you write things once and have them apply everywhere, forever.

What goes in a CLAUDE.md file

The most effective CLAUDE.md files tend to cover these areas:

• Role — who you are and what you're building or doing
• Working style — how you like to receive information (bullets vs. prose, brief vs. thorough)
• Domain context — the specific jargon, stack, or domain knowledge Claude should already have
• What to avoid — the failure modes you're tired of correcting (hedging language, over-caveating, invented APIs)
• Response format — how output should be structured for your most common tasks

You don't need all of these on day one. A paragraph that correctly sets your role and one "never do this" rule will already improve every session. Add to it over time as you notice patterns.

The length matters less than the specificity. A generic three-sentence CLAUDE.md ("I'm a developer, be concise, use code blocks") helps a little. A specific one that names your stack, your tone preference, and the particular mistakes you keep correcting helps a lot.

The real difference it makes

Here's what the same request looks like with and without a CLAUDE.md.

Without CLAUDE.md:

"Write a PR description for this change."

Claude returns a generic five-paragraph PR template. It doesn't know your team calls the database layer "the data tier," doesn't know your convention is to lead with the test plan, and doesn't know you prefer bullet points over prose.

You edit it heavily. You paste in context. You get something usable, eventually.

With a CLAUDE.md that names these things:

The same prompt returns a PR description that already matches your team's style, leads with the test plan, uses your terminology, and skips the caveating language you cut every time.

The first response is useful. Not the third.

That's the compounding benefit of a well-maintained CLAUDE.md. Every session starts calibrated. You spend less time steering and more time working.

FAQ

What is CLAUDE.md? CLAUDE.md is a plain Markdown file that Claude Code reads automatically at the start of every session. Its contents are injected into the system prompt before your first message, giving Claude persistent context about your role, working style, and preferences without any manual setup each session.

Why does Claude keep forgetting my preferences? Claude sessions are stateless — each new conversation starts with an empty context window. There's no cross-session memory by default. CLAUDE.md solves this by giving Claude Code a file to read at session start, so your context is restored automatically before you type your first message.

Where do I put my CLAUDE.md file? For project-specific instructions, put it in the root of your project directory. For instructions that apply everywhere, put it in ~/.claude/CLAUDE.md in your home directory. Claude Code loads both, with the project-level file taking precedence where they overlap.

How long should a CLAUDE.md be? Most effective CLAUDE.md files are 200–600 words — enough to cover role, working style, domain context, and a short "what to avoid" list. Longer is not always better; specificity matters more than length. A 150-word CLAUDE.md that names your exact stack and two concrete failure modes will outperform a 1,000-word generic template.