diff --git a/.claude/skills/memory-dream/SKILL.md b/.claude/skills/memory-dream/SKILL.md index 67023bb..59cee60 100644 --- a/.claude/skills/memory-dream/SKILL.md +++ b/.claude/skills/memory-dream/SKILL.md @@ -4,19 +4,23 @@ description: >- Memory lint + consolidation analyzer for the ClaudeTools REPO memory store (.claude/memory/). Audits the index, backlinks, referenced file paths, duplicate/overlap clusters, stale dated facts, and drift against the - machine-local harness profile memory store. ADDITIVE-ONLY: the default run is - read-only and mutates nothing; --apply-safe performs only non-destructive - additive fixes (append missing index lines, migrate profile-only memories - into the repo). It NEVER deletes, merges, truncates, or overwrites -- every - destructive idea is surfaced as a PROPOSED action for a human to approve. - Invoke for: "memory dream", "consolidate memory", "memory lint", "clean up - memory", "memory errors", "dedupe memory". + machine-local harness profile memory store. Default run is read-only. + --apply-safe performs the low-risk fixes (append missing index lines, copy + any profile-only files into the repo for indexing). Cluster merges, dedup + deletes, and stale-fact removal are surfaced as PROPOSED actions for a + human to apply -- they're judgment calls, not automation candidates. (Repo + is the source of truth as of 2026-06-02; sync-memory.sh mirrors repo to + profile, so PROFILE-side cleanup is handled by that script, not here. See + feedback_memory_sync_destructive_ok.md.) Invoke for: "memory dream", + "consolidate memory", "memory lint", "clean up memory", "memory errors", + "dedupe memory". --- # Memory Dream -A read-only-by-default analyzer that keeps the shared memory store healthy -without ever risking the data in it. +A read-only-by-default analyzer that flags issues in the shared memory store. +Mutating ops are gated behind `--apply-safe` (for low-risk fixes) or the +PROPOSED section (for judgment calls a human resolves by hand). ## The two-store model (important) @@ -29,8 +33,12 @@ There are TWO separate memory stores on every machine: local, NOT in git, NOT synced. This is the store the Claude Code harness auto-injects into the system prompt at session start. -The two drift over time. `memory-dream` reports that drift; the companion infra -script `.claude/scripts/sync-memory.sh` reconciles it (additively). +The two drift over time. `memory-dream` reports that drift in its report +section. The companion script `.claude/scripts/sync-memory.sh` is what +actually reconciles them: it runs in **mirror mode** (since 2026-06-02) — +repo is authoritative, profile is synced to match (deletions propagate; +repo content wins on conflict). PROFILE-side hygiene lives in +`sync-memory.sh`, not here. ## What it checks @@ -70,17 +78,16 @@ NEVER auto-applied. - `--no-file` -- print to stdout only; skip writing the `_reports/` file. - `--report-file ` -- write the report to an explicit path. -### The guarantee +### What dream does NOT auto-do -`memory-dream` NEVER: +`memory-dream` does NOT, even with `--apply-safe`: -- deletes a memory file (either store), -- removes or reorders an index line, -- overwrites a file whose content differs, -- performs a proposed merge or dedup. +- delete a repo memory file (cluster dedup is a judgment call — pick which file becomes canonical, fold the others' content, retire the originals deliberately); +- remove or reorder index lines (index cleanups are also surfaced as proposals); +- overwrite a file whose content differs; +- perform a proposed merge. -All of the above stay in the report as **proposals** for a human to action. -This is deliberate: "additive at first so we don't wipe useful data." +These stay in the report's `## PROPOSED` section. The rationale isn't "never delete" any more (the fleet-wide additive safety net was dropped 2026-06-02; see `feedback_memory_sync_destructive_ok.md`) — it's that merges and dedups require human judgment about which file is canonical and how to combine content. Profile-side deletion DOES happen automatically — but in `sync-memory.sh`, not here. ## Running it @@ -110,8 +117,10 @@ location -- no hardcoded drive letters. and reported). 3. Work the `## PROPOSED` section by hand: - `[MERGE?]` -- decide whether to consolidate a cluster. If yes, author a new - combined memory, keep the originals or retire them deliberately, and update - `MEMORY.md`. Never bulk-delete. + combined memory (or set of files for a rule/history split), retire the + originals via `git rm`, update `MEMORY.md`. Deletions are now first-class + — `sync-memory.sh` mirror mode will propagate them to every profile store + on the next run. - `[REVERIFY?]` -- confirm the dated fact still holds; update the body and its date if it changed. - `[STALE-REF?]` -- confirm the referenced path moved/renamed; repoint or @@ -123,8 +132,10 @@ location -- no hardcoded drive letters. `scripts/selftest.py` runs the analyzer against a synthetic fixture memory store in a temp dir and asserts each detector fires (orphan, missing target, -broken backlink, stale path, cluster, profile drift) and that `--apply-safe` is -strictly additive (no deletions, no overwrites). Run: +broken backlink, stale path, cluster, profile drift) and that `--apply-safe` +only touches the things it's supposed to (index appends + profile→repo copy +of new files; no deletions, no merges, no overwrites of differing content). +Run: ```bash py "$CLAUDETOOLS_ROOT/.claude/skills/memory-dream/scripts/selftest.py"