# Memory & Documentation Protocol

How `/dots-dev` reads and writes knowledge. **`CLAUDE.md`'s "Memory — four layers" section is authoritative** for the layer definitions and the which-tool-when routing (in-repo vault · `basic-memory` · `serena` · native `memory/`) — this file does not re-table them; it carries the **session bookends** and the **fallback chain**.

**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.
- **serena C# unavailable / stalls on the Unity solution** → `Glob`/`Grep` (or `claude-context`/LanceDB if it was added as the documented fallback).

## Setup pointer

The vault scaffold, the `basic-memory`/`serena` `.mcp.json` entries (using `${CLAUDE_PROJECT_DIR}`), 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.