memory-tiering
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
SKILL.mdskills/memory-tiering/SKILL.md
GitHubMemory 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.mdfiles (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 # see what Dreaming already promoted
/dreaming status # check last run
Step 2: Ingest & Audit
- Read MEMORY.md + last 7
memory/daily/YYYY-MM-DD.mdfiles - 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
/compactcommand
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
/compactcommand
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:orCandidate: Assistant:orevidence: 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 promoteto 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>rmalways
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