consolidate-memory

name

consolidate-memory

description

Consolidate, prune, and reorganize the memory system — like a dream cycle. Use when user says "dream", "consolidate memory", "clean up memory", "prune memory", "organize memory", or "tidy up memory". Also trigger when the user complains about stale context, contradictory information, or when memory files feel cluttered. If the agentSpawn hook reports that consolidation is overdue, and the user acknowledges it, use this skill. Think of this as REM sleep for the memory system — it strengthens what matters and discards what doesn't. Even a casual "my memory is getting messy" should trigger this.

Consolidate Memory Skill

Purpose

Review all memory files, prune stale entries, resolve contradictions, deduplicate, convert relative dates to absolute, and reorganize — keeping the memory system clean and useful over time.

Without periodic consolidation, memory files accumulate noise: contradictory entries pile up, relative dates like "yesterday" lose meaning, and duplicate information spreads across files. This skill is the cleanup cycle that prevents memory from degrading.

Memory System Location

<MEMORY_PATH>

Process

Phase 1: Orient

Read the full memory directory to understand current state. This prevents creating duplicates or missing context during consolidation.

1. Read SOUL.md — agent identity and principles
2. Read AGENT.md — behavioral rules and communication style
3. Read MEMORY.md — the index and recent context
4. Read USER.md — user profile
5. List and skim all files in Personal/, Personal/Projects/, People/, Knowledge/, Decisions/, Customers/, Reference/, Technical/, Work/
6. Note file sizes, last-updated dates, and cross-references

Phase 2: Identify Issues

Scan for these problems across all files:

• Stale entries — references to projects marked complete long ago, people no longer relevant, tools no longer used. A project completed 6 months ago with no recent references is a candidate for archival.
• Contradictions — conflicting facts across files. For example, one file says "uses Express" while another says "migrated to Fastify." The newer entry is usually correct.
• Relative dates — "yesterday", "last week", "recently" that have lost meaning. These are fine when first written but become confusing after a few days. Convert them using the current date and the file's context.
• Duplicates — same information repeated across multiple files. Common when the user mentions the same thing in different conversations.
• Orphaned links — [[links]] pointing to files that don't exist.
• Oversized files — any single file over 1000 lines should be split or trimmed. Large files are harder to search and slower to load.
• Misplaced content — files or folders outside the expected structure. This can happen after upgrades (e.g., a top-level Projects/ from an older version) or when files get dropped in the wrong place. The expected structure is:
  • Core files in root: SOUL.md, AGENT.md, USER.md, MEMORY.md, notes.md
  • Category folders: Customers/, Personal/, Personal/Projects/, People/, Knowledge/, Decisions/, Reference/, Technical/, Work/, .archive/
  • Anything else in the root or in unexpected locations is a candidate for relocation.

Phase 3: Consolidate

Fix each issue at the source:

• Preserve before pruning — before removing any stale entry, verify the information exists in the appropriate category sub-folder (Personal/, Personal/Projects/, People/, Knowledge/, Decisions/, Customers/, Reference/, Technical/, Work/). If it doesn't, create or update the corresponding file there first. For example, a stale project entry in MEMORY.md should have a corresponding file under Personal/Projects/ before it's removed from the index. Customer-related info goes under Customers/<Company>/, technical notes under Technical/, etc. Only after confirming the detail is preserved in the right place should you prune it from the source.

• Prune stale entries — remove them entirely. If an entire file becomes empty after pruning, delete the file and remove its link from the parent README.md.

• Resolve contradictions — newer information wins. When genuinely uncertain, keep both with a brief note: <!-- Conflict: verify with user whether Express or Fastify is current -->. Contradictions aren't just between files — they also happen within a single file. A decision log might say "Chose Express" on one date and "Switched to Fastify" on a later date. When a later entry supersedes an earlier one, annotate the original so readers understand the timeline:

  Before:

  - 2026-03-20: Chose Express as the framework
  - 2026-03-26: Switched to Fastify for better performance
  

  After:

  - 2026-03-20: Chose Express as the framework (superseded — migrated to Fastify 2026-03-26)
  - 2026-03-26: Switched to Fastify for better performance
  

  This preserves the decision history (useful context for understanding why things changed) while making it immediately clear what's current. Don't just delete the old entry — the rationale behind the original choice can still be valuable.

• Convert dates — replace relative with absolute.

  Before: - yesterday: Decided to use Fastify After: - 2026-03-26: Decided to use Fastify

• Deduplicate — merge overlapping entries into the most appropriate file. Keep the richer version, discard the thinner one.

• Fix links — remove broken [[links]], add missing ones where files clearly reference each other.

• Split large files — if a category README.md has grown too large, extract topics into dedicated files (e.g., Customers/Acme/Redesign.md) and leave a link in the README.

• Relocate misplaced content — move files and folders into the correct location based on their content:

  • A top-level Projects/ folder (from older versions) → move contents into Personal/Projects/
  • Customer-related files in Projects/ → move to Customers/<Company>/
  • Random markdown files in the root → read them, categorize, and move to the right folder
  • After relocating, update any [[links]] that referenced the old path
  • Tell the user what was moved and why in the Phase 6 report

Phase 4: Prune and Index

Update MEMORY.md to reflect the current state:

1. Keep it under 1000 lines — it's an index and recent-context log, not a dump. The agentSpawn hook loads this file into context at startup, so keeping it lean means faster, cleaner session starts.
2. Remove pointers to deleted files.
3. Add pointers to new files created during consolidation.
4. Archive "Recent Context" entries older than 30 days to .archive/YYYY-MM-DD-consolidation.md. These aren't lost — they're still searchable via the knowledge base — but they don't need to take up space in the active index.

Phase 5: Re-index and Stamp

After all changes:

1. Refresh the knowledge base:

knowledge update --path "<MEMORY_PATH>" --name "My Memory"

2. Update the dream timestamp so hooks know when consolidation last ran:

date +%s > "<MEMORY_PATH>/.last-dream"

3. Reset the session counter:

echo "0" > "<MEMORY_PATH>/.session-count"

Phase 6: Report

Tell the user what changed. Be specific and brief:

• Files pruned or deleted
• Contradictions resolved
• Entries deduplicated
• Dates converted
• Size before/after for MEMORY.md

Example report:

Consolidated memory:
- Pruned 3 stale project entries from Personal/Projects/README.md
- Resolved Express/Fastify contradiction in Knowledge/README.md (kept Fastify)
- Converted 7 relative dates to absolute
- Deduplicated 2 entries between MEMORY.md and Decisions/README.md
- Relocated Projects/Acme-Redesign.md → Customers/Acme/Redesign.md
- MEMORY.md: 187 → 142 lines

Guidelines

• Be surgical — don't rewrite files that don't need changes. If a file is clean, leave it alone.
• When unsure if something is stale, leave it and add a comment noting the uncertainty. It's better to ask the user than to delete something they still care about.
• Preserve the user's voice — don't rephrase their notes into formal language. If they wrote "this API is janky," keep it that way.
• Timestamp the consolidation: add - YYYY-MM-DD: Memory consolidated to MEMORY.md under Recent Context.