Memory in Claude Code
How Claude Code memory works, how to add memories with the # shortcut, and how to structure a CLAUDE.md that saves you context every session.
--- title: How Claude Code Memory Works author: FractionalSkill description: Claude Code's memory system lets you encode standing rules directly into a project without repeating yourself every session. Here is how operators deploy it. ---
How Claude Code memory works
Rules live in files. Every session, Claude Code reads those files before it does anything else. The rules you encode once carry forward automatically, whether you open Claude in the morning, switch to a different client folder, or hand the project to a colleague.
Most operators find this system by accident and never deploy it intentionally. That is where the value gets left on the table.
What memory actually is
"Memory" in Claude Code is not a database or a hidden system file. It is plain text written into a CLAUDE.md file. Claude reads that file when it starts a session, the same way it reads any other file in your project. The difference is it treats the contents as standing instructions, not document content.
This means you can encode decisions you make once and stop re-explaining them. Tell Claude your client uses Oxford commas. Tell it to always cite sources in footnotes, not inline. Tell it never to delete sections of a document without your approval. Write it once. It holds.
The CLAUDE.md file sits at the root of your project folder. If you work in a folder structure with sub-projects, Claude can read multiple CLAUDE.md files in a hierarchy. Rules closer to the current working directory take precedence.
> The practical frame: Think of CLAUDE.md as a standing brief you would give a new team member before they touched any client files. Conventions, constraints, named preferences. Once it exists, every session starts with that context already loaded.
How to add a memory without editing files manually
You do not have to open CLAUDE.md and type entries by hand. Claude Code has a shortcut.
Type # at the prompt. Claude enters memory mode and shows an "add to memory" prompt. Describe the rule you want in plain English. Hit return. Claude presents three options:
| Memory type | Where it writes | When to use it |
|---|---|---|
| Project memory | CLAUDE.md at your project root | Almost always. This is the one you want. |
| Local memory | A localized file scoped to your machine | Teams where individuals need personal overrides. Uncommon. |
| User memory | A global file across all projects | Not recommended. Rules bleed across unrelated work. |
Select project memory. Claude writes the rule to CLAUDE.md and confirms. Open the file and you will see it there in plain text, exactly as described.
The wording matters. Claude is good at interpreting plain-language rules, but specificity reduces ambiguity. "Always use the client's preferred terminology from the brand guide" is clearer than "be consistent." If a rule gets interpreted wrong in a session, reword it in CLAUDE.md directly.
The memory hierarchy for complex projects
Operators running multi-client work or nested folder structures need to understand this.
Claude Code reads CLAUDE.md files in a hierarchy: from the project root down to the current working directory. A rule in a sub-folder's CLAUDE.md overrides the same rule at the root level.
This means you can set global defaults at the top and override them client by client.
~/fractional-work/
├── CLAUDE.md ← Global rules: citation style, output format preferences
├── acme-corp/
│ ├── CLAUDE.md ← Acme-specific: voice, terminology, contact list
│ └── q3-board-deck/
│ └── CLAUDE.md ← Deck-specific: slide structure, length constraints
└── beacon-co/
└── CLAUDE.md ← Beacon-specific: different voice, different format
When you are working inside acme-corp/q3-board-deck/, Claude reads all three files. Acme-level rules override global ones. Deck-level rules override both. Nothing conflicts accidentally because the hierarchy is predictable.
For most fractionals running three to five clients, one CLAUDE.md per client folder is enough. Set global rules only for conventions that genuinely apply everywhere.
> Skip user memory. It writes rules that apply across every project on your machine, including unrelated ones. A rule that makes sense for one client can create friction in another. Keep rules in project scope.
Building your first CLAUDE.md
Start with the rules you re-explain most often. Common entries for fractional work:
- Output format defaults. "All deliverables should be in Markdown unless the client requests otherwise."
- Review constraints. "Never delete an existing section of a document without explicit approval."
- Naming conventions. "Refer to the client as 'Acme' not 'ACME Corp' in all output."
- Tone guardrails. "Match the formal register of the existing brand voice guide before producing any client-facing copy."
- Source rules. "Cite sources inline with the URL in parentheses. Do not use footnotes."
You can write these directly into CLAUDE.md or use the # shortcut mid-session when you catch yourself explaining something for the second time. That is the trigger worth building a habit around. The second time you type the same instruction, type # instead and encode it.
> One habit that compounds: At the end of each client engagement milestone, spend five minutes reviewing what instructions you gave Claude that session. Anything you typed more than once belongs in CLAUDE.md. Over three months, that file becomes a detailed operating manual for how you work with that client, and every new session starts fully briefed.
Memory and rules work together
Memory is most powerful when it runs alongside Claude Code's rules system. Rules handle enforcement: things Claude must always or never do. Memory handles context, standing knowledge about the client, the project, and your working preferences.
The # shortcut writes to the same CLAUDE.md file that rules live in. They are not separate systems. They are different kinds of entries in the same file.
A CLAUDE.md that combines both might look like this:
## Rules
- Never modify files outside the /deliverables folder without asking first
- Always run a spell check pass before marking a task complete
## Client context
- Client name: Acme Corporation (short form: Acme)
- Primary contact: Sarah Chen, CFO
- Preferred output format: PDF-ready Markdown, 12pt body, section headers in title case
- Tone: formal, data-led, no bullet points in executive summary sections
Claude reads all of it. Rules get enforced. Context gets applied. You spend zero time re-briefing.
The operators who get the most out of Claude Code are the ones who treat CLAUDE.md as a living document. Add to it when you notice repeated instructions. Revise it when a rule gets misinterpreted. Review it at the start of each new engagement phase. It is not a setup task you do once. It is a system you refine over time, and it gets sharper the longer you work in a project.