The three layers of memory
A Claude Code session loses its context once it ends. That is exactly why you need a way to persist the learnings worth keeping. In this environment we separate them into three layers, each with a different purpose.
How the three layers divide the work
| Layer | Location | What to keep | Entry point | Category |
|---|---|---|---|---|
| learnings | ~/.claude/learnings/{core,frontend-vue,...}/ | Technical tips and pitfalls (cross-cutting knowledge) | /learn | 🔧 |
| Project memory | ~/.claude/projects/.../memory/ | Facts and history specific to that repository | Automatic / explicit request | 📦 |
| Handoff context | ~/.claude/context/ | Handoff between sessions | /smart-handoff / /smart-pickup | 🔧 |
Of these three layers, only project memory is Claude Code standard (📦). The category design of learnings and /learn, and the handoff /smart-handoff / /smart-pickup, are mechanisms the author built (🔧) to cover use cases that the standard memory alone could not handle (cross-project knowledge, carrying work over between sessions). Note that project memory (auto memory) is enabled by default in Claude Code v2.1.59 and later.
learnings — cross-cutting knowledge
learnings/ is where you accumulate technical tips and pitfalls by category (core / frontend-vue / frontend-react / infra). The target is knowledge that helps in any project. In /debug terms, the "same-pattern bug" you found during Generalize, or an insight for preventing recurrence, gets written here with /learn.
learnings is not the goal. Once something is judged worth codifying, it gets "promoted" to a formal rule in rules/ or to a hook. This promotion flow is the Ratchet covered in Ratchet.
Project memory — repository-specific facts
Project memory is where you keep facts that only have meaning in that repository, one fact per file. You do not keep what you can learn by reading the code or git history; you write only "the history and constraints you cannot understand even by reading."
Each memory carries frontmatter, and you add a one-line pointer to an index file called MEMORY.md. This index is loaded at the start of a session, so facts learned in the past are recalled immediately. The frontmatter format, the index, and the auto-loading are all standard mechanisms (📦); what is on the author's side is only the operational judgment of "what to keep and what not to keep."
---
name: tech-notes-docs-index-slug
description: Writing a slug in index.md doubles the URL; omit it and let auto de-dup handle it
metadata:
type: project
---
The real frontmatter also gets fields like node_type and the originating session ID added automatically.
In fact, while writing this guide, past pitfalls were recalled from memory. Things like "do not write a slug in index.md" and "use sidebar_label to give a different name so the guide's category name and its landing page name do not collide." It is a living record for not stepping into the same hole twice.
handoff — carrying a session over
When you pause a long task partway through, /smart-handoff saves the current context to context/. In the next session, /smart-pickup lets you resume from there. Just before the context is compacted, precompact-snapshot.sh (the PreCompact hook in How hooks work) also stashes the state.
What to keep and what not to keep
You should not write just anything into memory. The guiding axis is simple.
- Keep: history, constraints, and the reasons behind design decisions that you cannot learn by reading the code; user preferences; pitfalls that could recur
- Do not keep: code structure, git history, past fixes—anything you can learn by looking at the repository (duplication breeds confusion)
The key points:
- Persistence has three layers: learnings (cross-cutting knowledge), project memory (specific facts), and handoff (carrying over)
- Only project memory is standard (📦); learnings and handoff are the author's own (🔧) to supplement the standard
- learnings get promoted to rules / hooks if worth codifying (the Ratchet covered next)
- Project memory is one fact per file plus a
MEMORY.mdindex, recalled at startup - Do not keep "what you can learn by reading the code"
With this, the mechanics of each layer are in place. In Ratchet, we use them to see the flow of "turning learnings into mechanisms."