# Memory map — conventions

## Why files, not a database

Grep-able, diffable, human-editable, portable; git gives versioning and history for free. Files
form a graph: each file is a node, each relative link an edge.

## Inventory

| File | Role | Entry point? |
|---|---|---|
| `AGENTS.md` | Rules + invariants | **always read** |
| `ai.md` | Router: product, build, architecture, where truth lives | yes |
| `HANDOFF.md` | Current state (≤40 lines, overwritten) | yes |
| `TASKS.md` | Active queue | when asking "what's next" |
| `docs/ai/*.md` | Subsystem truth, one file each | when the task touches it |
| `MyMistakes.md` | Failure log + recipes | grep first |

## Rules

1. **Semantic filenames.** No codes, no abbreviations.
2. **One `index.md` per code directory**, listing every file with a one-line purpose.
3. **Links over hierarchy.** Anything unreachable from `ai.md` may as well not exist.
4. **Stale facts get fixed, not appended.**
5. **Progressive disclosure.** Detail lives one level down, never crammed into the router.

## Reading order

1. `AGENTS.md` → 2. `HANDOFF.md` → 3. `ai.md` → 4. the one `docs/ai/<topic>.md` → 5. `<dir>/index.md`
→ 6. the source (always the authority over any memory file).

## Integration rule

Every change ships with the facts it **falsifies** corrected, in the same commit. Broader
restatement may be batched at a milestone.