name: rem-sleep
description: Memory consolidation and defragmentation for long-term memory maintenance. Use when asked to consolidate memories, defrag memory, run REM sleep, clean up memory files, or process session logs into durable memory. Also use periodically during heartbeats for memory maintenance.

REM Sleep - Memory Consolidation

Like biological REM sleep, this skill processes raw experience (session logs) into consolidated long-term memory.

Overview

LLM agents accumulate raw session logs but struggle with long-term memory. This skill provides a workflow for:
- Consolidating significant events from session logs into durable memory
- Defragmenting memory files to remove stale/redundant information

Requirements

• Repo Prompt (macOS) with MCP enabled
• Moltbot/Clawdbot with session logging enabled
• A workspace with MEMORY.md and memory/ directory

Modes

1. Consolidate (--mode consolidate)

Process recent session logs → extract significant events → update MEMORY.md

2. Defrag (--mode defrag)

Review MEMORY.md → remove stale/outdated entries → merge duplicates → compress

3. Full (--mode full)

Run both consolidate then defrag.

Consolidation Workflow

Step 1: Gather Recent Sessions

Use Repo Prompt to search recent session activity:

# List sessions to find recent ones
rp -e 'tree ~/.moltbot/agents/main/sessions'

# Search for significant patterns
rp -e 'search "decision" --context-lines 2'
rp -e 'search "learned" --context-lines 2'
rp -e 'search "important" --context-lines 2'
rp -e 'search "remember" --context-lines 2'
rp -e 'search "TODO" --context-lines 1'
rp -e 'search "preference" --context-lines 2'

Or use the helper script:

./scripts/gather-sessions.sh [days_back]

Step 2: Identify Consolidation Candidates

From search results, look for:
- Decisions made — choices, preferences, conclusions
- Facts learned — new info about people, projects, systems
- Lessons — things that worked/didn't, mistakes to avoid
- TODOs/commitments — things promised or planned
- Relationship context — interactions with people, their preferences

Step 3: Update Memory Files

1. Daily file (memory/YYYY-MM-DD.md): Raw events, specific details
2. MEMORY.md: Distilled, durable knowledge worth keeping long-term

Consolidation prompt:

Review these session excerpts. Extract significant information that should be remembered long-term. Focus on: decisions, facts about people/projects, lessons learned, and preferences. Format as bullet points suitable for MEMORY.md.

Step 4: Update Daily Memory

If today's memory/YYYY-MM-DD.md doesn't exist, create it with session highlights.

Defrag Workflow

Step 1: Analyze Current Memory

Read MEMORY.md and identify:
- Stale entries — outdated info, completed TODOs, old dates
- Duplicates — same info repeated in different sections
- Inconsistencies — conflicting information
- Bloat — overly verbose entries that could be compressed

Step 2: Categorize Issues

STALE: [entry] — reason it's outdated
DUPLICATE: [entry A] ≈ [entry B]
INCONSISTENT: [entry A] vs [entry B]
BLOAT: [verbose entry] → [compressed version]

Step 3: Apply Fixes

• Remove stale entries (or move to an archive section if uncertain)
• Merge duplicates into single authoritative entry
• Resolve inconsistencies (check session logs if needed)
• Compress verbose entries

Step 4: Reorganize

Ensure MEMORY.md has logical sections:
- About [User]
- My Setup
- Projects
- People
- Preferences
- Lessons Learned

Scheduling

Recommended cadence:
- Consolidate: Every few days, or after busy periods
- Defrag: Weekly or bi-weekly
- Full: Monthly deep clean

Can be triggered:
- Manually: "Run REM sleep" / "Consolidate my memories"
- Heartbeat: Add to HEARTBEAT.md for periodic runs
- Cron: Schedule isolated job for off-hours

Quick Reference

# Gather session data (last 3 days default)
./scripts/gather-sessions.sh

# Gather last 7 days
./scripts/gather-sessions.sh 7

# Manual searches
rp -e 'search "PATTERN" --context-lines 2'

Notes

• Session logs are JSONL format — content is there but wrapped in JSON
• Repo Prompt's builder can timeout on large queries — prefer manual search
• When uncertain if something is stale, keep it (conservative approach)
• MEMORY.md is loaded in main sessions — keep it focused and relevant

Credits

Inspired by a community comment: "We need a memory de-fragger for reducing latency of this RAG. We need LLM REM sleep."

Built for Moltbot agents using Repo Prompt for context engineering.