Willow Memory Health

Audit an OpenClaw agent's memory for staleness, redundancy, dark records, and contradictions. Use when a user asks to check memory health, clean up old memor...

Security Scan

The skill's code, instructions, and requirements are coherent with an on-disk memory-audit tool: it reads markdown memory files, optionally queries the qmd CLI, and reports candidates for archival/merge; nothing in the bundle requests unrelated credentials or hidden network endpoints.

Purpose & Capability

Name/description match the actual behavior: the skill scans .md memory files, scores age, redundancy, dark records (via qmd), and contradictions. The only required binary is python3, which is appropriate and proportionate.

Instruction Scope

SKILL.md stays mostly within scope (asks for memory directory, runs the included Python script, explains qmd usage, and requires confirmation before changes). Two minor mismatches: SKILL.md documents append-only 'memory writes' when the user opts in, but the included script only reports and does not perform appends or moves; and the SKILL.md lists cleanup actions (archive/merge) which are described as agent-driven — those file-modifying steps would be performed outside the report script, so installing this skill grants the agent the ability to propose and (with confirmation) perform filesystem operations. Reading all .md files in the specified directory is required for the task but does expose all memory contents to the agent/report.

Install Mechanism

Instruction-only install (script bundled); no downloads or external install steps. Low risk from install mechanism.

Credentials

No environment variables, credentials, or config paths are requested. The skill optionally invokes the qmd CLI if available, which is consistent with DARK detection behavior.

Persistence & Privilege

always is false and the skill is user-invocable; it does not request persistent platform privileges. The SKILL.md encourages user confirmation before file moves. Note that actual cleanup (moving/archiving) is an agent action outside the script and therefore depends on agent permissions and user consent.

Assessment

This skill appears to do what its name says: it reads your memory (.md) files, scores them, and reports candidates for archiving/merging. Before running it, confirm the exact memory directory you want scanned. Be aware the script will read the full contents of any markdown files under that directory (so it will surface any sensitive text stored there). DARK detection requires the qmd CLI — if you don't have it the tool will skip that check. The script as bundled only reports issues; any file moves or edits are performed by the agent after you confirm — review the list of files the agent plans to change before approving. Finally, SKILL.md mentions appending a summary to memory when 'memory writes' are enabled, but the bundled script does not perform that append itself — if you enable agent memory writes, verify what the agent will append and consider running the tool with --json or in a sandbox first.

Audit an OpenClaw agent's memory files for four failure modes that silently degrade memory quality over time:

Signal	What it means
STALE / DEAD	File hasn't been updated in 30+ / 90+ days — may no longer reflect current state
REDUNDANT	Two or more files cover the same subject (Jaccard similarity ≥ 0.55 on titles)
DARK	File exists in memory but doesn't surface when searched — invisible to the agent
CONTRADICTION	Same file contains opposing status words (e.g. "deployed" and "not deployed")

Trigger

Use this skill when the user:

• Asks to audit, clean up, or review memory
• Reports that the agent "forgot" something that should be in memory
• Wants to know which memories are stale or duplicated
• Asks why a memory isn't being retrieved

Step 1 — Find the memory directory

Ask for confirmation or infer from context. The memory directory is typically one of:

• <workspace>/memory/ — workspace-scoped memory files
• ~/.openclaw/agents/<agentId>/memory/ — agent-level memory

If neither is clear, ask: "Where are your memory files stored? (e.g. a memory/ folder in your workspace, or a path you specify)"

Step 2 — Run the diagnostic script

Run the bundled script against the memory directory:

python3 {baseDir}/scripts/memory_health.py --dir <memory-dir> --limit 50

Optional flags:

• --limit N — score only the N most recently modified files (default: 50)
• --qmd — enable DARK detection via qmd query (requires qmd CLI installed)
• --json — machine-readable output

If qmd is available and the user wants DARK detection:

python3 {baseDir}/scripts/memory_health.py --dir <memory-dir> --limit 50 --qmd

Step 3 — Interpret the report

The script prints a per-file table and a summary:

WILLOW MEMORY HEALTH — memory/ (50 files)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
FILE                    BUCKET   FLAGS
MEMORY.md               HOT      OK
2026-04-16.md           HOT      OK
2026-03-01.md           WARM     REDUNDANT
2026-03-01b.md          WARM     REDUNDANT
2025-12-10.md           DEAD     STALE | DARK
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
SUMMARY
  Files scored   : 50
  HOT  (<7d)     : 12
  WARM (7–30d)   : 23
  STALE (30–90d) : 11
  DEAD (>90d)    : 4
  REDUNDANT pairs: 3
  DARK           : 2  (qmd search returned no match)
  CONTRADICTION  : 1

HOT/WARM — healthy, no action needed.

STALE — review and either update or archive. Suggest: "These files haven't been updated in 30–90 days. Want me to review them and mark outdated sections?"

DEAD — strong candidate for archiving. Ask the user: "These files are 90+ days old. Should I move them to an archive/ subfolder?"

REDUNDANT — two files covering the same subject. Suggest merging the newer into the older or vice versa. Show both filenames and ask which to keep.

DARK — file exists but qmd search can't find it. This usually means the QMD index is out of date. Suggest running qmd update or re-indexing: openclaw memory sync.

CONTRADICTION — file contains opposing status phrases. Show the specific pairs flagged (e.g. "deployed" vs "not deployed") and ask the user to clarify current state.

Step 4 — Offer cleanup options

After reporting, offer numbered actions the user can pick:

1. Archive all DEAD files (move to memory/archive/)
2. Show REDUNDANT pairs for manual review
3. Update QMD index to fix DARK records (qmd update)
4. Show CONTRADICTION files for editing
5. Skip — report only, no changes

Always confirm before moving or modifying files.

Step 5 — Execute with confirmation

For each cleanup action:

• Show exactly which files will be moved or modified
• Confirm before proceeding
• Report what was done

After cleanup, offer to re-run the diagnostic to confirm the health score improved.

Memory writes

If the user has opted into memory writes, append a dated summary to memory/YYYY-MM-DD.md:

## Memory health audit — {timestamp}
- Files scored: N
- DEAD archived: N files → memory/archive/
- REDUNDANT merged: N pairs
- DARK fixed: N (qmd update run)
- CONTRADICTION resolved: N files

Append-only. Do not overwrite existing entries.

Notes

• MEMORY.md and undated files in memory/ are treated as evergreen — they are scored for REDUNDANT and CONTRADICTION but never flagged STALE/DEAD.
• Files outside the memory/YYYY-MM-DD.md naming convention use mtime for age calculation.
• DARK detection requires qmd CLI. If unavailable, the DARK column is skipped and noted in the report.
• This skill does not modify the QMD index directly — it reports and suggests; the user confirms all changes.