memory-tiering

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)

1. 🔥 HOT (memory/hot/HOT_MEMORY.md) — current session, active tasks
2. 🌡️ WARM (memory/warm/WARM_MEMORY.md) — stable preferences, configs
3. ❄️ COLD (MEMORY.md) — long-term, distilled, curated

Workflow: Organize-Memory (Manual / Post-Compaction)

Step 1: Check native systems first

openclaw memory status --deep   # see what Dreaming already promoted
/dreaming status                  # check last run

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)

1. Identify turn count in current session
2. For turns older than 30: summarize into a single "Session context so far" block
3. For turns 15-30: keep decisions and outcomes, drop tool output and exploration
4. Keep last 15 turns at full detail
5. 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          # what's queued for promotion
openclaw memory promote                # preview what would promote
openclaw memory promote --apply        # force apply now
openclaw memory promote-explain "term" # why something would/wouldn't promote
/dreaming status                        # last run summary

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

1. Run openclaw memory promote to list candidates
2. For each candidate, check against minimum requirements and rejection criteria
3. Accept only with a one-line rationale: why this is durable and useful
4. Reject with a one-line reason: why this doesn't belong
5. Rewrite accepted content into clean, concise rule format before adding to MEMORY.md
6. 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