Memory Health Check — OpenClaw Diagnostic Script

What It Does

Runs a 5-point health check on your OpenClaw agent in about 10 seconds, then automatically fixes what is safe to fix and tells you clearly what it did vs what needs your input.

1. Services — failed systemd (Linux) or launchd (macOS) services
2. Disk — root filesystem usage, warns at 80%+
3. Memory files — last-write age for MEMORY.md, active-context.md, today and yesterday daily logs
4. Memory index — real indexed doc count direct from SQLite (bypasses the misleading openclaw memory status display)
5. Today's activity — section count and last entry written

The Problem It Solves

openclaw memory status can show Indexed: 0/1 files · 0 chunks even when your agent has 99+ docs and 1,300+ vectors properly indexed. This skill reads the SQLite DB directly and tells you the truth.

It also catches the second-most-common memory failure: daily logs written to the wrong path, which makes memory_search return nothing even though the files exist.

Auto-Fix vs Report

After running the check, the agent applies a clear decision tree:

Auto-fixes silently (then reports what it did):

• QMD index conflict → runs openclaw memory index --force, confirms new doc count
• Empty index → same fix
• Missing daily log → creates a stub file so future writes work
• Daily log in wrong path → moves it to the correct location

Reports and advises (cannot self-fix):

• Service failures → tells you the exact systemctl status command to run
• Disk above 80% → tells you how to find what's taking up space
• Stale MEMORY.md → offers to write a memory update right now
• Stale active-context.md → offers to update it with current project state

Never does without permission:

• Restarting services
• Deleting files
• Modifying config or credentials

How to Use It

On-demand: Ask your agent "run a health check" or "why is my agent forgetting things". It runs the script, fixes what it can, reports back.

Heartbeat / cron (silent monitoring): Add one line to your HEARTBEAT.md — the agent runs it every cycle and stays silent unless something needs attention.

Proactive trigger: Add a line to AGENTS.md so the agent self-triggers the check when memory_search comes back empty.

What You Get

• scripts/memory_health.sh — portable shell script, no dependencies beyond bash and python3
• SKILL.md — agent instructions including the full auto-fix decision tree
• references/memory-architecture.md — the 3-tier memory model (MEMORY.md → active-context.md → daily logs) with community-proven config tweaks

Works On

• Linux servers (Ubuntu, Debian) — systemd + GNU date/stat
• macOS desktops — launchd + BSD date/stat fallbacks
• WSL2 on Windows

Does NOT support native Windows.

Requirements

• OpenClaw installed with openclaw in PATH
• bash + python3 (standard on Linux/macOS)
• No API keys, no external network calls, no data leaves your machine