Willow Memory Health

intent

audit an openclaw agent's memory files to surface four silent failure modes that degrade memory quality over time: staleness (files not updated in 30+ or 90+ days), redundancy (multiple files covering the same subject), dark records (files that exist but don't surface in search), and contradictions (opposing status words in the same file). use this skill when a user asks to audit, clean up, or review their memory, reports the agent forgot something that should be there, wants to know which memories are stale or duplicated, or asks why a memory isn't being retrieved.

inputs

input	format	notes
memory directory path	string or inferred from context	typically <workspace>/memory/ or ~/.openclaw/agents/<agentId>/memory/. if unclear, ask the user for the path.
python3 executable	system binary	required. check python3 --version before running diagnostics.
qmd CLI (optional)	system binary	only needed for DARK detection. if not present, DARK detection is skipped and noted in the report.
memory_health.py script	python script	bundled in {baseDir}/scripts/. must be present to run diagnostics.
limit parameter (optional)	integer	number of most recently modified files to score. default: 50. use --limit N to override.

external connections:

• qmd CLI: if installed, enables dark record detection via qmd query. no env vars or auth required.

procedure

step 1: locate and confirm the memory directory

ask the user where their memory files are stored. confirm one of these locations:

• <workspace>/memory/ (workspace-scoped memory)
• ~/.openclaw/agents/<agentId>/memory/ (agent-level memory)
• custom path the user provides

output: confirmed directory path as a string.

step 2: run the diagnostic script

execute the memory health script against the confirmed directory:

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

if qmd is installed and the user wants dark detection, run:

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

optional flags:

• --limit N: score only the N most recently modified files (default: 50).
• --qmd: enable dark detection via qmd query. skipped silently if qmd is unavailable.
• --json: output machine-readable json instead of human-readable table.

output: scored report with per-file table showing FILE, BUCKET (HOT/WARM/STALE/DEAD), and FLAGS (OK, REDUNDANT, DARK, CONTRADICTION, or combinations).

step 3: parse and interpret the report

read the script output as a table with columns: FILE, BUCKET, FLAGS. the summary section shows counts:

• HOT (<7d): file updated in the last 7 days. healthy, no action needed.
• WARM (7, 30d): file updated 7 to 30 days ago. healthy, no action needed.
• STALE (30, 90d): file not updated in 30 to 90 days. review and either update or archive.
• DEAD (>90d): file not updated in 90+ days. strong candidate for archiving.
• REDUNDANT: two or more files with jaccard title similarity ≥ 0.55. consider merging.
• DARK: file exists but qmd search returned no match. qmd index is out of date.
• CONTRADICTION: file contains opposing status words (e.g. "deployed" and "not deployed"). needs clarification.

output: interpreted summary as prose, with specific file names and recommendations per failure mode.

step 4: offer cleanup actions

present the user with numbered actions:

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)

ask which action(s) the user wants to take. require explicit confirmation before any file operation.

output: list of selected actions as a numbered menu.

step 5: execute cleanup with confirmation

for each selected action:

• show exactly which files will be moved, merged, or modified.
• confirm before proceeding.
• execute the operation (move files, run qmd update, etc.).
• report results (e.g. "moved 4 files to memory/archive/").

after cleanup, offer to re-run the diagnostic (step 2) to confirm the health score improved.

output: summary of files moved, merged, or updated, plus the new health counts if re-run.

step 6 (optional): write memory audit log

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

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

always append, never overwrite. output: confirmation that the audit entry was written.

decision points

if the memory directory path is unclear: ask the user: "where are your memory files stored? (e.g. a memory/ folder in your workspace, or a path you specify)".

if qmd CLI is not installed: skip dark detection silently. note in the report: "DARK detection skipped (qmd CLI not found)". do not fail the entire diagnostic.

if the diagnostic script returns an error (e.g. directory not found, permission denied): stop and report the error message to the user. ask them to verify the path exists and is readable. do not proceed to step 3.

if the report shows STALE files (30, 90 days): suggest: "these files haven't been updated in 30, 90 days. want me to review them and mark outdated sections?" ask if the user wants to archive them or keep them as-is.

if the report shows DEAD files (>90 days): ask: "these files are 90+ days old. should i move them to an archive/ subfolder?" require explicit yes/no before archiving.

if the report shows REDUNDANT pairs: show both filenames and ask: "these two files cover the same subject. which one do you want to keep?" offer to merge the newer into the older or vice versa.

if the report shows DARK records: suggest: "these files exist but don't surface in search. this usually means the qmd index is out of date. want me to run qmd update?" if yes, run qmd update and re-run the diagnostic.

if the report shows CONTRADICTION: show the specific opposing phrases (e.g. "deployed" vs "not deployed") and ask the user to clarify the current state. do not auto-resolve.

if no actions are selected in step 4: end the skill. report that the audit is complete and no changes were made.

if a file operation fails (e.g. move, chmod): report the error, stop that operation, and ask the user to manually fix the issue before retrying.

output contract

success is defined by:

• a per-file table with columns FILE, BUCKET, FLAGS, formatted as plaintext or json (if --json flag used).
• a summary section showing counts of HOT, WARM, STALE, DEAD, REDUNDANT, DARK, and CONTRADICTION files.
• specific file names and line numbers for CONTRADICTION and DARK records.
• for each cleanup action executed, a log entry showing which files were moved, merged, or updated, and the timestamp.
• if memory writes are enabled, an append-only entry in memory/YYYY-MM-DD.md with the audit summary.

all output must be readable by the user and machine-parseable (if json flag is used).

outcome signal

the user knows the skill worked when:

• the diagnostic report appears in less than 10 seconds (for <100 files) with no errors.
• specific files are named in each failure mode section (STALE, DEAD, REDUNDANT, DARK, CONTRADICTION).
• the health summary counts match the number of files scored.
• after cleanup actions, the user can re-run the diagnostic and see the health counts improve (e.g. fewer DEAD files, fewer DARK records after qmd update).
• if memory writes are enabled, the audit entry appears in the memory log file with the correct timestamp and counts.
• the user confirms each action explicitly before it executes, and receives a confirmation message afterward.

---

notes

• MEMORY.md and undated files in memory/ are treated as evergreen. they are scored for redundant and contradiction but never flagged stale or 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.
• the skill reports and suggests but does not modify the qmd index or move files without explicit user confirmation. all destructive actions require a yes/no prompt.
• rate limits: none for this skill. qmd update may take 5+ seconds for large indices, but the skill waits and reports progress.
• edge cases: empty memory directories (report "0 files scored, no action needed"), network timeouts (if qmd is remote, retry once), permission errors (prompt user to check file ownership).

credits

original author: rudi193-cmd (clawhub)