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:
@@ -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"
|
||||
|
||||
Reference in New Issue
Block a user