Claude Code Memory & CLAUDE.md: How to Use Them

Each Claude Code session starts with a fresh context window, so anything you explained yesterday is gone today unless you write it down somewhere it can read. That’s what CLAUDE.md is for: a markdown file of persistent instructions Claude loads at the start of every session. Set it up well and you stop repeating yourself. Here is how it works and how to get one going.

What CLAUDE.md is and why it matters

CLAUDE.md is a plain markdown file you write to give Claude lasting context about a project, your personal workflow, or your whole organization. Claude reads it at the start of every session and treats it as guidance, alongside your conversation.

Add to it whenever you find yourself re-explaining something:

• Claude makes the same mistake a second time.
• A review catches something it should have known about this codebase.
• You type the same correction you typed last session.
• A new teammate would need the same context to be productive.

Keep it to facts that should hold in every session: build and test commands, conventions, project layout, and clear “always do X” rules. It is context, not a hard rule engine, so specific and concise instructions get followed more reliably than vague ones. Write “Use 2-space indentation” rather than “format code properly.”

The memory locations

CLAUDE.md files can live in several places, each with a different scope. They are loaded from broadest to most specific, so a project instruction lands in context after a personal one:

Scope	File location	Applies to
Managed policy	/Library/Application Support/ClaudeCode/CLAUDE.md (macOS), /etc/claude-code/CLAUDE.md (Linux/WSL), C:\Program Files\ClaudeCode\CLAUDE.md (Windows)	Every session on the machine, set by IT and not excludable
User	~/.claude/CLAUDE.md	All your projects, just for you
Project	./CLAUDE.md or ./.claude/CLAUDE.md	Your team, shared through source control
Local	./CLAUDE.local.md	This project only, kept private with .gitignore

Use the local file for project-specific notes such as your sandbox URLs or test data that should not be committed.

How the files load

Claude loads CLAUDE.md and CLAUDE.local.md from your current working directory and every directory above it, then concatenates them from the filesystem root down to where you launched. Instructions closer to your working directory are read last, and within a directory CLAUDE.local.md is appended after CLAUDE.md.

Files in subdirectories below you are not loaded at launch. They come in on demand, when Claude reads files in those directories. To confirm what actually loaded in a session, run /context and check the list under Memory files.

Pull in other files with @imports

A CLAUDE.md can import other files using @path/to/import syntax. The imported file is expanded into context at launch alongside the CLAUDE.md that references it. Both relative and absolute paths work, relative ones resolving from the file that contains the import, and imports can nest up to four levels deep.

See @README for the project overview and @package.json for available npm commands.

# Additional Instructions
- git workflow @docs/git-instructions.md

To mention a path without importing it, wrap it in backticks. If your repo already uses an AGENTS.md for other tools, a one-line @AGENTS.md import at the top of CLAUDE.md keeps both in sync without duplicating.

Set one up with /init and

The fastest way to start a project CLAUDE.md is to run /init in a session. Claude analyzes your codebase and writes a file with the build commands, test instructions and conventions it discovers. If a CLAUDE.md already exists, /init suggests improvements instead of overwriting it. Refine from there with the things Claude can’t infer on its own.

Two commands keep it current as you work:

• # shortcut: type # at the start of your input, then write the instruction. Claude Code asks which memory file to save it to and appends it there, so you can capture a rule the moment you spot it without leaving the session.
• /memory command: lists your CLAUDE.md, CLAUDE.local.md and other memory files across user and project scopes, and opens any of them in your editor. Selecting one that doesn’t exist yet creates it first.

You can also just ask Claude in plain language, like “add this to CLAUDE.md,” and it will edit the file for you.

Best practices

A few habits keep your memory files useful rather than noisy:

• Keep it short. Target under 200 lines per file. Longer files eat context and lower how reliably instructions are followed.
• Be specific. “Run npm test before committing” beats “test your changes.” Write instructions concrete enough to verify.
• Structure it. Use markdown headers and bullets to group related rules. Claude scans structure the way a reader does.
• Avoid contradictions. If two files disagree, Claude may pick one arbitrarily. Review your files periodically and drop stale or conflicting entries.
• Right tool for the job. CLAUDE.md is for facts every session needs. A multi-step procedure or something that only matters in one part of the codebase belongs in a skill or a path-scoped rule instead, so it loads only when relevant.

Remember that CLAUDE.md shapes behavior but does not enforce it. If something must happen at a fixed moment, such as before every commit, a hook is the reliable way to guarantee it.

Keep going

CLAUDE.md is one of the highest-leverage things you can set up in Claude Code. From here, start at the Claude Code hub, and if you haven’t installed it yet, follow how to install Claude Code. Then explore slash commands for quick actions and connecting MCP servers to extend what it can do. Newer to working with AI tools? Our AI course covers the fundamentals, and you can start with the free lessons too.