Skip to main content

Purpose

In one line: A hub file (MEMORY.md) indexes topic-specific spoke files; the AI reads the hub at session start so knowledge is a structural input, not a per-session re-explanation.

What: Memory files are markdown documents in the project memory directory (~/.claude/projects/{project-path}/memory/). The hub MEMORY.md indexes specialized files by topic and is read at session start.

Why: The context window is large but finite and resets between sessions. Any decision, preference, debugging insight, or constraint not written where the AI reads it at session start does not exist for the new session.

The alternative is repeating instructions every session ("we use Alembic, never manual ALTER TABLE; the driver needs CAST not :: syntax; these are the ports…"). That is tedious, error-prone, and wastes context on what should load automatically. Memory makes the knowledge structural.

Hub-and-Spoke Architecture:

The hub budget is enforced in BYTES — the loader's unit: 24,000 bytes. A line count is gameable and gets gamed: a hub can sit at a modest line count yet exceed the byte cap several-fold, at which point the harness silently truncates the tail — dropping the durable half (bug patterns, user preferences, standing debt) while loading stale PR narratives. Under truncation, section order is policy: durable sections come FIRST; perishable active-work entries come LAST, one line each (≤250 characters). Enforcement is mechanical: templates/hooks/memory-budget-check.sh runs as an advisory Stop hook. MEMORY.md contains:

  • Mission and quality standards (the project's purpose and non-negotiable principles)
  • Architecture quick reference (enough to orient the AI, with links to detailed files)
  • User preferences (working style decisions that should be followed without asking)
  • Known technical debt (prevents the AI from assuming everything works as designed)
  • Upcoming tasks (provides session planning context)
  • Links to detailed memory files (the "spokes")

Each linked memory file covers a single topic in depth: pillar progress, regulatory compliance, technical patterns, component registry, feature inventory. This structure keeps MEMORY.md concise (fast to read at session start) while providing depth on demand (Claude can read specific memory files when working on a related task).

Evidence: Enforced by templates/hooks/memory-budget-check.sh — the advisory Stop hook flags a hub that exceeds the 24,000-byte loader cap before truncation silently drops the durable sections. Reproducible: grow a hub past the cap and watch the hook fire. See appendix-d-memory.md.

How: Memory files are created and updated as part of the development workflow. The /finishing-a-development-branch skill includes a memory update step. Memory is also updated when the developer provides feedback, makes a decision, or corrects a misunderstanding. For the full memory system specification, see appendix-d-memory.md.