Memory Health Monitor

Real-time agent memory health monitoring, compaction tracking, and auto-repair for OpenClaw workspaces.

Quick Start

# Full health dashboard
python3 scripts/memory-health-monitor.py status

# Monitor context window fill rate
python3 scripts/memory-health-monitor.py context

# Track compaction events and data loss
python3 scripts/memory-health-monitor.py compaction

# Auto-backup memory files
python3 scripts/memory-health-monitor.py backup

# Auto-repair corrupted memory files
python3 scripts/memory-health-monitor.py repair

# Continuous monitoring mode (writes alerts to stdout)
python3 scripts/memory-health-monitor.py watch --interval 60

Commands

`status` — Full Health Dashboard

Displays composite health score (0-100) covering:

• Memory file integrity (MEMORY.md, daily files, HEARTBEAT.md)
• Context window estimated fill rate
• Last compaction timestamp and data loss estimate
• File size trends (growing/stable/shrinking)
• Backup freshness

`context` — Context Window Monitor

Estimates current context window usage by analyzing:

• Session file sizes in .openclaw/
• Active memory files loaded into context
• Alerts at configurable thresholds (default: 70%/85%/95%)

`compaction` — Compaction Tracker

Tracks memory compaction events by:

• Snapshotting memory file checksums and line counts
• Comparing pre/post compaction states
• Estimating data loss percentage
• Logging compaction history to memory/compaction-log.json

`backup` — Auto-Backup

Creates timestamped backups of all memory files:

• Backs up to memory/backups/YYYY-MM-DD-HHMMSS/
• Keeps last N backups (configurable, default 10)
• Runs automatically before repair operations

`repair` — Auto-Repair

Detects and fixes common memory issues:

• Empty or truncated MEMORY.md → restore from latest backup
• Missing daily memory files → create stub with date header
• Corrupted JSON in heartbeat-state.json → reset to defaults
• Orphaned backup files → cleanup old backups
• Broken markdown structure → fix headers and formatting

`watch` — Continuous Monitoring

Runs in background, periodically checking health and writing alerts.

• --interval N — check every N seconds (default: 60)
• --threshold WARN — alert level: info/warn/critical (default: warn)
• Outputs JSON events to stdout for pipeline integration

Parameters

| Parameter | Default | Description |

|-----------|---------|-------------|

| --workspace | ~/.openclaw/workspace | Workspace root path |

| --warn-at | 70 | Context fill % to warn |

| --critical-at | 85 | Context fill % critical alert |

| --emergency-at | 95 | Context fill % emergency |

| --max-backups | 10 | Number of backups to retain |

| --format | text | Output format: text, json, markdown |

| --interval | 60 | Watch mode check interval (seconds) |

| --quiet | false | Suppress non-critical output |

Integration with OpenClaw

Add to HEARTBEAT.md for periodic monitoring:

- [ ] Run memory-health-monitor status (every 4 heartbeats)

Or set up as a cron job:

Schedule: every 2 hours
Command: python3 skills/memory-health-monitor/scripts/memory-health-monitor.py status --format json --quiet