Memory: Claude's Own Persistent Store

The concept in one sentence: Memory is the one Claude Code mechanism where Claude writes to a persistent file — not you.

Every other persistence mechanism in Claude Code is user-maintained: you write CLAUDE.md, you write skills, you configure hooks. Memory is different. When you tell Claude to remember something, Claude writes it down and loads it automatically next session. The flow is reversed.

The four persistence mechanisms, compared

To understand Memory, it helps to see it alongside the other mechanisms:

Mechanism Who writes Who reads Scope What it contains
CLAUDE.md You Claude Project or global Standing rules, conventions, project context
Skills You Claude Project or global Reusable task prompts
Hooks You Claude Code Project or global Automated shell triggers
Memory Claude Claude Global only Facts and preferences Claude has learned

The direction of authorship matters. CLAUDE.md is instructions you give Claude. Memory is facts Claude collects for itself on your behalf.

Where Memory lives

Memory is stored in a single global file: ~/.claude/MEMORY.md

It is always global — there is no project-specific memory file. Whatever Claude remembers is available in every session, from every project. This is both its strength (you do not have to re-establish the same facts in each project) and its limitation (you cannot have memory that applies only to one project).

Claude Code loads ~/.claude/MEMORY.md automatically at the start of every session, alongside your global CLAUDE.md and any project CLAUDE.md. It is part of the foundation layer that is in place before you type anything.

How to use it

Asking Claude to remember something:

> Remember that I prefer output in Czech when writing for a general audience,
  and English for academic work.

Claude writes this to ~/.claude/MEMORY.md and confirms. The next session, Claude will know this without you saying it.

> Remember that my Zotero library uses the author-date citation style
  and never uses ibid.

> Remember that in this project I use "deponent" not "witness" — the term
  matters for precision.

Viewing what Claude has remembered:

/memory

This opens the current content of ~/.claude/MEMORY.md for inspection. You can read it, edit it directly, or ask Claude to remove or update specific items.

Removing a memory:

> Remove the memory about Czech vs. English — that preference has changed.

Or edit ~/.claude/MEMORY.md directly with any text editor.

What belongs in Memory vs. CLAUDE.md

This is the practical question. Both mechanisms put information in Claude's context at session start. The distinction is about origin and nature of the content:

Memory is for things that emerge from use:

CLAUDE.md is for things you deliberately configure:

A useful test: Did this content arise from a conversation, or did you sit down and write it? If it arose from a conversation — you corrected Claude, you stated a preference, Claude asked you something — it belongs in Memory. If you designed it deliberately to configure Claude's behaviour for a project — it belongs in CLAUDE.md.

In practice, Memory handles the personal, cross-project layer; CLAUDE.md handles the project-specific, deliberate-design layer. They complement each other.

What Memory is not good for

Project-specific facts. Memory is global. If you ask Claude to remember something about Project A, that memory also loads in Projects B and C, where it may be irrelevant or misleading. Project-specific facts (conventions, source descriptions, extraction rules) belong in the project's CLAUDE.md, not in Memory.

Detailed procedural instructions. Memory is for facts and preferences — compact, propositional content. Detailed multi-step instructions belong in CLAUDE.md or as a skill. Memory that becomes a long list of procedures will work poorly; it dilutes the signal.

In-progress state. What you did yesterday, what task you are in the middle of, what files have been processed so far — this belongs in a progress file within the project (a progress.md or similar), not in Memory. Memory is for stable, enduring facts, not current task state.

Confidential project data. Memory is global and not scoped. Anything written to ~/.claude/MEMORY.md will be loaded in every Claude Code session. Do not use Memory for sensitive project content that should not leak across projects.

The maintenance question

Memory accumulates. Items added months ago may be outdated; preferences may have changed; corrections made for one context may be wrong in another.

Review periodically:

/memory

Read the full list. Remove what is no longer true. Update what has changed. A Memory file that grows without pruning becomes noisy — Claude loads it all, and stale facts can interfere with correct ones.

The signal for pruning: If Claude is behaving oddly in a way you cannot explain from CLAUDE.md or the current context, check Memory. A stale memory item is a common source of silent, hard-to-diagnose incorrect behaviour.

Memory in the context of the full system

Session start (what Claude already "knows"):
  ├── Claude Code system prompt (built-in, fixed)
  ├── ~/.claude/MEMORY.md          ← what Claude has learned about you
  ├── ~/.claude/CLAUDE.md          ← what you have configured globally
  └── project/CLAUDE.md            ← what you have configured for this project

During the session:
  ├── Skills available              ← reusable prompts you have written
  └── Hooks active                  ← automated triggers you have configured

Memory is the first user-level layer — the most personal and the most general. Everything else is either more specific (project CLAUDE.md) or more behavioural (skills, hooks).

A note on authorship and trust

Because Claude writes to Memory on your behalf, what ends up there reflects Claude's judgment about how to record what you asked. If you ask Claude to "remember that I prefer shorter responses," Claude will phrase that in its own words. The content is yours; the formulation is Claude's.

This is worth checking occasionally. Open /memory and read it not just for completeness but for accuracy — does each item say what you actually meant? A memory that is slightly off will behave slightly off in every subsequent session.

Related