| name | memory-tiering |
| description | Multi-tiered memory management (HOT/WARM/COLD) for context compaction. Invoke ONLY for explicit
compaction events: post-`/compact` cleanup, MEMORY.md tier promotion, archive batch, or "trim my context".
NOT for general recall (use deep-recall) or routine memory writes (use storage-router).
Triggers: "compact memory", "promote to durable", "archive old context", "tier this". |
Memory Tiering Skill 🧠⚖️
2026.4.10 Update: OpenClaw now has two native memory systems — Active Memory (runs before every reply) and Dreaming (nightly consolidation at 3 AM IL). This skill covers what they DON'T handle — see section below.
What Native Systems Now Cover (don't duplicate)
| Task | Who does it |
|---|
| Pull relevant context before each reply | Active Memory plugin (automatic) |
| Promote strong signals to MEMORY.md nightly | Dreaming / memory-core (automatic) |
| HOT.md pattern promotion after 2x mistakes | self-learning skill |
What This Skill Still Handles
- Manual pruning when MEMORY.md grows >200 lines
- Archiving old
memory/daily/YYYY-MM-DD.md files (30-day retention)
- Force-promoting critical owner corrections immediately (don't wait for Dreaming)
- Graduation gate — reviewing and filtering dream promotions before they land in MEMORY.md
- Post-compaction reorganization
- Enforcing store boundaries: daily notes = raw-first log,
MEMORY.md = durable rules only, project docs = project-scoped
The Three Tiers (for manual ops)
- 🔥 HOT (
memory/hot/HOT_MEMORY.md) — current session, active tasks
- 🌡️ WARM (
memory/warm/WARM_MEMORY.md) — stable preferences, configs
- ❄️ COLD (
MEMORY.md) — long-term, distilled, curated
Workflow: Organize-Memory (Manual / Post-Compaction)
Step 1: Check native systems first
openclaw memory status --deep
/dreaming status
Step 2: Ingest & Audit
- Read MEMORY.md + last 7
memory/daily/YYYY-MM-DD.md files
- Identify Dead Context: completed tasks, resolved issues, stale facts
Step 3: Prune & Redistribute
- Remove stale COLD entries (if Dreaming already promoted better versions)
- Force-add critical owner corrections → MEMORY.md immediately (don't wait for Dreaming)
- Archive daily notes older than 30 days →
memory/archive/YYYY-MM/
Step 4: Verify
- MEMORY.md should be <200 lines after cleanup
- Check
DREAMS.md — are Dreaming's promotions accurate? Prune bad ones.
Progressive Context Compaction (inspired by Claude Code harness patterns)
Long sessions degrade quality as context fills. Apply progressive compression by conversation age:
Compression Layers (oldest → newest)
| Layer | Age | Strategy | Detail Level |
|---|
| HISTORY_SNIP | >50 turns | Drop entirely or keep 1-line summary | ~5% |
| Microcompact | 30-50 turns | Aggressive: decisions + outcomes only | ~15% |
| CONTEXT_COLLAPSE | 15-30 turns | Medium: key exchanges, skip tool noise | ~40% |
| Full Detail | <15 turns | No compression | 100% |
When to Apply
- Session exceeds 30 turns
- Context window pressure detected (tool responses getting truncated)
- After any
/compact command
How to Apply (Manual)
- Identify turn count in current session
- For turns older than 30: summarize into a single "Session context so far" block
- For turns 15-30: keep decisions and outcomes, drop tool output and exploration
- Keep last 15 turns at full detail
- Always preserve: owner corrections, final decisions, error causes
What Never Gets Compressed
- Owner corrections and preferences
- Permission decisions (approved/denied actions)
- Error root causes and fixes applied
- Active task state and pending items
Gap vs. Claude Code
Claude Code does this in the harness layer (code, not prompt). We currently rely on manual /compact and prompt-level instructions. Future improvement: move compaction logic into OpenClaw's session management layer so it runs automatically without consuming agent tokens.
Usage Trigger
- Trigger manually: "Run memory tiering" or when MEMORY.md >200 lines
- Trigger automatically after any
/compact command
Dreaming Integration (OpenClaw 2026.4.9+)
Dreaming is already enabled (memory-core plugin, 0 3 * * * IL timezone).
What Dreaming does automatically:
- Light phase: ingests daily notes + session transcripts
- Deep phase: scores & promotes strong signals → MEMORY.md (weighted: relevance 0.30, frequency 0.24, recency 0.15)
- REM phase: extracts themes and patterns
Manual CLI for inspection/intervention:
openclaw memory status --deep
openclaw memory promote
openclaw memory promote --apply
openclaw memory promote-explain "term"
/dreaming status
What still requires manual action:
- Owner corrections → MEMORY.md immediately (don't wait for Dreaming)
- Critical session-startup rules → MEMORY.md manually
- Pruning bad/stale Dreaming promotions → manual cleanup
- MEMORY.md growing >200 lines → prune manually
Graduation Gate (inspired by agentic-stack)
Dreaming stages candidates. Nothing graduates to MEMORY.md without passing this gate:
Minimum Requirements
- Score >= 0.70 (weighted relevance + frequency + recency)
- Recalls >= 2 (the signal was retrieved and used at least twice)
- Status = staged (raw candidates with status=staged only)
- Content is a rule, preference, or durable fact — not a raw conversation fragment, not a debug log, not a confidence=0.00 dream corpus entry
Rejection Criteria (auto-reject)
- Confidence = 0.00 or status != staged
- Content is a raw session transcript or chat log (contains
Candidate: User: or Candidate: Assistant: or evidence: memory/.dreams/)
- Duplicate of an existing MEMORY.md entry (same semantic content)
- Content is ephemeral (specific timestamps, one-off events, resolved issues)
Review Process
- Run
openclaw memory promote to list candidates
- For each candidate, check against minimum requirements and rejection criteria
- Accept only with a one-line rationale: why this is durable and useful
- Reject with a one-line reason: why this doesn't belong
- Rewrite accepted content into clean, concise rule format before adding to MEMORY.md
- Never paste raw dream output directly into MEMORY.md
Post-Review Cleanup
- After review, clear processed candidates from DREAMS.md staging area
- Log review outcome in
memory/daily/YYYY-MM-DD.md: [HH:MM] Dream review: accepted N, rejected M
Safety Rules
- Content changes (MEMORY.md): require explicit review — never auto-apply
- Archiving old files: safe to run automatically
trash > rm always
Retention Policy
- Daily notes: keep 30 days → archive to
memory/archive/YYYY-MM/
- Archive: keep 90 days → delete
- MEMORY.md: prune if >200 lines
Health Indicators
- ✅ Healthy: MEMORY.md <200 lines, DREAMS.md updated nightly, daily notes exist
- ⚠️ Warning: MEMORY.md 200–300 lines, Dreaming didn't run in 48h
- ❌ Critical: MEMORY.md >300 lines, no Dreaming output in 7 days
