Memory

What this layer is: small note files Claude writes and reads between sessions, plus an index that is always loaded. Why it matters: CLAUDE.md holds stable rules. Memory holds what you learn along the way: corrections, decisions, gotchas. Without it you re-teach every week.

Core (everyone)

Where it lives

~/.claude/projects/<encoded-workspace-path>/memory/. The encoded path is your workspace path with every /, . and space replaced by - (/Users/maya/Work becomes -Users-maya-Work).

Memory follows the folder you start Claude in. Start claude in ~/Work and you get the workspace memory. Start it inside ~/Work/northlight/code (its own git repo) and you get a different, empty memory. So start day-to-day sessions from the workspace root and let the router load the project. Open a project folder directly only for focused coding.

The folder holds:

• MEMORY.md - the index. Loaded every session. One line per note.
• <name>.md - one note per fact.
• _index-<project>.md - an optional per-project index (lazy).

Four note types

Frontmatter is the same for all: name, description, metadata.type. Feedback and project notes have a rule line, then Why: and How to apply:. Link related notes with [[wikilinks]].

The index keeps context small

MEMORY.md is loaded into every session, so every line costs. Two rules:

1. One line per note, under ~150 characters, with a hook that says when it matters.
2. Per-project notes do not go in MEMORY.md. They go in _index-<project>.md, and MEMORY.md has one line pointing to that index: "READ FIRST when is mentioned". The workspace router (docs/01-rules.md) also tells Claude to read it.

This is a lazy index. Ten projects with 20 notes each is 200 lines you never load unless you talk about that project. Start with the template templates/memory/_index-project.md.

Incident to rule

Most good memory comes from something going wrong. The pattern:

1. Something breaks (a wrong email, a limit hit, a dead job).
2. Fix the thing.
3. Write a feedback or reference note: the rule, Why: with the date and what happened, How to apply: the check or habit.
4. Add one line to the index.

Write the incident in the Why. A rule with a story survives; a rule without one gets argued away. See example/memory/ for three of these.

When to save, when not to

Save: corrections, non-obvious choices you confirmed, gotchas, decisions with a date. Do not save: things visible in the code or git log, one-off task details, anything secret.

Advanced (developers)

• Dates. Convert relative dates ("next Thursday") to absolute dates in notes. A plan note without dates rots.
• Check before you trust. A note naming a file, flag or function is a claim from the past. Verify it exists before acting on it.
• Account separation. Personal and work accounts should not share memory by accident. Put a flag file (for example .private-memory) in any memory folder that must never be merged into a work repo. A sync script should refuse to touch a folder with that flag. Work accounts that share one team memory folder can be symlinked to the same directory on purpose.
• Transcripts. Session transcripts live in projects/ too. Share them across work accounts by symlink if you resume sessions across accounts. Never open the same session in two accounts at once.
• Search past sessions. A recall skill can grep old transcripts when memory has no answer.
• Generated indexes. A small script can rebuild _index-*.md from note frontmatter. Keep hooks hand-written; do not auto-generate them.

Memory hygiene

Memory decays. Expect it.

• Duplicates creep in. The same lesson gets saved three times under different names across sessions (model tiering, in one real setup, existed four times). Duplicates waste index lines and can drift apart.
• Prune monthly. Run /memory-prune (a skill you add, see skills/) on the first of the month. It should: list notes with near-identical descriptions, merge them, delete stale project notes (dates passed), and check that every index line points to a real file.
• Orphans. A note not in any index is invisible. A line pointing to a missing file is noise. The prune pass fixes both.
• Cap the index. If MEMORY.md passes ~200 lines, move a topic into its own _index-*.md.

Lessons from real use

• A scheduled backup was dead for 5 weeks. Cause: job log inside ~/Documents, which macOS blocks for background jobs. Rule saved as a reference note with the quick check command. See example/memory/jobs-outside-documents.md.
• 11 parallel opus agents hit the usage limit. About 3 hours lost. Rule saved: tier subagent models. The same rule was later saved 3 more times in other words, which is why pruning exists.
• An agent sent an email straight to a customer. Rule saved: drafts only, with one narrow written exception.
• A screenshot captured a private window. Claude took a screen capture while the user was working elsewhere. Rule saved: verify by reading the page, not by screenshot.
• Work facts leaked toward personal memory. Fixed by splitting memory by account and adding the private flag file.