docs(memory-dream): drop additive-only framing; reflect mirror-mode policy

SKILL.md still narrated the 2026-06-01-and-earlier additive-only stance.
With the policy change captured in feedback_memory_sync_destructive_ok.md
and sync-memory.sh now in mirror mode, the framing needed updating.

Behavior of the tool itself is unchanged (--apply-safe still only does
the low-risk index appends + profile->repo copies; merges/dedups still
land in PROPOSED for a human). The reasons given for that are now:
they're judgment calls, not "we might wipe useful data."

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-06-02 16:27:47 -07:00
parent 43c0835515
commit 88b02cc43b

View File

@@ -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 <path>` -- 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"