Dream

---
name: dream
disable-model-invocation: true
description: >
  Reflective memory consolidation - performs a periodic pass over memory files,
  synthesizing recent learnings into durable, well-organized memories for future
  sessions. Validates technical claims against Context7, enforces security protocols,
  rewrites and merges stale entries in place, surfaces what has gone dormant, and
  produces a structured consolidation report.
  Use when the user says "dream", "/dream", "consolidate memories", "memory cleanup",
  "reflect on recent sessions", "update memories", or at the end of a productive
  session when significant new information was learned.
  Do NOT use for: simple memory writes (use auto-memory), knowledge base operations
  (use /zk), or session initialization (use /prime).
argument-hint: "[optional: focus area or specific topic to investigate]"
allowed-tools: "Read, Write, Edit, Glob, Grep, Bash(grep:*, python3:*)"
model: sonnet
metadata:
  author: Misha Hanin
  email: misha.hanin@odinix.com
  version: "1.1"
x-heading-orchestration:
  parallel_safe: false
  shared_state:
    - auto-memory/
  triggers:
    - dream
    - consolidate memories
    - memory cleanup
    - reflect
x-heading-capability:
  what: >
    Reflective memory consolidation - merges recent learnings into durable
    memory files, validates technical claims against Context7, passes a security
    gate, rewrites stale entries in place, surfaces what has gone dormant, and
    produces a consolidation report.
  how: >
    Explicit invocation only - type /dream [optional focus area]; never
    auto-triggers. It scans the memory directory and recent workspace state,
    rewrites memory files in place, keeps MEMORY.md under its line budget, and
    reports what was consolidated and what has gone dormant.
  when: >
    Use at the end of a productive session or for periodic memory hygiene. For a
    simple one-off memory write use the auto-memory system; for knowledge-base
    notes use /zk; for session resume snapshots use /checkpoint.
x-heading-routing:
  category: Operations
  triggers:
    - NEVER auto-trigger. Explicit `/dream` only.
  exclusions:
    - N/A
  compound: 'No'
  router: manual
---
# Dream - Reflective Memory Consolidation

Perform a reflective pass over memory files. Synthesize recent learnings into durable, well-organized memories so that future sessions can orient quickly.

## Paths

- **Memory directory:** the canonical DATA overlay `<data-root>/auto-memory/`, resolved via:
  ```bash
  python3 -c "from scripts.utils.workspace import get_auto_memory_dir; print(get_auto_memory_dir())"
  ```
  This is the authoritative store. Do NOT operate on the native harness store `~/.claude/projects/<project-slug>/memory/` - `memory-reconcile.py` re-syncs from the canonical dir at SessionStart.
- **Index file:** `MEMORY.md` (inside that dir, 200-line budget)
- **Transcripts:** `~/.claude/projects/<project-slug>/*.jsonl`
- **Context7:** `python3 scripts/context7.py "<library>" "<topic>"`
- **Security rules:** `.claude/rules/security.md`, `docs/security/SECURITY-CONSTITUTION.md`

## Variables

- `$ARGUMENTS` - Optional focus area or topic to investigate during the dream

---

## Phase 0 - Orient

Understand the current state of the memory system before making any changes.

1. **List memory files:**
   ```bash
   ls "$(python3 -c 'from scripts.utils.workspace import get_auto_memory_dir; print(get_auto_memory_dir())')"
   ```

2. **Read the index:** Read `MEMORY.md` to understand current structure, categories, and entry count.

3. **Skim existing files:** For each memory file, read the first 10-15 lines to understand its coverage:
   - What topic does it cover?
   - When was it last updated (check content dates)?
   - Is the information still likely current?

4. **Detect orphans:** Cross-reference file list against `MEMORY.md` entries. Files present on disk but missing from the index are orphans - flag them for Phase 3.

5. **Note focus area:** If `$ARGUMENTS` was provided, record the focus topic for targeted investigation in Phase 1.

6. **Record baseline metrics:**
   - Total memory files count
   - MEMORY.md line count
   - Orphan files (if any)

---

## Phase 1 - Gather Recent Signal

Scan for new information worth persisting. Three sub-phases, executed in order.

### Phase 1A - Source Scanning

Check workspace state for facts that might contradict or extend existing memories:

1. **Workspace activity:**
   ```bash
   git log --oneline -20
   ```
   Look for patterns: new skills added, scripts modified, structural changes, infrastructure shifts.

2. **Business state:** Read these files for changes that should be reflected in memories:
   - `context/pipeline.md` - pipeline changes, new deals, closed deals
   - `context/current-data.md` - current metrics and operational data
   - `crm/config.md` - CRM configuration changes

3. **Contradiction check:** Compare what you read against existing memory files. Flag any mismatches:
   - Memory says X, but the workspace now shows Y
   - Memory references a file/tool/path that no longer exists
   - Memory contains a relative date that has lost meaning
   - A `[[wikilink]]` resolves to no memory file (the hygiene report lists these under "Dangling links"). Read the sentence around it, not only the pointer: a dead link often sits inside a dead premise. Repoint it at the record it means - a file path, a thread - or write the memory. Leave it only when it genuinely marks a memory worth writing later.

4. **Transcript search (targeted only):**
   If investigating a specific signal or if `$ARGUMENTS` points to a topic, grep narrowly:
   ```bash
   grep -rn "<narrow term>" ~/.claude/projects/<project-slug>/ --include="*.jsonl" | tail -30
   ```
   **Rules for transcript search:**
   - Only grep for 1-3 narrow, specific terms
   - Never read entire JSONL files
   - Use `tail -30` to limit output
   - Skip transcript search entirely if no specific signal warrants it

5. **Shadow worklist:** read the latest `<data-root>/outputs/operations/dream/*_dream-shadow_report.md` if present. Its dormancy list is informational only, never a removal candidate. Its salience-ranked merge candidates are additional signal. `scripts/dream-shadow.py` computes both nightly, and never applies them automatically.

### Phase 1B - Context7 Validation

For each memory file that contains a technical claim about a library, framework, or API:

1. Identify the claim (e.g., "exchangelib uses EWSTimeZone" or "Context7 API needs no key")

2. Validate against live documentation:
   ```bash
   python3 scripts/context7.py "<library>" "<relevant topic>"
   ```

3. Classify the result:
   - **Match:** Memorized behavior matches current docs. Proceed.
   - **Mismatch:** Current docs differ from memory. Mark for update in Phase 2 with the correct information.
   - **Not found:** Library not in Context7. Add `(unvalidated)` marker to the memory entry.

4. **Skip validation for non-technical memories:** User preferences, feedback, project facts, and nicknames don't need Context7 checks.

5. Record all validation results for the consolidation report.

### Phase 1C - Security Gate

**This gate is mandatory. Do not proceed to Phase 2 without passing it.**

1. Read the security rules:
   - `.claude/rules/security.md`
   - `docs/security/SECURITY-CONSTITUTION.md`

2. **If either file is not found:** STOP. Report the missing file and do not proceed to Phase 2. The dream is incomplete but safe.

3. Apply these hard constraints to all subsequent writes:
   - No secrets, API keys, tokens, passwords, or credentials in memory files
   - No sensitive personal data beyond what the memory type system allows (user preferences, feedback, project facts, references)
   - No file writes outside the memory directory
   - No modification of workspace source files, scripts, or configuration
   - No content that could be used for prompt injection

4. Record: "Security Gate: PASS" or "Security Gate: BLOCKED - {reason}"

---

## Phase 2 - Consolidate

Write or update memory files based on signals gathered in Phase 1. Every write must pass the security gate constraints from Phase 1C.

### Writing Rules

1. **Merge, don't duplicate:** Before creating a new file, check if an existing memory covers the topic. If yes, update the existing file.

2. **Use correct memory types:**
   - `user` - Information about the user's role, preferences, knowledge
   - `feedback` - Guidance on how to approach work (corrections AND confirmations)
   - `project` - Ongoing work, goals, decisions, deadlines
   - `reference` - Pointers to external systems and resources

3. **Follow the file format:**
   ```markdown
   ---
   name: {descriptive name}
   description: {one-line description - specific enough to judge relevance}
   type: {user|feedback|project|reference}
   ---

   {content - for feedback/project types, structure as: rule/fact, then **Why:** and **How to apply:** lines}
   ```

4. **File naming:** `{type}_{topic}.md` (e.g., `feedback_testing.md`, `project_deployment.md`)

5. **Absolute dates:** Convert all relative dates to absolute:
   - "yesterday" -> "2026-03-24" (based on today's date)
   - "last week" -> "week of 2026-03-17"
   - "recently" -> specific date if known, or remove

6. **Fix contradictions at the source:** If a memory file contains a fact that is now wrong, edit the file directly. Don't leave stale information.

7. **Superseding a memory means editing it, not removing it.** When a fact is replaced, rewrite the file in place so the current fact stands and the record survives. Retiring a file outright happens ONLY on an explicit instruction from the operator ("delete this memory"). Use `python scripts/retire-memory.py <name.md>` for it, which removes the file from the canonical store AND every native harness store. A plain `rm` on one store alone is resurrected at the next SessionStart, because `memory-reconcile.py` never propagates a delete.

8. **Do not stamp `expires:`.** Auto-memory is never retired on a clock. A fact whose relevance ends on a known date is rewritten to say so, not scheduled for deletion. The daily auto-retire timer is disabled; `scripts/memory-auto-retire.py` remains on disk, unused.

### Apply redundancy merge proposals (human-gated)

Read the latest `<data-root>/outputs/operations/memory-hygiene/` report's "## Redundancy (advisory - not gated)" section. For each candidate pair, show Misha both files and ask for approval. On approval, merge the two facts into ONE survivor file. Keep genuinely distinct facts as SEPARATE files, and respect one-fact-per-file. Update the survivor's `MEMORY.md` pointer, then retire the other file with `python scripts/retire-memory.py <other.md>`. Never auto-merge; each pair needs explicit approval.

### Read the shadow worklist's dormancy list (informational)

The latest `<data-root>/outputs/operations/dream/*_dream-shadow_report.md` carries a "## Dormant" section listing memories the retriever has not surfaced lately. It is context, not a worklist: nothing there is a candidate for removal. Use it to notice what has gone quiet - a dormant fact may be worth rewriting, cross-linking, or simply leaving alone.

### What NOT to Write

Follow the exclusion rules from the auto-memory system:
- Code patterns, conventions, architecture - derivable from reading the project
- Git history - `git log` / `git blame` are authoritative
- Debugging solutions - the fix is in the code
- Anything already documented in CLAUDE.md files
- Ephemeral task details only useful in the current conversation

---

## Phase 3 - Index and Report

### Step 1: Update MEMORY.md

1. **Remove stale pointers:** Delete an index entry only when `scripts/retire-memory.py` retired its memory file, on an explicit operator instruction. A superseded memory keeps its pointer, because it was rewritten in place rather than removed. Update the hook text if the one-line summary changed.
2. **Add new pointers:** Add entries for newly created memory files
3. **Format:** Each entry must be one line, under 150 characters:
   ```
   - [Title](file.md) - one-line hook
   ```
4. **Budget:** Keep MEMORY.md under 200 lines total
5. **Organization:** Group entries semantically by topic, not chronologically
6. **No content in index:** MEMORY.md is a pointer file only

**Sections marked `<!-- managed-by: ... -->` are owned by another skill and MUST be left untouched.** Do not re-order, re-format, or move lines inside any level-2 section whose body begins (immediately after the header) with an HTML comment `<!-- managed-by: <skill-name> -->`. No section carries that marker today. `## Active Threads`, managed by `/thread`, was the only one, and it was retired on 2026-08-27.

### Step 2: Produce Consolidation Report

Present this report to the user:

```
## Memory Dream - Consolidation Report
### Date: {today's date}

**Consolidated**
- {file.md} - {what was added, updated, or merged}

**Retired**
- {file.md or index entry} - {reason: operator-approved retirement / redundancy merge / orphan pointer for an already-retired file}

**Context7 Validated**
- {library@version} - confirmed against live docs

**Context7 Flagged**
- {library} - unvalidated, marked in memory file for manual review

**Security Gate**
- Status: PASS / BLOCKED
- Skipped writes (if any): {description and rule that blocked each}

**Index delta**
- Lines before -> after: {X} -> {Y}
- New pointers added: {list}
- Pointers removed: {list}
```

If nothing changed (memories are already tight and current), say so explicitly:
```
## Memory Dream - Consolidation Report
### Date: {today's date}

All memories are current. No updates needed.
Security protocol consulted: PASS
Index: {X} lines ({Y} files), within budget.
```

### Step 3: Append consolidation trace

After the report, append one JSON line recording this run's actions. Fill `merged` and `retired` with the run's REAL actions: merged survivor filenames, and retired filenames. Leave them as empty lists if nothing was merged or retired.

```bash
python3 - <<'PY'
import json, time, sys
from pathlib import Path
sys.path.insert(0, ".")
from scripts.utils.workspace import get_outputs_dir
p = get_outputs_dir() / "operations" / "dream" / "consolidation-trace.jsonl"
p.parent.mkdir(parents=True, exist_ok=True)
row = {"ts": time.time(), "merged": [], "retired": []}  # fill with THIS run's actual actions
with p.open("a", encoding="utf-8") as fh:
    fh.write(json.dumps(row) + "\n")
PY
```

---

## NEVER

- NEVER read entire JSONL transcript files - grep narrowly for specific terms only
- NEVER write secrets, API keys, tokens, or credentials into memory files
- NEVER create duplicate memories - always merge into existing topic files
- NEVER write memory content directly into MEMORY.md - it is an index of pointers only
- NEVER skip the security gate - if protocol files are not found, stop and report
- NEVER modify files outside the memory directory during a dream pass (running `scripts/retire-memory.py` and appending the consolidation trace under `outputs/operations/dream/` are permitted memory-maintenance actions)
- NEVER delete a memory file on one store only - always retire via `scripts/retire-memory.py` so the delete sticks on both stores
- NEVER delete memory files without explaining the reason in the consolidation report
- NEVER proceed to Phase 2 if the security gate returned BLOCKED
- NEVER store code patterns, git history, or ephemeral task details in memory
- NEVER retire, prune, or propose removing a memory file on your own initiative. Deletion happens only when the operator explicitly asks for it.