Where do CLAUDE.md and MEMORY.md live?

Per the Claude Code docs: your personal file for every project is ~/.claude/CLAUDE.md; a project file shared with your team is ./CLAUDE.md or ./.claude/CLAUDE.md at the project root; personal notes for one project go in ./CLAUDE.local.md, added to .gitignore. Auto memory, which Claude writes itself, lives in ~/.claude/projects/ /memory/, with MEMORY.md as the index. Run /memory inside Claude Code to list and open these files.

What is the difference between CLAUDE.md and auto memory?

From the official docs: CLAUDE.md is the instruction file you write, holding rules and workflows. Auto memory is the learning notes Claude writes for itself. CLAUDE.md loads in full every session, while the auto memory index (MEMORY.md) loads its first 200 lines or 25KB each session. The two systems complement each other, and neither replaces the other.

How long is too long for a CLAUDE.md?

Anthropic's own wording: “Size: target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence.” Aim for under 200 lines per file. Going over costs more tokens, and it also lowers how closely the model follows your instructions.

Which saves more tokens, .claude/rules/ or skills?

Skills cost less. The official explanation: rules are “loaded at the start of every session, or when a matching file is opened”, while skills are “loaded on demand, they enter context only when you invoke one or when Claude judges it relevant”. Put always-on instructions in rules, and put workflows you need once in a while in skills.

Do HTML comments really cost no tokens?

Yes, but only in CLAUDE.md files. The official wording: “Block-level HTML comments ( ) in CLAUDE.md files are stripped before the content is injected into Claude's context.” They are stripped before injection, so you can use them for human maintainer notes without spending context. Comments inside code blocks are kept, though, and Claude still sees them when it opens the file with the Read tool.

新版舊版

Claude Code memory: full guide + copy-paste prompts

4 ways to write CLAUDE.md and cut tokens, plus 5 prompts you paste into Claude Code

黃志弘 Leo

Published 2026-04-17 · Updated 2026-10-09 · 1 readers

5 prompts to paste into Claude Code

Copy the 5 prompts below into Claude Code. It reads your CLAUDE.md, tells you what to change, and waits for your OK before touching anything. The article then explains why each one saves tokens and how it works.

★One-shot full checkup (start here)

Open Claude Code in your project root and paste the whole block below. It runs every check from all 4 methods, and lists each change before making it, waiting for your OK.

Run a checkup on this project's CLAUDE.md. The goal is to cut context token use. Do it in this order:
1. Run `wc -l CLAUDE.md` and tell me the current line count
2. Scan for comments starting with # that are written for people (history, reasons, context)
   (not the rules themselves, the ones explaining why a rule exists)
   List them, then rewrite them as <!-- --> block comments
3. Find rules that only apply to one kind of file
   (for example only to API code, front-end components, SQL migrations)
   Split them into separate .claude/rules/xxx.md files, add a paths field in the YAML frontmatter bound to a glob
   Delete the moved parts from the main CLAUDE.md
4. Check for long sections (git workflow, style guides) that belong in an external file pulled in with @path
5. After all the edits, run `wc -l CLAUDE.md` again and tell me the difference
List the plan before each step and wait for my OK. Follow the rules in https://code.claude.com/docs/en/memory.

What you get: A change plan plus a before and after line count. Claude works step by step, no sweeping edits.
How long: Depends on how big your CLAUDE.md is, usually 10 - 30 minutes in one pass.

1Hide the history comments (5 minutes, the fastest win)

Scan my CLAUDE.md and rewrite every human-facing comment that starts with # (history, who decided what, why a rule exists, context written for people, not the rules themselves) as a <!-- --> block comment.
List the sections you found before changing anything and wait for my OK. When you are done, run `git diff CLAUDE.md` so I can check.

2Load rules only when the matching files are touched (saves the most)

Some rules in my CLAUDE.md only apply to certain kinds of files (only to src/api/, only to React components, only to SQL migrations).
Split those rules into separate files under .claude/rules/, each with YAML frontmatter:
---
paths:
  - "the matching glob"
---
Delete the moved rules from the main CLAUDE.md. Give me the split plan first (which group becomes which file, what paths says) and wait for my OK.
Rule format: https://code.claude.com/docs/en/memory

3Trim CLAUDE.md once it passes 200 lines

Run `wc -l CLAUDE.md`. If it is over 200 lines, analyse it for me:
1. List the line count of every major section
2. Find the sections best moved out:
   - History and context, wrap in HTML comments <!-- -->
   - Tied to one kind of file, move to .claude/rules/
   - Long examples / full workflows, move to docs/ and pull back with @path
3. Estimate how many lines are left after the cuts
Give me the list of suggestions first, I will pick which ones to do.

4Move long cross-project sections out (@import)

Find the content in my CLAUDE.md that is long and applies across projects (git workflow, personal code style preferences, commit conventions).
Move it to external files and pull it into the main file with @path:
- Cross-project personal preferences: move to ~/.claude/xxx.md, use @~/.claude/xxx.md
- Project-level detail: move to docs/xxx.md, use @docs/xxx.md
List the sections you want to move and the target filenames first, then wait for my OK.

Heads-up: Claude Code follows the rules already in your CLAUDE.md, so if you have a rule like “ask me before editing a file”, it will ask. If you do not, watch the first run and confirm you agree with everything it touches.

Why CLAUDE.md affects your token use

There are two layers. At the model layer, Claude Code lets you set effort (five levels: low, medium, high, xhigh, max) or simply ask for shorter answers.

The other layer is context, meaning your CLAUDE.md. It loads in full at the start of every session, so the longer it is, the more tokens you spend before the conversation begins. That holds whichever model you use, so the 4 methods below apply to any version of Claude.

Long-lived CLAUDE.md files tend to keep instructions written for older models. In Claude Code 2.1.283 or later, run /doctor prompt-audit in a session. It flags instructions written for older models, references to files or commands that no longer exist, and rules that contradict each other, then proposes edits and changes nothing until you say so.

4 ways to write CLAUDE.md (each with before / after and why it saves)

Every rule here comes from Anthropic's official Claude Code memory docs, code.claude.com/docs/en/memory. The examples are copy-paste ready for your own CLAUDE.md.

1Wrap context written for people in  block comments

Why it saves: Block-level HTML comments are stripped before the content is injected into Claude's context. The notes you write for your future self or a teammate, why this rule exists, ask before deleting it, cost nothing in tokens.

“Block-level HTML comments () in CLAUDE.md files are stripped before the content is injected into Claude's context.” Source: code.claude.com/docs/en/memory

Before (bad), those two history notes load every single time

# Rules
# 2025-08-15: added because Sarah kept getting her PRs rejected
# Do not delete, checked with the Compliance team
- Always include type annotations on exported functions
# Mike thinks we may drop this one later
- Prefer `import type` over `import { type }`

After (good), both notes are stripped and Claude sees only the rules

# Rules
<!--
2025-08-15: added because Sarah kept getting her PRs rejected
Do not delete, checked with the Compliance team
-->
- Always include type annotations on exported functions
<!-- Mike thinks we may drop this one later -->
- Prefer `import type` over `import { type }`

Do it now: Run grep -n "^#" CLAUDE.md to find the human comments that start with # in your file today, and wrap them in .
Note: Comments inside ``` code blocks are kept. Open the file with the /memory command and you still see them. The content written for people is not gone, it just does not enter Claude's context.

2Use .claude/rules/ + paths for conditional loading (this one saves the most)

Why it saves: Put them in .claude/rules/*.md and add the YAML frontmatter paths field. The rules only load into context when Claude touches a file matching the glob. Front-end work does not load the API rules, API work does not load the front-end rules. Session start = 0 tokens.

Before (bad), everything in the main CLAUDE.md, loaded every session

# CLAUDE.md (main file)
## API rules (50 lines)
- All endpoints must validate input with zod
- Use standard error response from src/api/errors.ts
- ... 47 more lines
## React rules (50 lines)
- Functional components only, no class components
- Tailwind only, no CSS modules
- ... 47 more lines
## DB rules (50 lines)
- Migrations must be reversible
- ... 48 more lines

150 lines ≈ 1500 tokens, paid every session. Write front-end code and the back-end rules load anyway.

After (good), three files, loaded conditionally

# .claude/rules/api.md
---
paths:
  - "src/api/**/*.ts"
---
- All endpoints must validate input with zod
- Use standard error response from src/api/errors.ts

# .claude/rules/react.md
---
paths:
  - "src/components/**/*.tsx"
  - "src/pages/**/*.tsx"
---
- Functional components only, no class components
- Tailwind only, no CSS modules

# .claude/rules/db.md
---
paths:
  - "migrations/**/*.sql"
  - "src/db/**/*.ts"
---
- Migrations must be reversible

How much you save: session start drops from 1500 tokens to 0. Editing the API pulls in only those 50 lines, the other two groups never load.
Do it now: Go through your CLAUDE.md and find the rules tied to one kind of file (API only, React only, SQL only, tests only). Put each group in its own file under .claude/rules/, write the matching glob in paths, then cut them from the main file.

3Keep every CLAUDE.md under 200 lines

Why it saves: CLAUDE.md loads into context in full at every session start. 600 lines ≈ 6,000 tokens, 200 lines ≈ 2,000 tokens, a gap of 4,000 tokens per session. Open 10 sessions a day and the gap is 40,000 tokens.
The docs also say that past 200 lines Claude follows the rules less closely.

“Size: target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence.” Source: code.claude.com/docs/en/memory

Typical reasons a file passes 200 lines (trim these first)

“Why this project exists / how we did it back in v1” history, wrap it with method 1 in 
“Onboarding steps for new teammates”, move to docs/onboarding.md
“Rules tied to one kind of file”, split out with method 2 into .claude/rules/
Long examples / full git workflow / DB schema notes, move to docs/ then pull them back in with @import from method 4

Do it now:

wc -l CLAUDE.md         # how long it is now
grep -c "^#" CLAUDE.md  # how many human comments start with #

Over 200 lines, trim along the 4 directions above, then run wc -l to confirm.

4Use @path to split files (pairs with the structure from methods 2 and 3)

Honestly: @import pulls the content inline into context, so @import on its own does not cut tokens. Its value is a readable main file, sharing across projects, and moving long sections into sub-files (which you can later move into .claude/rules/ for conditional loading, which is where the real saving is).

Typical usage

# Project Rules
- 2-space indent
- Run `npm test` before commit
- API handlers in src/api/handlers/
@~/.claude/my-personal-style.md   # shared across projects
@docs/git-workflow.md             # detail moved out

The docs say @path recurses at most 4 levels (A imports B, B imports C, up to 4 hops).

When to use it:

Personal preferences shared across projects (home path @~/...)
Modular structure in the main file, easy to move out later to .claude/rules/

When not to use it: Importing rules only to keep the main file tidy, token use does not change. To actually save tokens, use method 2 and split into .claude/rules/.

The 4 methods ranked by token saving:
Method 2 (.claude/rules/ + paths) > Method 3 (200 lines) > Method 1 (HTML comments) > Method 4 (@import does not save directly)
Want a result today: do method 1 first (easiest, 5 minutes), then method 2 (biggest saving, 30 minutes).

Going further: Skills save more than Rules

Anthropic has a third layer: Skills. Used in the right place it saves more than rules.

Mechanism	When it loads into context	Best for
CLAUDE.md	Every session start (loaded in full)	Rules Claude needs every day
`.claude/rules/` + paths	When Claude reads a file matching the glob	Rules tied to a specific kind of file
Skills	When you invoke it, or Claude decides it is relevant	Workflows you only need occasionally (complex tasks)

“Rules load into context every session or when matching files are opened. For task-specific instructions that don't need to be in context all the time, use skills instead, which only load when you invoke them or when Claude determines they're relevant to your prompt.” Source: Anthropic Claude Code documentation

Rule of thumb: always-on goes in CLAUDE.md, conditional goes in rules, on-demand goes in skills. Putting each at the right level is the saving.

Side by side: a bad CLAUDE.md vs a good one

The comparison below is illustrative. It shows you the structural difference, it is not measured token data.

The bad version

One file, 600+ lines
Long “Why this exists” sections written for people
Every rule always resident (front-end rules load while you edit the back end)
No import splitting
Unverifiable instructions like “format code nicely”

6,000+ tokens burned at the top of context every session.

The good version

Main file under 80 lines, only the rules needed daily
History and context in  comments, never in context
Front-end and back-end rules split into .claude/rules/*.md + paths
Use @docs/git-workflow.md to pull in external detail
Concrete and checkable, like “Use 2-space indentation”

About 800 tokens at session start, and better adherence.

One clarification: CLAUDE.md ≠ auto memory

People searching for “Claude memory” mix these two up. The docs actually have a clear comparison table (excerpt):

	CLAUDE.md	Auto memory (built into recent Claude Code versions)
Who writes it	You	Claude itself
Content	Rules and workflows	Preferences Claude picked up, debugging experience
Loading	Loaded in full every session	Loads the first 200 lines or 25KB of the MEMORY.md index each session
Best for	Code style, architecture, process	Build commands, debugging notes, preferences Claude learned itself

They complement each other, neither replaces the other. Full comparison table in the docs

Where CLAUDE.md and MEMORY.md live

From the official docs (October 2026). When several of these exist, none overrides another: Claude reads all of them, and the ones closer to your working folder are read last.

Personal CLAUDE.md: ~/.claude/CLAUDE.md. Just you, applied to every project
Project CLAUDE.md: CLAUDE.md or .claude/CLAUDE.md at the project root. Shared with the team through version control
CLAUDE.local.md: CLAUDE.local.md at the project root. Just you, so add it to .gitignore
Company-wide CLAUDE.md: on Mac at /Library/Application Support/ClaudeCode/CLAUDE.md, on Windows at C:\Program Files\ClaudeCode\CLAUDE.md. Deployed by IT, and individual settings cannot exclude it
Auto memory: ~/.claude/projects/<project>/memory/, with MEMORY.md as the index and one file per memory. Claude writes it, and it stays on this machine

You don't need to hunt for the paths: run /memory in Claude Code to list these files, open any of them in your editor, and switch auto memory on or off. To see which files actually loaded in this session, run /context.

If a project only has an AGENTS.md for other coding agents and no CLAUDE.md, Claude Code 2.1.277 or later reads the AGENTS.md directly.

Want the full memory template system?

Claude Memory Framework is the open-source version I use myself, with 4 memory categories plus auto memory templates

See the Memory Framework →

Sources

How Claude remembers your project (official CLAUDE.md docs)

code.claude.com/docs/en/memory

Claude Code best practices

docs.anthropic.com/en/docs/claude-code/best-practices

Follow and share

Join the LINE community Follow on Instagram @kanisleo328 Follow on Threads @kanisleo328