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.