Keeping Context with CLAUDE.md

The forgetting problem

You've learned how to manage conversations: when to clear, when to compact, how to resume sessions. But there's a gap none of those commands solve.

Every time you start a new conversation, Claude Code starts fresh. It doesn't remember that you prefer bullet points over numbered lists. It doesn't remember that your team calls the product "Relay" and not "the app." It doesn't remember that the sales data lives in the reports/ folder and the customer data lives in crm-exports/.

If you've used Claude Code for a few days, you've probably caught yourself typing the same background information over and over. "This is a marketing project for a B2B SaaS product..." "I'm an analyst on the growth team..." "The CSV files use semicolons as separators, not commas..."

That repetition is wasted effort. There's a better way.

What CLAUDE.md is

CLAUDE.md is a plain text file that lives in your project folder. Claude Code reads it automatically at the start of every conversation. You don't have to tell Claude Code to look at it. You don't have to paste anything. It loads on its own.

Think of it as a one-page briefing document. If you were handing off your project to a colleague who had never seen it, what would you put on a single sheet of paper? Whatever gets them up to speed fast, that's your CLAUDE.md.

Dan Shipper at Every.to describes the difference between the web-based Claude chat and Claude Code this way: the web app is like a hotel room. Clean, comfortable, but you start fresh every visit. Claude Code is more like your own apartment. Your files are there, your setup is there, your preferences persist. CLAUDE.md is what makes the apartment feel like yours. The labels on the drawers, the house rules on the fridge, the notes on the desk.

Creating your first CLAUDE.md

The fastest way to start is with the /init command. Type it during a Claude Code conversation:

/init

Claude Code scans your project folder, looks at what's in it, and creates a starter CLAUDE.md file.

The auto-generated version is a starting point, not a finished product. It tends to include more than you need. Read through it and cut anything that isn't useful. Deleting lines is easier than writing from scratch.

You can also create a CLAUDE.md by hand. It's a plain text file, nothing fancy. Create a file called CLAUDE.md in the root of your project folder (the folder where you start Claude Code) and write whatever you want Claude Code to remember.

Heads up: The filename matters. It must be CLAUDE.md exactly, with CLAUDE in uppercase and .md in lowercase. A file named claude.md or Claude.md won't be picked up.

What to put in it

For non-developer projects, your CLAUDE.md should cover four things: what this project is, what terminology to use, how you like to work, and what the folder structure looks like.

Here's an example for a marketing analyst's project:

# Marketing Analytics Project

## What this is
Quarterly campaign performance analysis for Relay (our B2B project management tool).
Data comes from HubSpot exports (CSV) and Google Analytics reports (CSV).
Reports go to the VP of Marketing.

## Terminology
- The product is called "Relay" — not "the app" or "the platform"
- "MQLs" = Marketing Qualified Leads
- "CAC" = Customer Acquisition Cost
- "Pipeline" refers to sales pipeline, not data pipeline

## Preferences
- Use bullet points, not numbered lists
- Reports should be professional but conversational (not academic)
- Always show dollar amounts with two decimal places
- When comparing time periods, show both the absolute numbers and the percentage change

## Folder structure
- /data — raw CSV exports from HubSpot and Google Analytics
- /reports — finished analysis and summaries
- /charts — generated visualizations
- /archive — old data from previous quarters

About 25 lines. Claude Code reads this at the start of every conversation and knows exactly what it's working with.

No more explaining what Relay is. No more reminding it about your formatting preferences. No more pointing it at the right folder.

What NOT to put in it

CLAUDE.md works best when it's short and focused. A useful test: if Claude Code should know something six months from now, put it in CLAUDE.md. If it changes week to week, keep it in your conversation prompts instead.

Leave out:

• Today's specific tasks ("analyze the January report")
• Temporary deadlines or sprint goals
• Passwords, API keys, or sensitive data
• Information that Claude Code can figure out by reading your files

That last point matters. You don't need to list every file in your project. Claude Code can see your files. You only need to explain things that aren't obvious from the files themselves, like what "MQL" stands for, or that reports go to the VP of Marketing.

Anthropic's own guidance is direct: for each line in your CLAUDE.md, ask yourself, "Would removing this cause Claude Code to make a mistake?" If the answer is no, cut it.

How long it should be

Short. Under a page of text. Most effective CLAUDE.md files run 20 to 100 lines.

This might seem counterintuitive. Wouldn't more instructions be better? No. Every instruction in your CLAUDE.md competes for Claude Code's attention. When the file gets long, important rules get buried. A tight 50-line CLAUDE.md where every line matters will outperform an 800-line version that tries to cover every scenario.

If your CLAUDE.md grows past 100 lines, prune it. Remove anything Claude Code already does correctly without being told. Remove anything that's obvious from your file and folder names. Keep only what Claude Code can't figure out on its own.

It survives everything

Remember the conversation management tools from the last page? CLAUDE.md works with all of them.

When you use /clear, the conversation resets but your CLAUDE.md reloads automatically. When you use /compact, your CLAUDE.md stays intact. When you start a new session tomorrow, your CLAUDE.md loads fresh. When you resume an old session with claude --continue, it's there too.

Conversations come and go. CLAUDE.md persists. That's the whole point.

Auto memory

Claude Code also remembers things on its own.

As you work, it can save notes to itself about your project: patterns it notices, preferences you express, things that worked or didn't. This is called auto memory.

You can also tell Claude Code to remember things directly:

Remember that the HubSpot exports use semicolons as separators, not commas.

Claude Code saves this note and loads it in future sessions.

Auto memory is separate from your CLAUDE.md. CLAUDE.md is the instructions you write for Claude Code. Auto memory is the notes Claude Code writes for itself. Both load at the start of each session.

You don't need to manage auto memory actively. It happens in the background. But if you want to see or edit what Claude Code has remembered, type:

/memory

This opens a list of all your memory files, including your CLAUDE.md, so you can review or change them.

Editing your CLAUDE.md over time

Your CLAUDE.md isn't a set-it-and-forget-it file. As your project evolves, update it.

Added a new data source? Add it to the folder structure section. Changed your reporting format? Update the preferences. Stopped working with one team and started working with another? Adjust the project description.

The /memory command is the easiest way to open and edit your CLAUDE.md during a session. You can also edit the file directly in any text editor, since it's a plain text file on your computer.

A good habit: every few weeks, skim your CLAUDE.md and ask whether it still reflects how you work. Remove anything that's no longer true. Add anything you've been repeating in every conversation.

What's next

You now have the full toolkit for communicating with Claude Code: giving good instructions, reviewing results, iterating, managing conversations, and keeping context across sessions with CLAUDE.md.

Next, we'll bring everything together with a summary of what you've learned in this module and a decision guide for when to use each technique. After that, an exercise to practice these skills with a real task.