Tiered Memory System
Apply when reading or writing to memory files under ~/.claude/projects/*/memory/.
Memory Architecture
Memory is organized in three tiers:
- L0 (Index):
MEMORY.md in each scope. Auto-loaded. Contains a routing table pointing to topic files. NEVER store knowledge here, only pointers. Keep under 50 lines.
- L1 (Topic Files): Categorized markdown files (e.g.,
decisions.md, debug-journal.md). Read on demand when a task requires that category of knowledge. Each has YAML frontmatter with last_updated and topics.
- L2 (Full Reference): PROJECT.md, ARCHITECTURE.md, source code, external docs. Read only when specific details are needed.
Cross-Scope Access
The root L0 index lives at your global memory scope:
~/.claude/projects/<root-scope>/memory/MEMORY.md
When working in a project directory, the project's own MEMORY.md auto-loads. For cross-project context (shared dependencies, infrastructure, cross-project decisions), explicitly read the root L0 index above, then follow its pointers.
Session Start
- MEMORY.md auto-loads (L0). Scan the routing table.
- If the project has a STATE.md or PROJECT.md, read it for current context.
- If the task relates to a topic in the L0 index, read that L1 topic file.
Continuous Updates
Do NOT wait for session end to update memory. Sessions can end abruptly with no exit hook. Update immediately:
- Bug fixed? Append to
debug-journal.md right after confirming the fix.
- Decision made? Append to
decisions.md right after the user approves.
- Pattern confirmed? Append to
patterns.md immediately.
- New topic file created? Update MEMORY.md's index table in the same action.
- Update the
last_updated field in both the topic file's YAML frontmatter and the L0 index table.
Memory Safety
- NEVER overwrite or rewrite an L1 topic file wholesale. Use Edit to append or update specific entries.
- When updating an entry, edit in place. When adding, append to end of file.
- Read a topic file before writing to it, to avoid duplicating existing entries.
- Do not perform more than 3 memory reorganization actions per user prompt (circuit breaker to prevent loops).
Scope Escalation
If an update affects more than the current project (shared dependency, cross-project pattern, common convention), log it in the ROOT scope, not just the local project memory.
Search Fallback
If the L0 index doesn't clearly point to the right topic file, use Grep across all memory files rather than guessing:
Grep pattern="<search term>" path="~/.claude/projects/<root-scope>/memory/" glob="*.md"
Staleness
If the L0 index shows a "Last Updated" date older than 90 days for a file you're about to read, flag it to the user and review the file's entries for accuracy. If a topic file is missing YAML frontmatter, treat it as stale and add default frontmatter on the next update.
Overflow
If an L1 topic file exceeds 150 lines, archive oldest entries to <topic>-archive-YYYY.md in a memory/archive/ subdirectory and replace them in the L1 file with a 3-5 line summary pointing to the archive.