Memory Management
Memory File Format
Frontmatter schema (simple key: value, NOT general YAML):
---
name: <string, required> # short identifier
description: <string, required> # one-line summary for relevance matching
type: <enum, required> # value | user | feedback | project | reference
---
- All values are plain strings, no quoting needed unless value contains
:
- No nested structures, no lists, no multi-line values
- Body follows after the closing
--- delimiter as markdown
MEMORY.md Index Format
- Plain markdown file, no frontmatter
- Contains links to individual memory files with brief descriptions
- Lines after 200 are truncated by Claude Code's loader — keep concise
- Entry format:
- [filename.md](filename.md) — brief description
- When writing: create individual .md file first, then append entry
Staleness Scoring
Exponential decay: score = 100 * (1 - exp(-age_days * ln(2) / half_life))
| Type |
Half-life |
Score 50 at |
Score 90 at |
| value |
365 days |
365d |
~1213d |
| user |
180 days |
180d |
~598d |
| feedback |
90 days |
90d |
~299d |
| reference |
60 days |
60d |
~199d |
| project |
14 days |
14d |
~47d |
| unknown |
30 days |
30d |
~100d |
Score-to-action: 0-50 = keep, 50-75 = review, 75-100 = prune.
Deep verification modifiers (additive, capped at 100):
- +20 if referenced file is missing
- +30 if referenced function/class not found
- +10 if URL returns non-200
- +15 if referenced branch doesn't exist
Claim Extraction Heuristics (Deep Audit)
| Claim Type |
Detection Pattern |
Verification |
| File path |
Contains /, ends with file extension |
Glob for existence |
| Function/class |
Backtick identifier in camelCase/PascalCase/snake_case |
Grep in project |
| URL |
Starts with http:// or https:// |
curl HEAD request |
| Branch |
After "branch" keyword or git pattern in backticks |
git branch -a |
| Package |
In dependency/package context |
Grep in manifest files |
Skip generic descriptions that aren't verifiable (e.g., "use a database" vs "uses PostgreSQL 15").
Destination Routing
| Destination |
When to Use |
Target Path |
| Memory file (value) |
Learned value choices — "X is better than Y" |
Session's project memory/ dir, type=value |
| Memory file |
Knowledge for Claude's future behavior |
Session's project memory/ dir |
| CLAUDE.md |
High-impact instructions for every conversation |
Session's project root CLAUDE.md |
| Knowledge file |
Human-readable notes, decision logs |
docs/knowledge/ in project root |
| Skip |
Session-specific, not worth preserving |
— |
Priority: Value choices are the most durable memories. When extracting, surface them first. Facts decay (files move, APIs change); values persist (readability > cleverness survives any rewrite).
Rule: Always target the session's originating project, not the current shell cwd.
Mutation Rules
| Layout |
How to Write |
| Index + files |
Create .md file with frontmatter, append to MEMORY.md |
| Standalone MEMORY.md |
Convert to index layout: create first .md file, rewrite MEMORY.md as index |
| No memory dir |
Create memory/, create MEMORY.md, create .md file |
| Malformed frontmatter |
Read as type=unknown. Never corrupt existing files. |
Archive Convention
- Location:
memory/archive/ subdirectory
- Files preserved intact (frontmatter + content)
- MEMORY.md entry removed on archive
iter_memories() skips archive/ — invisible to dashboard/audit/tokens- Standalone MEMORY.md: archiving not supported (offer delete or keep)
- Restore: manual move from
archive/ + re-add to MEMORY.md
1---2name: memory-management3description: Use when auditing, extracting, pruning, or writing Claude Code memory files. Covers memory file format, MEMORY.md index conventions, staleness scoring, claim extraction heuristics, destination routing, mutation rules, and archive conventions.4---56# Memory Management78## Memory File Format910Frontmatter schema (simple key: value, NOT general YAML):1112 ---13 name: <string, required> # short identifier14 description: <string, required> # one-line summary for relevance matching15 type: <enum, required> # value | user | feedback | project | reference16 ---1718- All values are plain strings, no quoting needed unless value contains `:`19- No nested structures, no lists, no multi-line values20- Body follows after the closing `---` delimiter as markdown2122## MEMORY.md Index Format2324- Plain markdown file, no frontmatter25- Contains links to individual memory files with brief descriptions26- Lines after 200 are truncated by Claude Code's loader — keep concise27- Entry format: `- [filename.md](filename.md) — brief description`28- When writing: create individual .md file first, then append entry2930## Staleness Scoring3132Exponential decay: `score = 100 * (1 - exp(-age_days * ln(2) / half_life))`3334| Type | Half-life | Score 50 at | Score 90 at |35|------|-----------|-------------|-------------|36| value | 365 days | 365d | ~1213d |37| user | 180 days | 180d | ~598d |38| feedback | 90 days | 90d | ~299d |39| reference | 60 days | 60d | ~199d |40| project | 14 days | 14d | ~47d |41| unknown | 30 days | 30d | ~100d |4243Score-to-action: 0-50 = keep, 50-75 = review, 75-100 = prune.4445Deep verification modifiers (additive, capped at 100):46- +20 if referenced file is missing47- +30 if referenced function/class not found48- +10 if URL returns non-20049- +15 if referenced branch doesn't exist5051## Claim Extraction Heuristics (Deep Audit)5253| Claim Type | Detection Pattern | Verification |54|------------|-------------------|--------------|55| File path | Contains `/`, ends with file extension | Glob for existence |56| Function/class | Backtick identifier in camelCase/PascalCase/snake_case | Grep in project |57| URL | Starts with `http://` or `https://` | curl HEAD request |58| Branch | After "branch" keyword or git pattern in backticks | `git branch -a` |59| Package | In dependency/package context | Grep in manifest files |6061Skip generic descriptions that aren't verifiable (e.g., "use a database" vs "uses PostgreSQL 15").6263## Destination Routing6465| Destination | When to Use | Target Path |66|-------------|-------------|-------------|67| Memory file (value) | Learned value choices — "X is better than Y" | Session's project `memory/` dir, type=value |68| Memory file | Knowledge for Claude's future behavior | Session's project `memory/` dir |69| CLAUDE.md | High-impact instructions for every conversation | Session's project root CLAUDE.md |70| Knowledge file | Human-readable notes, decision logs | `docs/knowledge/` in project root |71| Skip | Session-specific, not worth preserving | — |7273**Priority:** Value choices are the most durable memories. When extracting, surface them first. Facts decay (files move, APIs change); values persist (readability > cleverness survives any rewrite).7475**Rule:** Always target the session's originating project, not the current shell cwd.7677## Mutation Rules7879| Layout | How to Write |80|--------|-------------|81| Index + files | Create .md file with frontmatter, append to MEMORY.md |82| Standalone MEMORY.md | Convert to index layout: create first .md file, rewrite MEMORY.md as index |83| No memory dir | Create `memory/`, create MEMORY.md, create .md file |84| Malformed frontmatter | Read as type=unknown. Never corrupt existing files. |8586## Archive Convention8788- Location: `memory/archive/` subdirectory89- Files preserved intact (frontmatter + content)90- MEMORY.md entry removed on archive91- `iter_memories()` skips `archive/` — invisible to dashboard/audit/tokens92- Standalone MEMORY.md: archiving not supported (offer delete or keep)93- Restore: manual move from `archive/` + re-add to MEMORY.md
xiaolai