From da832b961eef98b452e50d7d1c89d41d17ea1765 Mon Sep 17 00:00:00 2001 From: Jens Ahrensfeld Date: Sat, 4 Jul 2026 12:57:21 +0200 Subject: [PATCH] docs: add claude-faq.md, starting with memory-vs-docs Q&A Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01KefnwbGDM8CGrhb4sFhVq9 --- docs/claude-faq.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 docs/claude-faq.md diff --git a/docs/claude-faq.md b/docs/claude-faq.md new file mode 100644 index 0000000..8449cd2 --- /dev/null +++ b/docs/claude-faq.md @@ -0,0 +1,35 @@ +# 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.