The memory layer
Re-reading source code to reconstruct intent is a token tax the agent pays on every prompt. Throughspec pays it once by writing a small set of durable memory files, then reads a compressed snapshot instead of re-scanning the repo.
The files
CLAUDE.mdThe behavior contract Claude reads before every prompt: how to work here, invariants, and active integrations.claude/srs.mdThe frozen requirements - the source of truth for what the software must do.claude/plan.mdThe 8-10 stage build plan with checkbox state the agent flips as it ships.claude/context.mdA compressed snapshot of current state - what exists, what works, what is next.claude/features.mdAn append-only log of completed features and their final shape.claude/design-decisions.mdAn append-only log of architectural and product decisions with rationale.claude/learnings.mdAn append-only learning trail (used heavily by the Student persona).Append-only logs never rewrite history. If a past entry was wrong, a new entry corrects it - so the reasoning trail stays intact.
Why it stays cheap
CLAUDE.md + context.md are kept under an ~8,000-token budget so loading full project context is a small, fixed cost no matter how large the repo grows. When a memory file passes 1,500 lines, /spec-sync compresses it while preserving a compressed-from audit trail.
Memory is sacred: after every feature cycle, update context.md, features.md, design-decisions.md, learnings.md, and CHANGELOG.md - in that order.