honey-memory

# Honey Memory Lever 2 applied to discovery cost. Every cold session re-greps the same things — where auth lives, the build command, *why* X is shaped Y. One committed file replaces N rediscovery round-trips with a single cached read, on every future session. The cheapest token is the one not re-derived. The win is per-session and recurring. The risk is staleness — a wrong cached fact costs *more* than no file. So the file lives in git, next to the code that can invalidate it, and is fixed in the same change that breaks it. ## Scaffold (create) 1. **One file per repo: `PROJECT.md` at the root**, committed (not `~/.claude`). If the repo already has `CLAUDE.md`/`AGENTS.md`, add/refresh a `## Memory` section there instead — don't add a second file. 2. **Back up before overwriting** an existing file: copy → `FILE.original.md`. If that backup already exists, stop and ask. Never clobber a restore point. 3. **Write only three kinds of fact** (derive by reading the repo): - **Architecture + conventions** an agent can't cheaply grep — where things live, and *why* (the intent, not the file list). - **Build / test / run** commands, env, and gotchas. - **Decisions and dead-ends** — choices made, paths tried and rejected. This is intent; it is never in the code. 4. **Report** what was written and the file path. ## Never store - Anything **derivable from source** — code structure, symbol locations, past fixes, git history. Re-deriving is cheaper than mai...