Memory

Memory

Where it lives

Persistent memory sits under ~/.claude/projects/<project key>/memory/, where the project key derives from the working directory with slashes turned into hyphens. A home of /home/alice gives -home-alice.

The installer creates that directory and drops two files in it: MEMORY.md, the index, and EXAMPLE.md, a sample to delete once real memories start accumulating.

The rule that keeps it useful

One memory is one file holding one fact, with frontmatter:

---
name: short-kebab-case-slug
description: one-line summary, used to decide relevance during recall
metadata:
  type: user | feedback | project | reference
---

The fact itself.

MEMORY.md holds one line per memory and nothing else:

- [Title](file.md) : short hook

That separation is the whole point. The index is loaded into context at every session, so it has to stay small; the content lives in files that are read only when relevant. Putting memory content directly into MEMORY.md turns a cheap index into an expensive permanent payload, which is exactly the failure this structure prevents.

The four types

Type	What belongs there
user	Who the user is: role, expertise, preferences
feedback	Guidance on how to work, corrections and confirmed approaches, always with the why
project	Ongoing work, goals, constraints that the code does not already record
reference	Pointers to external resources: URLs, dashboards, tickets

For feedback and project, the body should carry a Why and a How to apply line. A rule without its reason gets misapplied the first time the situation shifts slightly.

What does not belong in memory

Anything the repository already records: code structure, past fixes, git history, the content of CLAUDE.md. Memory is for what is not derivable from the files in front of you.

The same goes for anything that only matters inside one conversation. If it will not be useful in three weeks, it is not a memory.

Absolute dates

Relative dates rot. "Last week" written six months ago means nothing, and worse, it reads as if it were still true. Convert to absolute dates when writing a memory.

Starting fresh

MEMORY.md ships empty apart from its explanatory header, and EXAMPLE.md exists only to show the format. Delete the example once you have real memories; leaving it behind means one useless file consulted on every recall.