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))

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)

Skip generic descriptions that aren't verifiable (e.g., "use a database" vs "uses PostgreSQL 15").

Destination Routing

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

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