claudetools/.claude/skills/memory-dream/SKILL.md

name, description

name

description

memory-dream

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".

Memory Dream

A read-only-by-default analyzer that keeps the shared memory store healthy without ever risking the data in it.

The two-store model (important)

There are TWO separate memory stores on every machine:

• REPO store -- .claude/memory/ (88+ *.md files + MEMORY.md index). Tracked in git, syncs to all machines via Gitea. This is the source of truth. CLAUDE.md mandates writing here.
• HARNESS PROFILE store -- $HOME/.claude/projects/<slug>/memory/. 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).

What it checks

scripts/memory_dream.py runs six READ-ONLY analyses over the REPO store:

1. INDEX RECONCILE -- orphan files (no MEMORY.md line), index lines whose target file is missing, and frontmatter name: vs filename signals.
2. BACKLINKS -- [[name]] references in bodies whose target slug has no file.
3. REFERENCED-ARTIFACT VALIDITY -- conservatively extracts repo-relative file paths / script names from each body (backtick-wrapped single tokens only) and flags ones not found in the repo. Reported as verify, never delete (many are legitimately server-side or in sibling repos).
4. DUPLICATE / OVERLAP CLUSTERS -- groups memories by type + token-overlap / shared slug-prefix and lists candidate mergeable clusters (e.g. the many feedback_syncro_* files). Proposes merges; never performs them.
5. STALE DATED FACTS -- flags project-type memories with an "as of " style claim older than ~6 months for re-verification.
6. DRIFT vs PROFILE STORE -- locates the harness profile memory dir for this project and reports profile-only files (candidates to migrate INTO the repo) and repo-only files (candidates to push OUT to profile). Report only.

The report ends with a ## PROPOSED (needs human approval) section that is NEVER auto-applied.

Modes

• Default (no flag) -- REPORT ONLY. Mutates nothing. Writes a timestamped report to .claude/memory/_reports/YYYY-MM-DD-HHMM-dream.md (created if missing) and prints it to stdout.
• --apply-safe -- performs ONLY additive, non-destructive fixes and prints each action:
  • (a) append missing index lines to MEMORY.md for orphan files, under the correct ## <Type> header, never reordering or removing existing lines;
  • (b) copy profile-only memory files INTO the repo store (additive migration). If a same-named repo file already exists it is SKIPPED and the conflict is reported -- it is never overwritten.
• --no-file -- print to stdout only; skip writing the _reports/ file.
• --report-file <path> -- write the report to an explicit path.

The guarantee

memory-dream NEVER:

• deletes a memory file (either store),
• removes or reorders an index line,
• overwrites a file whose content differs,
• performs a proposed merge or dedup.

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."

Running it

This machine's Python launcher is py (per identity.json); the script also runs under python / python3. Stdlib only -- no pip deps.

# REPORT ONLY (default) -- writes _reports/<stamp>-dream.md and prints it
py "$CLAUDETOOLS_ROOT/.claude/skills/memory-dream/scripts/memory_dream.py"

# report to stdout only, write nothing
py "$CLAUDETOOLS_ROOT/.claude/skills/memory-dream/scripts/memory_dream.py" --no-file

# additive-only fixes (append orphan index lines, migrate profile-only files)
py "$CLAUDETOOLS_ROOT/.claude/skills/memory-dream/scripts/memory_dream.py" --apply-safe

CLAUDETOOLS_ROOT resolves from the env var, else claudetools_root in .claude/identity.json, else the repo root derived from the script's own location -- no hardcoded drive letters.

Cleanup / approve workflow

1. Run with no flag. Read the report (stdout or _reports/<stamp>-dream.md).
2. Run --apply-safe to take the safe additive wins: orphan index lines get added, profile-only memories get migrated into the repo (conflicts skipped 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.
   • [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 annotate. Many are legitimately server-side (.service units, /opt/...).
   • [INDEX-CLEANUP?] / [DRIFT-RESOLVE?] -- human picks the winner.
4. Commit the repo store changes so they sync to the fleet via Gitea.

Self-test

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:

py "$CLAUDETOOLS_ROOT/.claude/skills/memory-dream/scripts/selftest.py"