Skip to main content
OrchestKit v8.11.1 — 111 skills, 37 agents, 212 hooks · Claude Code 2.1.148+
OrchestKit
Skills

Dream

Nightly memory consolidation — prunes stale entries, merges duplicates, resolves contradictions, rebuilds MEMORY.md index. Use when memory files have accumulated over many sessions and need cleanup. Do NOT use for storing new decisions (use remember) or searching memory (use memory).

Command medium
Invoke
/ork:dream

Dream - Memory Consolidation

Deterministic memory maintenance: detect stale entries, merge duplicates, resolve contradictions, rebuild the MEMORY.md index. All pruning decisions are based on verifiable checks (file exists? function exists? duplicate content?), not LLM judgment.

Argument Resolution

DRY_RUN = "--dry-run" in "$ARGUMENTS"  # Preview changes without writing

Overview

Memory files accumulate across sessions. Over time they develop problems:

  • Stale references — memories pointing to files, functions, or classes that no longer exist
  • Duplicates — multiple memories covering the same topic with overlapping content
  • Contradictions — newer memories superseding older ones without cleanup
  • Index drift — MEMORY.md index out of sync with actual memory files

This skill fixes all four problems using deterministic checks only.

Cadence (CC 2.1.142+): Reactive compaction now sizes its first summarize attempt to the actual overflow, so long sessions stall mid-turn far less often. The "run nightly" cadence can relax toward "run when memory files accumulate" — consolidation is no longer needed to head off compaction inefficiency.


STEP 1: Discover Memory Files

# Find the memory directory (agent-specific or project-level)
# Agent memory lives in: .claude/agent-memory/<agent-id>/
# Project memory lives in: .claude/projects/<hash>/memory/
# Also check: .claude/memory/

memory_dirs = []
Glob(pattern=".claude/agent-memory/*/MEMORY.md")
Glob(pattern=".claude/projects/*/memory/MEMORY.md")
Glob(pattern=".claude/memory/MEMORY.md")

# For each discovered MEMORY.md, glob all *.md files in that directory
for dir in memory_dirs:
    Glob(pattern=f"{dir}/../*.md")  # All memory files alongside MEMORY.md

Read every discovered memory file. Parse frontmatter (name, description, type) and body content. Build an in-memory inventory:

inventory = [{
    "path": "/abs/path/to/file.md",
    "name": frontmatter.name,
    "type": frontmatter.type,  # user, feedback, project, reference
    "description": frontmatter.description,
    "body": body_text,
    "file_refs": [],      # extracted file paths
    "symbol_refs": [],    # extracted function/class names
    "topics": [],         # key phrases for duplicate detection
}]

STEP 2: Detect Staleness

For each memory file, extract references and verify they still exist.

2a: File Path References

Extract paths that look like file references (patterns: paths with / and file extensions, backtick-wrapped paths):

# Regex-like extraction from body text:
# - Paths containing / with common extensions: .py, .ts, .tsx, .js, .json, .md, .yaml, .yml, .sh
# - Backtick-wrapped paths: `src/something/file.ts`
# - Quoted paths in frontmatter descriptions

for ref in file_refs:
    Glob(pattern=ref)  # Check if file exists
    # If no match → mark as STALE_FILE_REF

2b: Symbol References

Extract function/class names (patterns: function_name(), ClassName, def function_name):

for symbol in symbol_refs:
    Grep(pattern=symbol, path=".", output_mode="files_with_matches", head_limit=1)
    # If no match → mark as STALE_SYMBOL_REF

2c: Staleness Classification

FindingClassificationAction
All file refs valid, all symbols foundFRESHKeep
Some file refs missingPARTIALLY_STALEFlag for review
All file refs missing AND all symbols missingFULLY_STALEPrune candidate
No external refs (pure decision/preference)EVERGREENKeep

Only memories classified as FULLY_STALE are auto-pruned. PARTIALLY_STALE memories are reported but kept — the user decides.


STEP 3: Detect Duplicates

Compare memories pairwise within the same directory. Two memories are duplicates when:

  1. Same type (both feedback, both project, etc.)
  2. Overlapping topic — 60%+ of significant words (excluding stopwords) appear in both bodies
  3. Same subjectname or description fields reference the same concept
stopwords = {"the", "a", "an", "is", "are", "was", "were", "be", "been",
             "have", "has", "had", "do", "does", "did", "will", "would",
             "could", "should", "may", "might", "can", "shall", "to", "of",
             "in", "for", "on", "with", "at", "by", "from", "as", "into",
             "through", "during", "before", "after", "this", "that", "it",
             "not", "no", "but", "or", "and", "if", "then", "than", "so"}

def significant_words(text):
    words = set(text.lower().split()) - stopwords
    return {w for w in words if len(w) > 2}

def overlap_ratio(words_a, words_b):
    if not words_a or not words_b:
        return 0.0
    intersection = words_a & words_b
    smaller = min(len(words_a), len(words_b))
    return len(intersection) / smaller if smaller > 0 else 0.0

# For each pair with same type:
#   if overlap_ratio >= 0.6 → DUPLICATE pair
#   Keep the NEWER file (by filesystem mtime), prune the older

STEP 4: Resolve Contradictions

Contradictions occur when two memories of the same type make opposing claims about the same subject. Detection:

  1. Same type + same topic (overlap >= 0.4 but < 0.6 — related but not duplicate)
  2. Negation signals — one body contains negation of the other's assertion:
    • "do X" vs "do not X" / "don't X" / "never X"
    • "use X" vs "avoid X" / "stop using X"
    • "prefer X" vs "prefer Y" (for same decision domain)
negation_pairs = [
    ("do ", "do not "), ("do ", "don't "),
    ("use ", "avoid "), ("use ", "stop using "),
    ("prefer ", "don't prefer "), ("always ", "never "),
]

# For each pair flagged as contradictory:
#   Keep the NEWER file (more recent decision supersedes)
#   Prune the older file

STEP 5: Execute Changes (or Dry Run)

Dry Run Mode (--dry-run)

If --dry-run flag is present, skip all writes. Output the full report (Step 6) with [DRY RUN] prefix and list what WOULD be changed:

[DRY RUN] Would delete: .claude/agent-memory/foo/stale_old_path.md (FULLY_STALE)
[DRY RUN] Would delete: .claude/agent-memory/foo/duplicate_auth.md (DUPLICATE of auth_patterns.md)
[DRY RUN] Would delete: .claude/agent-memory/foo/old_preference.md (CONTRADICTED by new_preference.md)
[DRY RUN] Would rebuild: .claude/agent-memory/foo/MEMORY.md (3 entries removed, 12 remaining)

Live Mode

# 1. Delete FULLY_STALE files
for stale in fully_stale_files:
    Bash(command=f"rm '{stale['path']}'")

# 2. Delete DUPLICATE files (keep newer)
for dup in duplicate_pairs:
    older = dup["older"]
    Bash(command=f"rm '{older['path']}'")

# 3. Delete CONTRADICTED files (keep newer)
for contradiction in contradiction_pairs:
    older = contradiction["older"]
    Bash(command=f"rm '{older['path']}'")

# 4. Rebuild MEMORY.md index from surviving files

Rebuild MEMORY.md

Read all surviving .md files (excluding MEMORY.md itself). Generate the index:

# <Directory Name> Memory

- [Name](filename.md) -- one-line description from frontmatter

Rules for the rebuilt index:

  • One line per memory file, under 150 characters
  • Sorted alphabetically by filename
  • Total index must stay under 200 lines
  • If over 200 lines after rebuild, warn the user (do not auto-truncate content memories)
# Write the rebuilt MEMORY.md
Write(path="<memory_dir>/MEMORY.md", content=rebuilt_index)

STEP 6: Report

Output a summary table after consolidation:

## Dream Consolidation Report

| Metric | Count |
|--------|-------|
| Memory directories scanned | N |
| Total memory files scanned | N |
| Stale entries pruned | N |
| Duplicates merged | N |
| Contradictions resolved | N |
| Partially stale (kept, flagged) | N |
| Evergreen (no external refs) | N |
| Surviving memories | N |
| MEMORY.md indexes rebuilt | N |

### Changes Made

| File | Action | Reason |
|------|--------|--------|
| `path/to/file.md` | DELETED | Fully stale: all referenced files removed |
| `path/to/old.md` | DELETED | Duplicate of `path/to/new.md` |
| `path/to/outdated.md` | DELETED | Contradicted by `path/to/current.md` |

### Flagged for Review (PARTIALLY_STALE)

| File | Missing References |
|------|-------------------|
| `path/to/file.md` | `src/old/path.ts` no longer exists |

If --dry-run, prefix the entire report with:

[DRY RUN] No files were modified. Run without --dry-run to apply changes.

Error Handling

ConditionResponse
No memory directories foundReport "No memory directories found" and exit
No memory files in directoryReport "Directory empty, nothing to consolidate"
All memories are FRESHReport "All N memories are current, nothing to prune"
MEMORY.md exceeds 200 lines after rebuildWarn user, do not auto-truncate
File deletion failsReport error, continue with remaining files
Memory file has no frontmatterTreat as EVERGREEN (cannot verify refs without metadata)

STEP 7: Plugin Housekeeping (CC 2.1.121+, #1544)

After memory consolidation, check for orphaned auto-installed plugin dependencies and offer to prune them:

# Detect orphans
claude plugin list --json | jq '[.[] | select(.auto_installed == true and .reason_kept == "orphaned")] | length'

# If > 0 and last prune > 7 days ago (track in .claude/state/last-prune.txt):
claude plugin prune  # interactive — confirms before removing

Skip this step on CC < 2.1.121. The state file .claude/state/last-prune.txt records the last successful prune date so we don't run it on every dream invocation.


STEP 8: Stale Project State Hint (CC 2.1.126+, #1582, fixed in #1587)

After plugin housekeeping, surface a non-blocking suggestion when stale project state exists. Never execute the purge — only preview it.

# Skip on CC < 2.1.126 (no `claude project purge` available)

# Detect stale projects via the authoritative source: `claude project purge --dry-run --all`
# emits `config: projects["<canonical-path>"]` lines that come straight from ~/.claude.json.
# Parsing these is lossless; the directory-name encoding under ~/.claude/projects/ is NOT
# (both `/` and `.` collapse to `-`, so it cannot be reversed deterministically).
stale_count=$(claude project purge --dry-run --all 2>/dev/null \
  | grep -oE 'projects\["[^"]+"\]' \
  | sed -E 's/^projects\["//; s/"\]$//' \
  | while IFS= read -r p; do
      [ -n "$p" ] && [ ! -d "$p" ] && echo "$p"
    done | wc -l)

# If > 0, surface the hint in the dream summary (never auto-execute)
if [ "$stale_count" -gt 0 ]; then
  echo "ℹ $stale_count stale project state entries detected."
  echo "   Preview cleanup with: claude project purge --dry-run --all"
fi

Strict rules: always --dry-run, never --yes. Users who moved (not deleted) a project need to keep the directory; the purge is irreversible. Surface the suggestion, let the user decide.

Why parse claude project purge --dry-run --all instead of ~/.claude/projects/: the directory naming under ~/.claude/projects/ is a lossy collapse of the original path (/ and . both become -). A naive sed 's|-|/|g' decode misidentifies any path containing - (e.g. my-project/my/project). The CLI's dry-run output reads canonical paths from ~/.claude.json and is the only reliable source.


When NOT to Use

  • To store new decisions -- use /ork:remember
  • To search past decisions -- use /ork:memory search
  • To load context at session start -- use /ork:memory load
  • After fewer than 5 sessions -- memory files are unlikely to have accumulated enough staleness

  • ork:remember -- Store decisions and patterns (write-side)
  • ork:memory -- Search, load, sync, visualize (read-side)
Edit on GitHub

Last updated on