Memory & the single source of truth

Two of the four sources of truth deserve a closer look, because together they're what let a brand-new session pick up exactly where the last one left off.

docs/ARCHITECTURE.md — the single source of truth

This file describes how the system is structured right now: purpose, the stack, the directory layout (current and target), data flow, external dependencies, and conventions. The rule that makes it trustworthy:

When you change the structure, you change this file in the same unit of work — never "later." Code and this document must not drift.

Because every agent reads it first and edits it as they go, it doubles as the coordination surface for parallel work: an agent starting a non-trivial change leaves an "in progress" marker here so another agent doesn't duplicate it.

docs/ai/ — durable memory

Memory is granular and append-mostly:

• docs/ai/memory/NNNN-slug.md — one file per unit of work, capturing what was done, why, and how (key choices + where the code lives), with links to the wiki page, the ADR, and the commit.
• docs/ai/MEMORY.md — a one-line index, newest first.

A new session reads the index, opens the entries it needs, and is immediately oriented — no re-deriving past decisions, no asking the user to re-explain.

Why both, and why in the repo

ARCHITECTURE.md answers "what is the system now?" in one place; the memory log answers "how did we get here, and why?" over time. Keeping both in the repo (rather than in a single tool's private memory) means any model and any human reviewer sees the same history. Claude Code mirrors only a small pointer into ~/.claude so it auto-loads the in-repo memory each session; the repo copy is always canonical.