SKILL.md
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(-agedays ln(2) / halflife))
| 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()skipsarchive/— 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