How to add a new memory file

Status: 🟩 COMPLETE Last updated: 2026-06-19 Plain-English tagline: Adding a memory in Claude Code is a TWO-STEP process — write the memory file, then add a pointer to it in MEMORY.md. Skipping the second step means the memory exists but isn’t auto-loaded; common mistake.

Goal

By the end of this guide, you can manually create or upgrade memory files in ~/.claude/projects/<project>/memory/ correctly — including the frontmatter, the file location, and the critical MEMORY.md index entry that makes the memory discoverable across future conversations.

This is the procedure Claude Code itself follows when saving memories. Doing it by hand lets you create memories at any time without going through Claude — useful for moving content between projects, fixing memories that drifted, or seeding a new project’s memory tree.

Why it matters

Memories are how Claude Code remembers things across sessions. A well-organized memory tree means future conversations don’t waste tokens re-discovering things you’ve already established.

The two-step process matters because:

Memory FILES (e.g., project_tech_stack.md) are loaded ON DEMAND when referenced by name
MEMORY.md is loaded AUTOMATICALLY at the start of every conversation
A memory not listed in MEMORY.md is effectively invisible until Claude reads it for some other reason

Skipping the MEMORY.md update is the #1 way memories quietly fail to apply.

Prerequisites

Claude Code installed and running on at least one project
You know the project name’s folder format in ~/.claude/projects/ (see step 1)
The memory location exists (it usually does once you’ve used Claude Code in the project)

For Bible Quest specifically:

The folder is C:\Users\georg\.claude\projects\C--Users-georg\memory\ (note: a SHARED memory folder across all of George’s projects because they share a parent path)

Steps

1. Locate the memory folder for the project

On disk, the memory folder is at:

~/.claude/projects/<encoded-project-path>/memory/

Where <encoded-project-path> is the project’s path with separators replaced. Examples:

C:\Users\georg\ → C--Users-georg
/Users/george/projects/myapp → -Users-george-projects-myapp

Find the right folder:

# Windows
ls ~\.claude\projects\
 
# Mac/Linux
ls ~/.claude/projects/

Pick the folder matching your project’s path. Inside it should be a memory/ subfolder.

For Bible Quest: C:\Users\georg\.claude\projects\C--Users-georg\memory\.

2. Decide on a name + type for the memory

Naming convention (use kebab-case for the file, descriptive slug):

user_*.md — facts about you (the user)
feedback_*.md — guidance about how you want Claude to behave
project_*.md — information about a specific project
playbook_*.md — reusable conventions / methodologies
reference_*.md — pointers to external resources

Examples from George’s setup:

user_role.md — “I’m not a programmer”
feedback_encyclopedia_quality.md — the iron-clad quality rule
project_tech_stack.md — Bible Quest’s stack
playbook_webapp_stack.md — defaults for any new webapp
reference_personal_encyclopedia.md — pointer to ~/encyclopedia/

Use a name that’s specific enough to find later. user_preferences.md is bad; user_role.md is good.

3. Write the memory file

Each memory has frontmatter + body. The structure:

---
name: short-kebab-case-slug
description: One-line summary of what this memory captures — used to decide relevance in future conversations
metadata:
  type: user | feedback | project | reference
---
 
# Memory title (optional — usually a clean restate of the description)
 
Body of the memory in plain prose or sections. Be specific. Use the structure that suits the content:
 
- For **feedback / project memories**, include:
  - The rule, fact, or decision
  - **Why:** — the reasoning (often a past incident or stated preference)
  - **How to apply:** — when this guidance kicks in
 
- For **user memories**, just clear facts.
- For **reference memories**, the pointer + when to use it.
 
Link related memories with `[[other-memory-name]]`.

A concrete example — project_test_strategy.md:

---
name: project-test-strategy
description: "Bible Quest testing strategy — what's tested and how"
metadata:
  type: project
---
 
# Bible Quest test strategy
 
- Vitest for unit tests on utility functions in `lib/`
- React Testing Library for component tests (when needed; minimal at this point)
- Playwright for one critical-path E2E test (login + answer first question)
- TypeScript + ESLint as the dominant quality layers — type checking catches most bugs without explicit tests
 
**Why:** Solo-developer project; investing in heavy test suite would slow shipping. Type checking + lint + one E2E + manual smoke testing is the right level.
 
**How to apply:** When adding a feature, ask "does this need a test?" Default to no for UI tweaks; yes for pricing logic, auth flows, payment, or anything I'd be embarrassed to ship broken. See [[playbook-testing]].
 
## Tests we have
- (currently minimal — to be expanded as features land)
 
## Tests we explicitly DON'T have
- Visual regression
- Cross-browser tests beyond Chrome / Safari smoke
- Mobile device tests (rely on emulation + manual checks)

Save this file to the memory folder.

4. Add the pointer to `MEMORY.md`

Open MEMORY.md in the memory folder. Add a one-line entry pointing to the new file:

- [Bible Quest test strategy](project_test_strategy.md) — what's tested and how

Format: - [Title](filename) — one-line hook (under ~150 chars).

Put the entry in a sensible section. The existing MEMORY.md is organized:

## Cross-project playbook
- [Playbook index](playbook_index.md) — start here when beginning any new project
...
 
## User
- [User is not a programmer](user_role.md) — needs step-by-step guidance
 
## Personal encyclopedia
- [Personal encyclopedia](reference_personal_encyclopedia.md) — live reference at ...
...
 
## St Mark's Bible Quest (current project)
- [Bible Quest project](project_bible_study_app.md) — full Bible study webapp...
- [Bible Quest tech stack](project_tech_stack.md) — Next.js 16 + Supabase + Vercel...
- [Bible Quest progress log](project_progress_log.md) — chronological build log...
- [Bible Quest test strategy](project_test_strategy.md) — what's tested and how    ← NEW

Save MEMORY.md.

5. Verify

Open a NEW Claude Code conversation (or run /clear in the current one). Ask:

> What memories are loaded for this conversation?

Claude lists MEMORY.md entries. Your new entry should appear. Then ask:

> What's our test strategy?

Claude should recall it accurately, citing the new memory.

If Claude doesn’t seem to know, check:

The file was saved in the right location
MEMORY.md has the new entry
The frontmatter is valid YAML
The file name matches what MEMORY.md references

Verification

A correctly-added memory:

✅ The .md file exists in ~/.claude/projects/<folder>/memory/
✅ The file has valid frontmatter (name, description, metadata.type)
✅ MEMORY.md includes a one-line entry pointing to it
✅ A fresh Claude Code conversation can recall the memory’s content
✅ The frontmatter description is meaningful enough that future Claude can decide relevance

Common failures and fixes

”I wrote the memory but Claude doesn’t know it”

Almost certainly: you didn’t update MEMORY.md. The memory FILE exists; the INDEX entry doesn’t.

ls ~/.claude/projects/<folder>/memory/

Verify your new file is in the listing. Then open MEMORY.md and add the entry.

”I added it to MEMORY.md but it still doesn’t apply”

Three causes:

The conversation cache — current conversation read the OLD MEMORY.md. Run /clear or open a new session.
Wrong project folder — ~/.claude/projects/<folder>/memory/ is per-project; you may have edited the wrong project’s MEMORY.md.
Frontmatter is invalid — a YAML syntax error makes the file skip silently. Verify with a YAML validator if uncertain.

”MEMORY.md is over 200 lines”

MEMORY.md is loaded fully into every conversation. Lines past ~200 are truncated. Consolidate:

Group related entries
Move large content INTO the linked file, keep MEMORY.md to one-line entries
Periodically run the /consolidate-memory skill to prune duplicates

”Two memories say opposite things”

Memories layered over time can contradict. Resolution:

Read both
Decide which is current
Delete or update the stale one
Update MEMORY.md accordingly

Don’t let contradictions pile up. Inconsistent memories produce inconsistent behavior.

”I want to move a memory between projects”

Memories live per-project folder, but the playbook ones (playbook_*.md) often apply to ALL projects.

For George’s setup specifically: the memory folder ~/.claude/projects/C--Users-georg/memory/ is shared because all projects share the parent path C:\Users\georg\. Memories in that folder load for every project in that path.

To explicitly share a memory across multiple projects:

Put it in the global ~/.claude/CLAUDE.md (auto-loads for ALL projects)
Or duplicate it to each project’s memory folder (no auto-sync)

“I want to delete a memory”

Two-step delete:

Remove the file from the memory folder
Remove the entry from MEMORY.md

If you forget step 2, MEMORY.md references a missing file — most loaders handle this gracefully (link is broken) but it’s untidy.

”I want to update a memory’s name”

Three-step rename:

Rename the file (old-name.md → new-name.md)
Update the name: field in the frontmatter
Update the link in MEMORY.md

All three steps must agree.

”My memory’s content is wrong or outdated”

Just edit it. Update the body, optionally update the description: frontmatter if the meaning shifted. No need to touch MEMORY.md if the title/file didn’t change.

”Claude saved a memory automatically; where is it?”

When Claude saves a memory mid-conversation, it follows this same procedure: creates the file, adds the MEMORY.md entry. After it announces “saved memory X,” you can find the file by name in the memory folder.

A concrete example walkthrough

George decides he wants Claude to know: “When tweaking dark mode, always check both modes in DevTools, not just visually.”

Step 1: Decide name + type

Name: feedback_dark_mode_verification.md
Type: feedback

Step 2: Write file at C:\Users\georg\.claude\projects\C--Users-georg\memory\feedback_dark_mode_verification.md:

---
name: feedback-dark-mode-verification
description: "Always verify both light AND dark modes in DevTools when changing styles — not just visually"
metadata:
  type: feedback
---
 
# Dark mode verification rule
 
When making style changes, ALWAYS verify both light and dark modes by toggling DevTools' "Emulate CSS prefers-color-scheme" feature.
 
**Why:** A 2026-06-15 incident — a contrast fix improved light mode but broke dark mode by introducing a pure-black text-on-dark-gray combination. Wasn't caught until production.
 
**How to apply:**
- When editing any Tailwind class involving color tokens
- When changing color CSS variables
- When updating components with explicit color values
- Use Chrome DevTools' device toolbar → "Rendering" tab → "Emulate CSS prefers-color-scheme" → "dark"

Step 3: Add to MEMORY.md under the appropriate section:

## Feedback / behavior
- [Dark mode verification](feedback_dark_mode_verification.md) — always check both modes in DevTools after style changes

Step 4: Verify

In a new Claude Code session, ask “Any rules for changing styles?” Claude mentions the dark-mode verification rule.

Total time: 3 minutes. Future conversations get the rule automatically.

What just happened, conceptually

Claude Code’s memory system has two tiers:

MEMORY.md — loaded INTO context on every conversation. Should be the INDEX of all memories. Each line is a pointer + hook (description) to help Claude decide which memory to load when.
Memory files — loaded ON DEMAND when relevant. Claude reads MEMORY.md, sees a relevant title or description, opens the file.

Adding a memory means doing BOTH steps. Just the file isn’t enough (it’s invisible unless Claude stumbles on it). Just the entry isn’t enough (the description hook is too thin to act on).

Over time, the memory tree grows. Periodically consolidate:

Merge duplicates
Update outdated facts
Remove memories no longer relevant
Keep MEMORY.md under ~200 lines

The /consolidate-memory skill exists for this; run it occasionally.

Sources

Claude Code memory docs
Anthropic Skills — consolidate-memory — the periodic cleanup

Tech & AI, Explained

Explorer

add-memory-file

How to add a new memory file

Goal

Why it matters

Prerequisites

Steps

1. Locate the memory folder for the project

2. Decide on a name + type for the memory

3. Write the memory file

4. Add the pointer to `MEMORY.md`

5. Verify

Verification

Common failures and fixes

”I wrote the memory but Claude doesn’t know it”

”I added it to MEMORY.md but it still doesn’t apply”

”MEMORY.md is over 200 lines”

”Two memories say opposite things”

”I want to move a memory between projects”

“I want to delete a memory”

”I want to update a memory’s name”

”My memory’s content is wrong or outdated”

”Claude saved a memory automatically; where is it?”

A concrete example walkthrough

What just happened, conceptually

See also

Sources

Graph View

Table of Contents

Backlinks

Tech & AI, Explained

Explorer

add-memory-file

How to add a new memory file

Goal

Why it matters

Prerequisites

Steps

1. Locate the memory folder for the project

2. Decide on a name + type for the memory

3. Write the memory file

4. Add the pointer to MEMORY.md

5. Verify

Verification

Common failures and fixes

”I wrote the memory but Claude doesn’t know it”

”I added it to MEMORY.md but it still doesn’t apply”

”MEMORY.md is over 200 lines”

”Two memories say opposite things”

”I want to move a memory between projects”

“I want to delete a memory”

”I want to update a memory’s name”

”My memory’s content is wrong or outdated”

”Claude saved a memory automatically; where is it?”

A concrete example walkthrough

What just happened, conceptually

See also

Sources

Graph View

Table of Contents

Backlinks

4. Add the pointer to `MEMORY.md`