CLAUDE.md: Session Memory

The Problem You Will Hit Immediately

You start a Claude Code session. You explain your project, describe the conventions, mention the database schema. Claude does great work. You close the session.

Next time you open Claude Code, it remembers nothing. Zero. You re-explain everything. Every single time.

This is the problem CLAUDE.md solves.

The Glossary in Front of a Textbook

A CLAUDE.md file lives in the root of your project. It is a plain text file (nothing fancy) that Claude Code reads automatically at the start of every session. It contains everything Claude needs to know: what the app does, what framework it uses, what the conventions are, what commands to run, what to avoid.

Think of it like the glossary in the front of a textbook. It is always there. Always available. So you never have to start from scratch.

Without a CLAUDE.md, every session starts cold. Claude has to re-read your files, re-discover your patterns, re-learn your project. It burns time, burns tokens, and produces worse results because it is guessing at context you already explained yesterday.

With a CLAUDE.md, every session starts warm. Claude reads the file, understands your project, and gets to work immediately.

Creating One

Run /init inside Claude Code. That is it.

Claude scans your project (your file structure, your package.json, your existing patterns) and generates a starter CLAUDE.md. It is not perfect on the first pass. You will want to edit it, add details, remove things that are wrong. But it gets you 80% of the way there in seconds.

The file is plain text. You can open it in your editor and modify it like any other file. Add your team's conventions. Note which APIs you use. List the commands for running tests. Anything you would tell a new developer joining the project, put it in CLAUDE.md.

The Before-and-After

This is the exercise that makes the concept click:

Step 1: Open Claude Code in a project. Ask: "What is this project about?"

Watch what happens. Claude has to read files, scan the structure, make guesses. The answer is vague and generic. It might be wrong about key details.

Step 2: Run /init to generate a CLAUDE.md.

Step 3: Kill the session (Ctrl+C). Start a new one.

Step 4: Ask the exact same question: "What is this project about?"

The answer is immediate, specific, and accurate. Claude read the CLAUDE.md and already knows. No file scanning. No guessing. Night and day difference.

What Goes in a CLAUDE.md

The best CLAUDE.md files are concise. They are not documentation. They are context. Here is what works:

• What the project does (one or two sentences)
• Key commands (how to run, build, test, deploy)
• Conventions (naming patterns, folder structure, style preferences)
• What to avoid (known pitfalls, deprecated patterns, things that break)
• External dependencies (APIs, databases, services the project connects to)

You do not need to describe every file. Claude can read the files itself. The CLAUDE.md tells it what matters and how to think about the project so it does not waste time figuring that out from scratch.

It Persists. You Do Not Have To.

The key property of CLAUDE.md: it persists across sessions. Conversation history disappears when you close Claude Code. CLAUDE.md does not. It is a file on disk, like any other file. It survives restarts, reboots, and time.

This means you can evolve it. After a session where you corrected Claude about something ("no, we use Tailwind, not plain CSS"), add that to the CLAUDE.md. Next session, Claude will not make the same mistake.

Over time, your CLAUDE.md becomes a living document that encodes everything Claude needs to know about your project. The longer you use it, the better it gets.

Further Reading