How to Use CLAUDE.md for Persistent Memory and Context in Claude Code

If you keep repeating the same project rules every time you open Claude Code, CLAUDE.md is the fix. It gives Claude a shared memory file for commands, conventions, architecture notes, and working preferences.

This article keeps to the practical path: what CLAUDE.md is, where it lives, what to put in it, and how to keep it useful instead of bloated.

What CLAUDE.md Actually Does

CLAUDE.md is a Markdown file that Claude Code loads into context when a session starts. You can use it to store stable instructions such as:

• common build, test, and lint commands
• project architecture notes
• naming and style conventions
• workflow rules that Claude should follow every session

This is different from Claude's automatic memory. A simple rule of thumb:

• use CLAUDE.md for instructions you want to write down on purpose
• rely on automatic memory for things Claude learns while working with you

Where Claude Code Looks for Memory

According to Anthropic's documentation, Claude Code supports these memory locations:

Memory type	Location	Best for	Shared with
Enterprise policy	macOS: /Library/Application Support/ClaudeCode/CLAUDE.md Linux: /etc/claude-code/CLAUDE.md Windows: C:\ProgramData\ClaudeCode\CLAUDE.md	company-wide rules	everyone in the org
Project memory	./CLAUDE.md	project conventions and commands	your team
User memory	~/.claude/CLAUDE.md	your personal defaults across projects	just you
Project local memory	./CLAUDE.local.md	older project-specific personal notes	just you

Two details matter:

• Claude loads memory files automatically when it starts.
• CLAUDE.local.md is now considered deprecated in favor of imports, which work better across multiple Git worktrees.

Claude also looks upward from your current working directory. If you run Claude in a nested folder, it can pick up CLAUDE.md files higher in the repo. Nested CLAUDE.md files inside subdirectories are loaded when Claude reads files in those subtrees.

Fastest Way to Set It Up

The quickest path is to start with project memory.

Step 1: Start Claude Code in your repo

cd /path/to/your/project
claude

Step 2: Bootstrap a starter file

Inside Claude Code, run:

/init

Anthropic documents /init as the built-in way to create a starter CLAUDE.md for your codebase. It helps Claude discover common commands and project conventions instead of forcing you to start from a blank file.

Step 3: Clean up the generated file

Do not keep everything. Keep only information that is:

• stable
• useful across many sessions
• specific to this repo or your workflow

If a note only matters once, it does not belong in CLAUDE.md.

A Good Starter Template

For most repos, a short file like this is enough:

# Project Memory

## Commands

- Install dependencies: `npm install`
- Start dev server: `npm run dev`
- Run tests: `npm test`
- Run lint: `npm run lint`

## Code Style

- Use TypeScript for new files
- Prefer small focused functions
- Do not introduce new dependencies without a clear reason

## Architecture Notes

- API routes live in `src/app/api`
- Shared UI components live in `src/components`
- Domain logic should stay out of page components

## Workflow Rules

- Explain risky changes before making them
- Run relevant tests after edits
- Keep diffs small when possible

This works because it is short, concrete, and biased toward action.

Use Imports Instead of Stuffing One Huge File

CLAUDE.md can import other files with @path/to/file syntax. This is the cleanest way to keep the main file readable while still giving Claude access to useful context.

Example:

# Project Memory

See @README.md for project overview.
See @package.json for available scripts.

## Additional Instructions

- Follow the Git workflow in @docs/git-workflow.md
- Use the deployment notes in @docs/deploy.md
- Load my personal project notes from @~/.claude/my-project-notes.md

Useful details from the official docs:

• relative and absolute paths are supported
• imported files can recursively import other files
• import depth is capped at 5 hops
• imports are not evaluated inside code spans or fenced code blocks

This is why imports are now preferred over storing everything in CLAUDE.local.md.

Two Useful Shortcuts

Add a memory quickly with #

If you discover a rule during work, you can start your input with #:

# Always run `npm run lint` before opening a PR

Claude Code will prompt you to choose which memory file to save it into.

Edit memory directly with /memory

When you want to reorganize or expand your memory files, use:

/memory

That opens the memory file in your system editor so you can clean it up properly.

What Belongs in CLAUDE.md

Good candidates:

• commands Claude would otherwise have to rediscover
• repo-specific directory conventions
• test and verification expectations
• naming rules your team cares about
• non-obvious architecture constraints

Bad candidates:

• temporary bug notes
• one-off task instructions
• personal brainstorming
• long prose that says little
• duplicated content that already lives clearly elsewhere

If you can replace three paragraphs with one bullet, do it.

Common Mistakes

1. Writing vague rules

Bad:

• "Format code properly"

Better:

• "Use 2-space indentation"
• "Run npm test after backend changes"

Specific instructions are easier for Claude to follow.

2. Turning CLAUDE.md into a dumping ground

If the file gets huge, Claude has to read more low-signal context every session. Move detailed docs into imported files and keep the root memory file focused.

3. Keeping outdated instructions

If your build command changed three months ago and CLAUDE.md still says otherwise, you are feeding Claude stale context. Review this file whenever your workflow changes.

4. Using project memory for personal-only notes

If a note is only for you, keep it in ~/.claude/CLAUDE.md or import a personal file from your home directory instead of committing it to the repo.

A Simple Maintenance Routine

Use this once a week or whenever the repo changes significantly:

1. Open CLAUDE.md.
2. Delete anything temporary.
3. Check whether commands still work.
4. Move bulky detail into imported files.
5. Keep the top-level file easy to scan in under a minute.

That is enough for most teams.

Quick Checklist

• Run /init in the project root
• Keep the file short and specific
• Store commands, conventions, and architecture notes
• Use imports for larger supporting docs
• Use # for quick additions
• Use /memory to edit and reorganize
• Review the file when your workflow changes

Official References

• Manage Claude's memory
• Slash commands
• Claude Code tutorials