Chapter 3: CLAUDE.md — Your AI’s Long-Term Memory#
The Problem: Claude Forgets Everything#
Here is something that surprises every new Claude Code user: Claude has no memory between sessions.
When you close a Claude Code session and open a new one, Claude starts completely fresh. It does not remember what you worked on yesterday, what decisions you made, what files you edited, or what your preferences are. Every new session is a blank slate.
For quick, one-off tasks — download a video, convert a file, analyze a spreadsheet — this does not matter. But for ongoing projects that span days, weeks, or months, the lack of memory is a serious problem. You do not want to re-explain your project’s structure, your writing style, your data sources, and your preferences every time you start a new session.
CLAUDE.md solves this problem.
What CLAUDE.md Is and How It Works#
CLAUDE.md is a plain text file that Claude Code reads automatically at the start of every session. It is your project’s instruction manual for Claude — a persistent document that tells Claude everything it needs to know to be effective on your project.
When Claude Code launches, it looks for CLAUDE.md files in specific locations and loads them into its context. This means anything you write in your CLAUDE.md is included in every conversation from the start, as if you had typed it at the beginning of each session.
Think of CLAUDE.md as a briefing document. When a new team member joins a project, you give them a document that explains the project’s goals, conventions, current status, and key decisions. CLAUDE.md does the same thing, except the team member is an AI that needs this briefing every single time it sits down to work.
Project-Level vs. Global CLAUDE.md#
CLAUDE.md files work at two levels:
Project-level CLAUDE.md: Lives inside your project folder (at ./CLAUDE.md or ./.claude/CLAUDE.md). This file contains information specific to that project — its structure, its conventions, its current status. Every time you launch Claude Code from that project’s folder, this file is loaded automatically.
Global CLAUDE.md: Lives in your home directory. This file contains preferences and instructions that apply to all your projects — your writing style, your preferred output formats, tools you always want Claude to use, or behaviors you always want Claude to follow.
The project-level file is the one you will use most. Each significant project gets its own CLAUDE.md that evolves as the project progresses.
A Real Example: Building a Multi-Month Research Report#
Let me show you what a mature CLAUDE.md looks like in practice. I managed a multi-month survey research project — a large-scale report based on responses from over 180 professionals across multiple executive personas (CEOs, CTOs, CMOs, CPOs, and others). The project involved data cleaning, dashboard creation, report writing across multiple sections, and ongoing editorial decisions.
Here is what the CLAUDE.md memory system looked like by the end:
The CLAUDE.md file included:
- Project context: What the report was about, the total respondent count, the data format, and the target output
- Key decisions made: Which personas were included or removed (and why), how edge cases in the data were handled, how company size categories were mapped
- Persona breakdowns: Exact counts per respondent type, so Claude never had to recount
- Narrative arc: The overarching story the report was telling (excitement to investment to productivity to hiring impact)
- Writing progress: Which sections were drafted, which were approved, which still needed work
- Workflow rules: Specific instructions like “always present insights for approval before writing final copy” and “never write a section until the data analysis is complete”
- Corrected data points: Exact figures that had been verified and corrected during the project, so Claude would never hallucinate statistics
- Gotchas: Known issues with the data (certain question types that did not visualize well, budget questions that needed averaging, ambiguous response categories)
- Tone rules: The framing mandate — always positive, negative findings reframed as opportunities
This CLAUDE.md was over a hundred lines long. Every time I started a new session on the project, Claude loaded this entire context and was immediately up to speed. I never had to re-explain a decision, re-correct a data point, or re-establish a writing rule. The CLAUDE.md was the project’s institutional memory.
The memory directory supplemented the main CLAUDE.md with additional files:
session-context-detailed.md— A comprehensive log of everything that had been built, including column mappings in the data, file locations, and data transformation stepsceo-section-plan.md— The approved structure and data points for the CEO sectioncto-section-plan.md— The same for the CTO section
This multi-file memory system meant that Claude could instantly access deep context without the main CLAUDE.md becoming unwieldy.
The shortcut most people miss: You do not need to manually edit your CLAUDE.md or memory files to save information. During any conversation, you can simply tell Claude: “Remember that I prefer tables over bullet lists for data summaries” or “Remember that this project uses earth-tone colors.” Claude saves this to your memory/MEMORY.md file automatically, and it persists across sessions. This “just say remember” approach is the fastest way to build up your project’s institutional memory without ever opening a text editor. Over time, your memory file becomes a rich collection of preferences, decisions, and context — all captured in the natural flow of your work.
Writing Effective CLAUDE.md Files#
A good CLAUDE.md includes:
Project identity: What is this project? What are we making? Who is it for?
Example CLAUDE.md structure:
# Project: Annual Industry Research Report
- Survey-based report covering 180+ respondents across 5 executive personas
- Output: Website + PDF for public distribution
- Stakeholders: Research team (3 people), design partner
Key decisions and rules: What has been decided? What rules should Claude follow?
Example CLAUDE.md structure:
## Decisions
- Small persona groups (under 10 respondents) are excluded from dedicated sections
- All findings framed positively — challenges described as "opportunities"
- Each section reviewed and approved before writing final copy
## Writing Rules
- Use active voice throughout
- Every claim backed by a specific data point
- Keep paragraphs under 4 sentences
Current status: Where are we in the project? What is done, what is pending?
Example CLAUDE.md structure:
## Progress
- Data cleaning: COMPLETE
- Section 1 (Introduction): COMPLETE
- Section 2 (Highlights): COMPLETE
- Section 3 (CEO): FIRST DRAFT
- Section 4 (CTO): NOT STARTED
Technical context: File locations, data formats, known issues.
Example CLAUDE.md structure:
## Files
- Raw data: /data/survey-responses.csv (1,051 columns)
- Cleaned data: /data/cleaned/ (5 persona-specific CSVs)
- Report drafts: /report/ (numbered markdown files)
## Known Issues
- Matrix questions have 6 sub-columns per statement
- Budget question: each respondent distributed 100 points; use AVERAGE
What NOT to Include in CLAUDE.md#
- Do not include the full content of your files (Claude can read them when needed)
- Do not include session-specific instructions (those go in your prompt)
- Do not include information that changes every session (use it for stable context)
- Do not make it too long — keep it under 200 lines for the main file; use supplementary files in a memory directory for deep context
When to Update Your CLAUDE.md#
Update your CLAUDE.md when:
- A significant decision is made that affects future work
- You discover a data issue or gotcha that Claude should always know about
- A major milestone is completed (update the progress section)
- You establish a new rule or convention for the project
- Claude makes a mistake that you do not want repeated (add it to the gotchas)
A good rhythm: review and update your CLAUDE.md at the end of each working session, or whenever you feel Claude is forgetting something important.
Template: A Starter CLAUDE.md for a New Project#
Here is a template you can copy and modify for any new project:
Starter CLAUDE.md template:
# Project: [Name]
## Overview
[One paragraph: what this project is and what the output should be]
## Key Decisions
- [Decision 1]
- [Decision 2]
## Rules
- [Rule 1: e.g., "Always save outputs as RTF, not markdown"]
- [Rule 2: e.g., "Use formal tone throughout"]
## File Structure
- [Main files and where they live]
- [Data sources]
- [Output locations]
## Progress
- [ ] Phase 1: [description]
- [ ] Phase 2: [description]
## Known Issues / Gotchas
- [Anything Claude should be aware of]
Start simple. Your CLAUDE.md will grow naturally as the project evolves.
What Others Have Learned About CLAUDE.md#
The Claude Code community has developed strong opinions about CLAUDE.md through collective trial and error. Here are the most widely-shared insights:
Dynamic error correction is the killer feature. One of the highest-engagement tips is to update your CLAUDE.md immediately after Claude makes a mistake. The workflow: after an error occurs, prompt Claude with “Add a rule to CLAUDE.md to prevent this.” Claude appends something like “Always confirm before committing” or “Never reconstruct numbers from memory — always re-read source data.” Over time, your CLAUDE.md becomes a living record of every lesson learned, preventing the same mistakes from recurring. I discovered this independently during my survey report project, and it was a game-changer.
Keep it lean — under 5,000 tokens.. A CLAUDE.md that is too long can consume valuable context window space and actually degrade Claude’s performance on your tasks. The fix: keep instructions concise, use the /memory/ directory for supplementary files, and review your CLAUDE.md frequently to prune outdated entries.
Break it into sections by function. Structure CLAUDE.md into distinct sections: onboarding rules (how to start a session), common pitfalls (mistakes to avoid), and operational rules (like “If a task affects more than 3 files, break into subtasks”). This modular approach makes it easy for Claude to find the relevant rules for the current task.
Non-technical rules work just as well as technical ones. CLAUDE.md is not just for coding rules. Non-technical rules like “Format all research output as bullet points,” “Use formal academic tone,” or “Never use exclamation points” are equally effective. Think of CLAUDE.md as your style guide, operations manual, and decision log combined.
The contrarian view: auto-maintain it. Some experienced users argue that manually updating CLAUDE.md is unsustainable for long projects. They suggest using the claude-md-management plugin’s /claude-md-management:revise-claude-md command at the end of every session, letting Claude propose updates based on what happened. My approach: manual updates for important decisions, auto-updates for everything else.