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
|
Memory lint + consolidation analyzer for the ClaudeTools REPO memory store
|
||||||
(.claude/memory/). Audits the index, backlinks, referenced file paths,
|
(.claude/memory/). Audits the index, backlinks, referenced file paths,
|
||||||
duplicate/overlap clusters, stale dated facts, and drift against the
|
duplicate/overlap clusters, stale dated facts, and drift against the
|
||||||
machine-local harness profile memory store. ADDITIVE-ONLY: the default run is
|
machine-local harness profile memory store. Default run is read-only.
|
||||||
read-only and mutates nothing; --apply-safe performs only non-destructive
|
--apply-safe performs the low-risk fixes (append missing index lines, copy
|
||||||
additive fixes (append missing index lines, migrate profile-only memories
|
any profile-only files into the repo for indexing). Cluster merges, dedup
|
||||||
into the repo). It NEVER deletes, merges, truncates, or overwrites -- every
|
deletes, and stale-fact removal are surfaced as PROPOSED actions for a
|
||||||
destructive idea is surfaced as a PROPOSED action for a human to approve.
|
human to apply -- they're judgment calls, not automation candidates. (Repo
|
||||||
Invoke for: "memory dream", "consolidate memory", "memory lint", "clean up
|
is the source of truth as of 2026-06-02; sync-memory.sh mirrors repo to
|
||||||
memory", "memory errors", "dedupe memory".
|
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
|
# Memory Dream
|
||||||
|
|
||||||
A read-only-by-default analyzer that keeps the shared memory store healthy
|
A read-only-by-default analyzer that flags issues in the shared memory store.
|
||||||
without ever risking the data in it.
|
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)
|
## 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
|
local, NOT in git, NOT synced. This is the store the Claude Code harness
|
||||||
auto-injects into the system prompt at session start.
|
auto-injects into the system prompt at session start.
|
||||||
|
|
||||||
The two drift over time. `memory-dream` reports that drift; the companion infra
|
The two drift over time. `memory-dream` reports that drift in its report
|
||||||
script `.claude/scripts/sync-memory.sh` reconciles it (additively).
|
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
|
## What it checks
|
||||||
|
|
||||||
@@ -70,17 +78,16 @@ NEVER auto-applied.
|
|||||||
- `--no-file` -- print to stdout only; skip writing the `_reports/` file.
|
- `--no-file` -- print to stdout only; skip writing the `_reports/` file.
|
||||||
- `--report-file <path>` -- write the report to an explicit path.
|
- `--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),
|
- delete a repo memory file (cluster dedup is a judgment call — pick which file becomes canonical, fold the others' content, retire the originals deliberately);
|
||||||
- removes or reorders an index line,
|
- remove or reorder index lines (index cleanups are also surfaced as proposals);
|
||||||
- overwrites a file whose content differs,
|
- overwrite a file whose content differs;
|
||||||
- performs a proposed merge or dedup.
|
- perform a proposed merge.
|
||||||
|
|
||||||
All of the above stay in the report as **proposals** for a human to action.
|
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.
|
||||||
This is deliberate: "additive at first so we don't wipe useful data."
|
|
||||||
|
|
||||||
## Running it
|
## Running it
|
||||||
|
|
||||||
@@ -110,8 +117,10 @@ location -- no hardcoded drive letters.
|
|||||||
and reported).
|
and reported).
|
||||||
3. Work the `## PROPOSED` section by hand:
|
3. Work the `## PROPOSED` section by hand:
|
||||||
- `[MERGE?]` -- decide whether to consolidate a cluster. If yes, author a new
|
- `[MERGE?]` -- decide whether to consolidate a cluster. If yes, author a new
|
||||||
combined memory, keep the originals or retire them deliberately, and update
|
combined memory (or set of files for a rule/history split), retire the
|
||||||
`MEMORY.md`. Never bulk-delete.
|
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
|
- `[REVERIFY?]` -- confirm the dated fact still holds; update the body and
|
||||||
its date if it changed.
|
its date if it changed.
|
||||||
- `[STALE-REF?]` -- confirm the referenced path moved/renamed; repoint or
|
- `[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
|
`scripts/selftest.py` runs the analyzer against a synthetic fixture memory
|
||||||
store in a temp dir and asserts each detector fires (orphan, missing target,
|
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
|
broken backlink, stale path, cluster, profile drift) and that `--apply-safe`
|
||||||
strictly additive (no deletions, no overwrites). Run:
|
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
|
```bash
|
||||||
py "$CLAUDETOOLS_ROOT/.claude/skills/memory-dream/scripts/selftest.py"
|
py "$CLAUDETOOLS_ROOT/.claude/skills/memory-dream/scripts/selftest.py"
|
||||||
|
|||||||
Reference in New Issue
Block a user