What is CLAUDE.md? (your agent's memory file)

What it actually is

CLAUDE.md is a plain markdown file that lives in your project, usually at the root as CLAUDE.md, or inside .claude/CLAUDE.md. Claude Code reads it automatically at the start of every session. There’s no required format or schema to learn: it’s a text file you write in plain language, describing things your agent should already know before it starts touching your code.

Think of it like the notebook a substitute teacher finds on the desk. Every session, Claude Code shows up with a completely fresh memory: it does not remember yesterday’s conversation, your preferences, or the correction you gave it three sessions ago. The notebook on the desk is what tells the substitute which student needs patience, where the supplies live, and when the fire drill happens. Skip the notebook, and the substitute has to relearn all of it from scratch, or guesses wrong.

Why your AI just did this

If Claude just created or updated a CLAUDE.md on its own, it’s usually one of two things. Either you ran /init, which tells Claude to scan your whole codebase (file structure, build scripts, test commands) and draft a starting CLAUDE.md from what it finds, or Claude decided a correction you just gave it was worth writing down for future sessions.

The second case is the one worth paying attention to. In early 2026, Andrej Karpathy posted about the specific ways Claude Code kept tripping him up: making silent assumptions instead of asking, overcomplicating simple changes, and editing files that had nothing to do with the task. A developer turned that post into a short, four-rule CLAUDE.md, things like telling Claude to surface confusion instead of guessing silently and to avoid touching files outside the task, and it spread fast enough to become one of the most-starred single files on GitHub. That story is a big part of why CLAUDE.md caught on so fast: it turns “I keep having to tell it the same thing” into something you write once and stop repeating.

When you’ll run into it

• Claude makes the same mistake two sessions in a row, because the correction only ever lived in chat and nothing got written to CLAUDE.md.
• You run /init in a project that already has a CLAUDE.md, and Claude offers to suggest improvements instead of overwriting it.
• A brand-new session ignores a convention you set up days ago; that’s expected, since only CLAUDE.md, not your old chat history, carries forward automatically.
• Your CLAUDE.md grows past roughly 200 lines and instructions near the bottom seem to get followed less reliably.
• You spot both a CLAUDE.md and a .claude/CLAUDE.md in the same project giving different instructions: both load together instead of one replacing the other, so the contradiction itself is what makes Claude’s behavior inconsistent.

What to check

• Confirm it actually loaded: run /context in the session and look under “Memory files”
• Keep it short and specific: aim under 200 lines, and swap vague lines like “format code nicely” for concrete ones like “use 2-space indentation”
• Put team-shared rules in the committed CLAUDE.md, and personal-only notes (local URLs, your own test data) in a gitignored CLAUDE.local.md
• If instructions aren’t sticking, look for contradictions: another CLAUDE.md elsewhere in the directory tree, or a nested one in a subfolder, can quietly conflict with it
• Run /memory to browse and edit every memory file Claude Code currently knows about, in one place

Say it like a dev

Instead of: “just remember this for next time” Say: “add this to CLAUDE.md so it loads every session”

Instead of: “why does it keep forgetting what I told it” Say: “was that ever written to CLAUDE.md, or only said in chat”

Instead of: “make a rules file for the project” Say: “let’s start a CLAUDE.md at the project root”