Skills / Guides

The two kinds of memory

Both are context, not settings Claude is forced to obey. Specific, short instructions get followed most reliably. To block an action no matter what Claude decides, use a hook instead.

Where CLAUDE.md files go

The organization file lives at /Library/Application Support/ClaudeCode/CLAUDE.md on macOS, /etc/claude-code/CLAUDE.md on Linux and WSL, and C:\Program Files\ClaudeCode\CLAUDE.md on Windows.

Claude Code reads the CLAUDE.md files in the folder you start it in and in every folder above it. They are joined together, not overridden, from the top folder down, so the file closest to where you started is read last. CLAUDE.md files in subfolders load later, the first time Claude opens a file in that subfolder.

Set up a project CLAUDE.md

Run /init in your project. Claude reads the codebase and writes a starting CLAUDE.md with the build commands, test commands and conventions it finds; if the file already exists, it suggests improvements instead of overwriting it. Then add what Claude could not work out by itself. A short file might look like this:

# Project notes

- Run `npm test` before committing.
- API handlers live in src/api/handlers/.
- Use 2-space indentation.
- Never edit files in generated/; run `npm run codegen` instead.

• Write things Claude can check. “Run npm test before committing” works; “test your changes” does not.
• Keep each file under about 200 lines. Longer files cost more context and get followed less.
• Add a line when you repeat yourself: when Claude makes the same mistake twice, or you type the same correction you typed last session.
• Keep procedures out. A multi-step workflow that you need now and then belongs in a skill, which loads only when needed.

Import files and split rules

A CLAUDE.md can pull in other files with @path. Imported files load at launch too, so this tidies a long file without saving any context.

See @README for an overview and @package.json for npm commands.

- Git workflow: @docs/git-instructions.md

For bigger projects, put one topic per file in .claude/rules/. A rule with a paths list loads only when Claude works on matching files, which keeps the rest of the session lighter:

---
paths:
  - "src/api/**/*.ts"
---

- Every endpoint validates its input.
- Use the standard error response format.

Rules in ~/.claude/rules/ apply to all your projects.

Auto memory

Auto memory is on by default in local sessions. As Claude works, it saves notes of four kinds: who you are and how you like to work (user), corrections and approaches you confirmed (feedback), ongoing work and decisions (project), and where to find outside information such as an issue tracker (reference). It skips anything it can read from the code or that your CLAUDE.md already says, and it does not save something every session.

~/.claude/projects/<project>/memory/
├── MEMORY.md            index, one line per note, loaded every session
├── user_role.md         one note
├── feedback_testing.md  one note
└── ...

Only the first 200 lines or 25 KB of MEMORY.md load at the start of a session; Claude opens the topic files when it needs them. The folder belongs to the git repository, so every worktree and subfolder of that repository shares it. It stays on your machine and is not deleted when old session transcripts are cleaned up.

To switch it off for one project, add this to the project's settings file:

{
  "autoMemoryEnabled": false
}

To store it somewhere else, set autoMemoryDirectory to an absolute path or one starting with ~/. To turn it off everywhere, set CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

The /memory command and “remember this”

/memory lists every CLAUDE.md and memory location for your session, opens any of them in your editor (creating the file if it does not exist yet), toggles auto memory, and opens the auto memory folder so you can read, edit or delete what Claude saved.

Ask Claude to remember something and it goes to auto memory: “always use pnpm, not npm”. Say “add this to CLAUDE.md” when the rule should be shared with your team. To see which files actually loaded, run /context and look under Memory files.

AGENTS.md and other coding agents

Recent versions of Claude Code read a repository's AGENTS.md when there is no CLAUDE.md in the folder or above it. If your project has both, Claude reads only CLAUDE.md unless you change the Project instructions option in /config. To keep one shared file for every tool, put @AGENTS.md at the top of your CLAUDE.md and add Claude-only notes below it. Codex reads AGENTS.md too; see the Codex skills guide.

When Claude forgets or ignores memory

• Run /context. If the file is not listed under Memory files, Claude cannot see it. Subfolder files only appear once they load.
• Make the instruction specific, and look for two files that say different things; Claude may follow either one.
• If something must happen every time, such as a check before each commit, write a hook. Hooks run whatever Claude decides.
• After /compact, the project-root CLAUDE.md is read again from disk. Anything you only said in the chat is gone, so put lasting rules in the file.
• Run /doctor prompt-audit to have Claude look for outdated or conflicting instructions. It proposes edits and changes nothing until you agree.

When the built-in memory is not enough

Built-in memory keeps rules and short notes, not a searchable history of what you did. If you want to ask “what did we change in the billing module last week?”, a memory plugin such as claude-mem records each session, stores summaries locally and brings the relevant ones back later. It runs a background worker and asks you to sign in for an optional hosted service, so read its page before installing.

Based on Anthropic's Claude Code documentation, “How Claude remembers your project”, checked on 2026-10-17. Details such as limits and settings names change between releases, so check the docs if something behaves differently. Also see What are Claude skills?