Project-M/.claude/skills/dots-dev/references/memory-protocol.md

Memory & Documentation Protocol

How /dots-dev reads and writes knowledge. CLAUDE.md's "Memory — three layers" section is authoritative for the layer definitions and the which-tool-when routing (in-repo vault · basic-memory · native memory/) — this file does not re-table them; it carries the session bookends and the fallback chain. (serena removed 2026-07-07 — unused + flaky on Unity; C# nav = Glob/Grep.)

Cross-machine rule: anything that must be true on both the Mac and Windows machines goes in the vault (Docs/Vault/) or CLAUDE.md (both committed). Native memory/ is machine-local convenience — never the sole home of a decision or design fact.

Session bookends (non-negotiable for non-trivial work)

Start — scan (read-only):

1. CLAUDE.md (repo root).
2. Vault map of content + latest session log (07_Sessions/<year>/).
3. Open decision records (_Decisions/ status: proposed) + roadmap/backlog.
4. basic-memory recall on the goal's nouns; native MEMORY.md + memory/.

End — update (Phase 8):

1. Session log → the vault (obsidian-cli or direct Write).
2. Firm decisions → decision records, back-referenced from the log. The kept design-review Build Spec feeds the DR (don't re-derive it).
3. Touched design docs edited in place (wikilink, don't duplicate into the log).
4. Durable cross-machine knowledge → a basic-memory note in the vault; machine-local facts/feedback → native MEMORY.md (+ a memory file if substantive).
5. CLAUDE.md self-maintenance — if a new build gotcha or convention emerged, fold it in under the 40 KB budget (archive the displaced detail to the gotchas archive, don't delete). Never silently defer this — do it now or explicitly ask the operator to defer.

If the operator says "skip the protocol," still write a one-line stub session log so the gap is visible, and record the preference as a native feedback memory.

Fallbacks

• No obsidian-cli configured → direct Read/Write on Docs/Vault/** (it's plain markdown; Obsidian/basic-memory pick up changes on next index). This is the operative path on a fresh machine.
• basic-memory down → obsidian-cli search + Grep over the vault.

Setup pointer

The vault scaffold, the basic-memory .mcp.json entry, and CLAUDE.md are created by the one-time project setup task (Docs/dots-setup-task.md), not by this skill. If this skill runs and the vault or memory MCPs are missing, it notes the gap and points to that setup task.