brewpi/docs/claude-faq.md

# Claude FAQ

Notes on how Claude Code works with this repo, for later reference.

## Does Claude store a separate memory/context for planning work like the overshoot investigation, or is the TODO enough?

**Q:** After a long session diagnosing the HOLD-state overshoot and writing
up the fix plan in `docs/overshoot_hold_windup.md` / `components/pid/TODO.md`,
I asked: did you also store a context and/or memory for easier retrieval
later, or is the TODO enough?

**A:** No separate memory was created for the plan's *content* — that lives
in the committed docs (`docs/overshoot_hold_windup.md` +
`components/pid/TODO.md`), which is strictly better than Claude's own memory
system for this: it's version-controlled, visible to anyone with repo
access, and gets updated in place as the real work happens. Claude's memory
system explicitly excludes storing "architecture/file paths/design content
already derivable by reading the project" — duplicating a plan into memory
would just be a second, decaying copy of the same facts.

What Claude *does* keep in memory is a **pointer**, not the content: an
existing `pid_design_backlog.md` memory says (in effect) "check
`components/pid/TODO.md` before starting PID work." That pointer was 15
days stale at the time and had a couple of now-wrong claims (e.g. it said
the three Kalman filters sharing one tuning was "still open", but
`temp_controller_smith.py` had since dropped Kalman filtering entirely) —
so it was refreshed in the same turn, with one line added noting this
session's windup investigation exists and where to find it, without
copying the investigation's content into memory.

**Takeaway:** for durable project knowledge that belongs in the repo
(design decisions, investigation writeups, TODOs), the repo docs *are* the
memory — Claude's own memory system is reserved for cross-session pointers,
preferences, and facts that aren't otherwise written down anywhere in the
project.