memory-dream

Consolidate memory into a smaller, current, non-duplicated, reviewable store.

This is a manual memory garbage-collection and consistency pass. It is not ordinary note-taking, not transcript summarization, and not a license to rewrite memory from guesses.

Core contract

This skill is user-triggered only.

Default behavior:

• Inspect the memory store.
• Detect the store layout before assuming paths.
• In --dry-run, never edit files.
• Without --dry-run, edit only when evidence is strong.
• Before any destructive or broad change, show a review summary.
• Do not push.
• Do not modify unrelated files.
• Do not modify this skill file unless the user explicitly asks to update the skill.

$ARGUMENTS may contain:

• no argument: inspect the detected memory store
• MEMORY.md: focus on the index
• a filename such as project_tbaygo.md: focus on one recall file
• notes: focus on notes, if the hierarchy has notes
• projects: focus on project memory, if the hierarchy has projects
• auto-memory: focus on auto-memory, if the hierarchy has auto-memory
• since <git-ref>: in git mode, prioritize changes after the given ref
• --dry-run: review only; do not edit
• --commit: in git mode only, prepare commits after user approval

Safety invariants

Always follow these rules:

• Do not modify AGENTS.md.
• Do not push.
• Do not use git add -A.
• Do not stage unrelated user changes.
• Do not overwrite memory blindly.
• Do not invent facts.
• Do not convert uncertain inference into memory.
• Do not store credentials, tokens, cookies, private keys, passwords, one-time codes, API keys, session secrets, or unnecessary personal data.
• Do not preserve process history in final memory files.
• Do not add meta-comments such as "duplicated elsewhere", "not repeated here", "removed because repeated", or "learned from previous mistake".
• Do not record who pointed something out, how many times it happened, session IDs, failed attempts, or "why this was learned" narratives.
• If a conflict cannot be resolved from reliable evidence, leave memory unchanged and list it under unresolved conflicts in the review output.

Technical causality may stay when it changes future behavior.

Good:

Do not run `git add -A`; it may stage unrelated user changes.

Bad:

The user corrected this multiple times, so remember not to use `git add -A`.

Store detection

Detect the memory store before doing any consolidation.

Mode A — git hierarchy store

Use this mode when the current directory or user-provided target contains a memory hierarchy such as:

AGENTS.md
MEMORY.md
auto-memory/MEMORY.md
auto-memory/*.md
notes/*.md
projects/*.md

AGENTS.md is read-only and must never be edited.

In this mode, git may be available. Commits are allowed only after user approval.

Mode B — Claude flat auto-memory store

Use this mode when the real store is a flat Claude Code project memory directory, typically:

~/.claude/projects/<encoded-project-path>/memory/

A common encoded path is made by replacing / with -.

Example:

/home/ubuntu

maps to:

/home/ubuntu/.claude/projects/-home-ubuntu/memory/

This store usually looks like:

MEMORY.md
feedback_*.md
project_*.md
reference_*.md
*.md

In flat mode:

• MEMORY.md is the index.
• Every other *.md file is a recall file.
• There is no AGENTS.md.
• There may be no git repository.
• There are usually no notes/, projects/, or auto-memory/ subdirectories.
• Do not try to refresh a notes/ index.
• Do not commit unless the memory directory is inside a git repository and the user explicitly asks.
• Before editing, create a backup outside the memory directory.

Flat mode detection commands may include:

pwd
date +%F
memory_dir="$HOME/.claude/projects/$(pwd | sed 's#/#-#g')/memory"
test -d "$memory_dir" && test -f "$memory_dir/MEMORY.md" && echo "$memory_dir"
find "$HOME/.claude/projects" -path '*/memory/MEMORY.md' -print 2>/dev/null

If multiple memory stores are plausible, ask the user which one to consolidate.

Evidence policy

Prefer current, local, verifiable evidence.

Strong evidence includes:

• current repository files
• current memory files
• tracked git history, if available
• current file paths verified by test -e, git ls-files, or find
• current symbols verified by rg
• explicit user instructions in the current task

Weak evidence includes:

• vague recollection
• old memory entries without confirmation
• inferred intent
• relative-date statements
• point-in-time status words such as "currently", "still running", "now", "目前", "现在", "仍在"
• references to files, symbols, flags, commands, deployments, hosts, or workflows that cannot be verified locally

Only write strong evidence into memory. Put weak evidence in the review output.

Phase 0 — Prepare

Start by inspecting the store safely.

For all modes:

pwd
date +%F

For git hierarchy mode:

git status --short
git branch --show-current
git log --oneline --decorate -n 30
git diff --stat
git diff
git ls-files
find notes -type f -name '*.md' | sort

For flat mode:

cd "$memory_dir"
find . -maxdepth 1 -type f -name '*.md' ! -name 'MEMORY.md' -printf '%f\n' | sort
wc -l MEMORY.md
rg -n "today|yesterday|last week|recently|currently|still running|now|目前|现在|仍在|前回|之前|最近|昨日|今日" .

If the worktree has unrelated user changes, record them and avoid touching or staging them.

If $ARGUMENTS contains --dry-run, stop after review. Do not edit.

Phase 1 — Mine

Mine the selected memory store for durable, recurring, actionable information.

Look for:

• duplicate rules
• duplicate project facts
• duplicate operational procedures
• stale file paths
• stale command names
• stale function, class, module, flag, environment variable, or script references
• contradictions between memory files
• index entries that repeat recall-file body content
• index entries with excessive detail
• relative dates such as "today", "yesterday", "last week", "recently", "前回", "之前", or "最近"
• point-in-time statuses that may now be stale
• completed task notes that no longer affect future behavior
• process history that should not be in final memory

Do not keep one-off debugging notes unless they became durable procedure.

Do not scan unrelated private logs or transcripts outside the selected memory store unless the user explicitly asks.

Phase 2 — Consolidate

Merge useful findings into the correct layer.

General rules:

• Convert relative dates into absolute dates using the current date from date +%F.
• Replace old values with newer confirmed values.
• Keep only current, actionable facts and procedures.
• Remove obsolete entries only after verifying they are obsolete.
• If a path, deployment, host, service, branch, or symbol may exist outside the local environment, do not delete it automatically; list it as uncertain in the review output.

Mode A hierarchy rules

Use this hierarchy:

AGENTS.md > MEMORY.md > auto-memory/MEMORY.md > auto-memory/*.md > notes/*.md > projects/*.md

AGENTS.md is highest authority and read-only.

Deduplicate downward:

• If AGENTS.md defines a rule, remove duplicate copies from lower layers.
• If MEMORY.md defines shared knowledge, remove duplicate copies from lower layers unless the lower layer adds genuinely local detail.
• If a note or playbook defines a procedure, other files may point to it in one short operational sentence but must not restate it.
• If a project file repeats general team rules, remove the repeated rule and keep only project-specific exceptions or details.

specs/ files are project design documents, not general memory. Do not edit specs/ unless the user explicitly includes that scope.

Mode B flat-store rules

Use this hierarchy:

MEMORY.md index > recall files

This does not mean the index is where facts belong. In flat mode:

• MEMORY.md should be a compact routing index.
• Each recall file should have exactly one useful hook in MEMORY.md.
• Recall-file bodies hold the durable details.
• The index should not duplicate long project status, commit hashes, deployment history, pushed branch names, or detailed troubleshooting notes.
• The index should answer: "When should Claude open this file?"
• A good index hook is usually one short line.
• Prefer 80–180 characters per hook.
• Hooks over roughly 250 characters are candidates for compression.

Good flat index hook:

- `project_tbaygo.md`: TbayGo project memory; use for deployment topology, rollout/rollback notes, project commands, and gotchas.

Bad flat index hook:

- `project_tbaygo.md`: Full multi-phase status with commit hashes, pushed origin state, rollback service details, exact host status, fixes, review corrections, and historical progress.

In flat mode, do not move details into MEMORY.md. If a detail is useful, keep it in the recall file. If the recall file already contains it, remove the duplicate from the index.

Flat index health checks

In flat mode, verify index/file consistency.

Expected:

• Every recall *.md file except MEMORY.md has one index hook.
• Every indexed filename exists on disk.
• No orphan recall files exist.
• No duplicate index entries exist.
• No backup files are created inside the memory directory.

Useful commands:

cd "$memory_dir"
find . -maxdepth 1 -type f -name '*.md' ! -name 'MEMORY.md' -printf '%f\n' | sort
rg -n '\.md' MEMORY.md

When parsing the index, be conservative. Preserve the repository's existing index style unless it is clearly broken.

Backup policy for non-git flat mode

In flat mode, before editing any file, create a backup outside the memory directory.

Do not put backup *.md files inside the memory directory, because they may be mistaken for recall files.

Use a path like:

backup_dir="${TMPDIR:-/tmp}/memory-dream-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$backup_dir"
cp -p "$memory_dir/MEMORY.md" "$backup_dir/MEMORY.md"

If editing recall files too, copy each edited file to the backup directory before modification.

After editing, show a diff against the backup:

diff -u "$backup_dir/MEMORY.md" "$memory_dir/MEMORY.md" || true

Phase 3 — Dedup and resolve

Deduplicate from lower authority to higher authority.

In hierarchy mode:

• Remove repeated rules from lower layers.
• Keep one definition place for each rule, fact, or procedure.
• Keep local exceptions in lower layers.

In flat mode:

• Compress MEMORY.md into routing hooks.
• Remove long body-like summaries from the index.
• Keep detailed facts inside recall files.
• If multiple recall files repeat the same fact, keep the fact in the most specific appropriate file and remove or shorten the duplicate only when the correct owner is obvious.
• If ownership is unclear, list it in the review output.

Do not write explanations about deduplication into final memory files.

Phase 4 — Prune and index

Prune aggressively but safely.

For MEMORY.md in hierarchy mode:

• Keep it compact.
• Keep shared facts, high-level indexes, and stable cross-project conventions.
• Keep notes index synchronized.
• Prefer short entries over long narratives.

For MEMORY.md in flat mode:

• Keep it as one hook per recall file.
• Remove commit hashes unless the filename itself is about commit references.
• Remove pushed-to-origin status.
• Remove detailed phase history.
• Remove "review correction" or "again checked" narratives.
• Remove point-in-time operational status unless the hook would be meaningless without it.
• Keep enough information to route retrieval correctly.

For recall files:

• Keep durable current facts.
• Keep project-specific commands and gotchas.
• Keep deployment details only if still useful.
• Convert relative dates to absolute dates.
• Mark uncertain point-in-time state for user review instead of rewriting it.

Notes index refresh for hierarchy mode

Only in hierarchy mode, regenerate the notes list with:

find notes -type f -name '*.md' | sort

If MEMORY.md already has a notes-list section, replace the entire existing code block with the command output.

If no notes-list section exists, add a concise section named notes 一览 or preserve the repository's existing heading style.

Do this whenever notes are added, moved, deleted, renamed, or when the existing list is stale.

Do not perform this step in flat mode.

Stale reference verification

Before removing or updating a stale reference, verify it.

Useful checks:

test -e <path>
git ls-files | rg '<path-or-name>'
find . -path './.git' -prune -o -name '<name>' -print
rg --fixed-strings '<symbol-or-command>'
rg '<symbol_regex>'

For deployments, hosts, remote services, market positions, and current runtime state, local verification may be insufficient. If not verifiable, do not edit automatically. List it as an unresolved stale candidate.

Conflict policy

Resolve conflicts only when newest reliable evidence is clear.

If clear:

• update the older entry
• remove the contradictory duplicate
• keep only the current value

If unclear:

• leave memory unchanged
• list the conflict in the review output
• include the files involved
• ask the user what the correct value should be

Never choose a side just to make the memory look clean.

Output hygiene

Final memory files must contain only current useful content.

Exclude:

• consolidation reasoning
• failure stories
• session IDs
• "learned on" metadata
• "the user said" history
• repeated correction counts
• obsolete task progress
• old TODOs with no future value
• duplicate-avoidance notes
• speculative guesses
• credentials or secrets

Review output

Before any edit in normal mode, and always in --dry-run, produce a concise review summary.

Use this format:

Memory Dream Review

Detected store:
- Mode:
- Path:
- Git available:

Scope:
- ...

Index health:
- ...

Changed files:
- ...

Confirmed updates:
- ...

Duplicates removed:
- ...

Stale references removed or updated:
- ...

Stale candidates needing confirmation:
- ...

Unresolved conflicts:
- ...

Intentionally not changed:
- ...

Checks run:
- ...

Next action:
- ...

In --dry-run, Changed files must say that no files were changed.

The review output may contain reasoning and history. Final memory files must not.

Validation after edits

After edits, validate before finishing.

For hierarchy mode:

git diff --check
git diff --stat
git diff
git status --short
git diff -- AGENTS.md

git diff -- AGENTS.md must be empty. If AGENTS.md changed, revert that change before continuing.

For flat mode:

cd "$memory_dir"
find . -maxdepth 1 -type f -name '*.md' ! -name 'MEMORY.md' -printf '%f\n' | sort
rg -n '\.md' MEMORY.md

If a backup exists, show:

diff -u "$backup_dir/MEMORY.md" "$memory_dir/MEMORY.md" || true

Confirm that no backup files were created inside the memory directory.

Commit protocol

Only hierarchy mode should normally create commits.

Do not commit until the user approves after reviewing the summary.

When committing:

• stage only the files changed by this memory-dream task
• do not use git add -A
• do not stage unrelated pre-existing changes
• use one logical commit unless there are clearly separate units
• never push

Suggested commit messages:

memory: consolidate memory store
memory: refresh notes index
memory: prune stale project memory
memory: add memory-dream skill

Before committing, show the exact files to be staged.

After committing, show:

git status --short
git log --oneline -n 3

In flat mode, say that no commit was created unless the user explicitly requested one and the memory store is actually inside a git repository.

Final response

End with:

• detected store mode and path
• what was consolidated
• what changed
• what remains unresolved
• whether a backup was created
• whether commits were created
• confirmation that no push was performed
• the next recommended command, if useful

Example invocations

/memory-dream --dry-run

/memory-dream MEMORY.md --dry-run

/memory-dream MEMORY.md

/memory-dream project_tbaygo.md --dry-run

/memory-dream notes --dry-run

/memory-dream projects

/memory-dream since HEAD~30