Skip to main content

Project Memory with CLAUDE.md

Module: Memory & Context | Lesson: 2 of 4 | Time: ~10 minutes

What You Will Learn​

  • How CLAUDE.md provides persistent project memory
  • How to create and update CLAUDE.md
  • How nested CLAUDE.md files work in subdirectories
  • How to use .claude/rules/ for path-specific instructions
  • What belongs in CLAUDE.md and what does not

Prerequisites​

What Is CLAUDE.md?​

In the previous lesson, you learned that Claude forgets everything between sessions. CLAUDE.md is the solution. It is a special file that Claude Code reads automatically every time you start a new session in a project folder.

Think of it like a sticky note on your desk that says "Here is what you need to know about this project." Every morning when you sit down (every time you start Claude Code), that sticky note is right there waiting for you.

The file is named exactly CLAUDE.md (all uppercase, with the .md extension) and it lives in the root of your project folder.

Creating a CLAUDE.md File​

There are two ways to create one:

Method 1: Ask Claude to Create It​

The easiest way — just ask:

You: Create a CLAUDE.md file for this project. This is a personal website
     built with HTML, CSS, and JavaScript. The site uses a dark theme.
     Always use camelCase for JavaScript variable names.

Claude will create the file with your instructions formatted nicely.

Method 2: Ask Claude to Update the Existing One​

If Claude has already learned things about your project during the session, you can say:

You: Save what you've learned about this project to CLAUDE.md

Claude will write its accumulated knowledge to the file.

Method 3: Edit It Manually​

You can also open CLAUDE.md in any text editor (Notepad, VS Code, etc.) and type your instructions directly. It is just a regular text file.

What to Put in CLAUDE.md​

Here are the most useful things to include:

# Project: My Personal Website

## Tech Stack
- HTML5, CSS3, vanilla JavaScript
- No frameworks or build tools
- Hosted on GitHub Pages

## Code Style
- Use camelCase for JavaScript variables and functions
- Use 2-space indentation
- Add comments for any function longer than 10 lines

## Project Structure
- /index.html — homepage
- /css/ — stylesheets
- /js/ — JavaScript files
- /images/ — image assets

## Important Notes
- The site uses a dark theme — all new pages should match
- Navigation menu is in every page's header
- Do NOT modify the analytics script in the footer
Keep it focused

CLAUDE.md is loaded into the context window every session, so it uses tokens. Keep it concise and relevant — think bullet points, not essays. A good CLAUDE.md is typically 20-50 lines.

What NOT to Put in CLAUDE.md​

  • Entire code files — Claude can read those directly when needed.
  • Long tutorials or documentation — Link to them instead.
  • Temporary information — Things that change daily do not belong here.
  • Sensitive information — Never put passwords, API keys, or secrets in CLAUDE.md. If your project is on GitHub, this file will be visible to anyone with access.
Keep secrets out

CLAUDE.md is a regular file in your project. If you commit it to Git (which is common), anyone with access to the repository can read it. Never include passwords, API keys, tokens, or other sensitive data.

Updating CLAUDE.md​

Your project changes over time, and CLAUDE.md should change with it. You can update it at any time:

You: Update CLAUDE.md to note that we added a blog section using
     Markdown files in the /blog/ folder

Claude will edit the file to include the new information. You can also ask Claude to clean up or reorganize the file:

You: Clean up CLAUDE.md — remove anything outdated and reorganize it

Nested CLAUDE.md Files for Sub-Projects​

Large projects often have different sections that need different instructions. You can place additional CLAUDE.md files in subdirectories, and Claude will read the relevant one based on which files it is working with.

my-project/
  CLAUDE.md              <-- Project-wide instructions
  frontend/
    CLAUDE.md            <-- Frontend-specific instructions
    src/
      ...
  backend/
    CLAUDE.md            <-- Backend-specific instructions
    src/
      ...

When Claude works on files in the frontend/ directory, it reads both the root CLAUDE.md AND the frontend/CLAUDE.md. The nested file adds extra context without replacing the parent.

When to use nested files

You only need nested CLAUDE.md files if different parts of your project have genuinely different conventions, tech stacks, or rules. For small projects, one root CLAUDE.md is plenty.

Path-Specific Rules with .claude/rules/​

For even more targeted instructions, you can create rule files in the .claude/rules/ directory. These are small text files that apply to specific file paths or patterns.

For example, you could create .claude/rules/tests.md:

---
description: Rules for test files
globs: "**/*.test.js"
---

- Always use describe/it blocks
- Include at least one positive and one negative test case
- Use meaningful test descriptions

This rule only activates when Claude is working with files that match the **/*.test.js pattern.

How Claude Finds and Loads Memory​

When you start Claude Code in a project folder, here is what gets loaded, in order:

  1. User-level CLAUDE.md (~/.claude/CLAUDE.md) — Your global preferences (Lesson 3).
  2. Root CLAUDE.md — The one in your project's root folder.
  3. Nested CLAUDE.md files — Any in subdirectories Claude is working in.
  4. Rule files (.claude/rules/) — Path-specific rules that match current files.

All of these are combined and loaded into Claude's context window at the start of the session.

Try It Yourself​

Let us set up project memory for your practice project:

  1. Open Claude Code in your practice project folder.
  2. Ask Claude to create a CLAUDE.md: 
    Create a CLAUDE.md file for this project. Include:
    - The project name and what it does
    - The technologies used
    - Any code style preferences you'd recommend
  3. Review the file Claude creates. Ask it to adjust anything you want to change.
  4. Close Claude Code (type /exit).
  5. Reopen Claude Code in the same folder.
  6. Ask Claude: "What do you know about this project?" It should now remember the key facts from CLAUDE.md.
  7. Bonus: Ask Claude "What is in my CLAUDE.md?" to see exactly what it loaded.

What You Learned​

  • CLAUDE.md is a persistent memory file that Claude reads at the start of every session.
  • You can create it by asking Claude, or by editing the file manually.
  • Keep it concise and focused — bullet points, not essays.
  • Never put secrets (passwords, API keys) in CLAUDE.md.
  • Nested CLAUDE.md files add subdirectory-specific instructions.
  • .claude/rules/ provides path-specific rules that activate based on file patterns.
  • Claude loads all relevant memory files automatically at session start.
Help Us Improve

How was this lesson? Take 2 minutes to share your feedback — it helps us make the tutorials better for everyone.

Give Feedback →

Next Up​

Next: User Memory