openclaw-memory-quality

# openclaw-memhealth **External QA layer for OpenClaw memory — diagnose, guard, and remediate your agent's memory.** [Report a Bug](https://github.com/ladyiceberg/openclaw-memory-quality/issues/new?template=bug_report.md) · [Request a Feature](https://github.com/ladyiceberg/openclaw-memory-quality/issues/new?template=feature_request.md) --- OpenClaw automatically builds a memory system as your agent works — storing short-term recall signals, promoting them into `MEMORY.md`, and loading `SOUL.md` on every session. Over time, this memory accumulates problems that silently degrade your agent's behavior: - **Stale long-term memories** — code snippets pointing to deleted or heavily refactored files, still cited as facts - **False-positive short-term entries** — low-quality FTS hits that inflate recall counts and get promoted - **SOUL.md drift** — task instructions and business rules creeping into your agent's identity file - **No cleanup mechanism** — OpenClaw only adds to memory, never removes **openclaw-memhealth** is a standalone MCP Server that sits alongside your existing OpenClaw setup without occupying a plugin slot. It uses retrieval behavior data — not just content — to diagnose whether your memory system is producing noise. --- ## Three-layer architecture ``` Layer 1: Observe — diagnose memory health (read-only, zero risk) Layer 2: Guard — audit promotion candidates before they enter MEMORY.md Layer 3: Remediate — safely clean up polluted long-term memory ``` --- ## Requirements - **OpenClaw** (any recent version) - **Python 3.11+** - **LLM API Key** (optional — for semantic evaluation features) - OpenAI, Anthropic, Kimi, or MiniMax --- ## Installation ```bash pip install openclaw-memory-quality ``` --- ## MCP Tools ### Layer 1 — Observe (read-only) | Tool | Description | |------|-------------| | `memory_health_check_oc()` | Quick health scan — zombie count, false-positive rate, three diagnostic scores | | `memory_retrieval_diagnose_oc()` | Detailed retrieval quality diagnosis — high-freq low-quality entries, config suggestions | | `memory_longterm_audit_oc()` | Deep audit of `MEMORY.md` — source validity, duplicate detection, generates `report_id` | ### Layer 2 — Guard | Tool | Description | |------|-------------| | `memory_promotion_audit_oc()` | Pre-promotion quality check — 5 gates + LLM long-term value assessment | | `memory_config_doctor_oc()` | Infer embedding/minScore configuration issues from behavior data | | `memory_soul_check_oc()` | Audit `SOUL.md` for boundary violations, identity drift, and stability | ### Layer 3 — LLM Semantic Layer | Tool | Description | |------|-------------| | `memory_longterm_audit_oc(use_llm=True)` | Semantic validity review + merge suggestions | | `memory_soul_check_oc(use_llm=True)` | Persona vs. task-instruction classification, contradiction detection | | `memory_longterm_cleanup_oc(report_id)` | Safely rewrite `MEMORY.md` — atomic write, backup, concurrency guard | --- ## Skills (slash commands) Once installed, these slash commands are available in your OpenClaw conversations: | Command | Description | |---------|-------------| | `/memory-check` | Run full health check and open the visual dashboard | | `/memory-cleanup` | Clean up stale entries in long-term memory | | `/memory-diagnose` | Deep retrieval quality diagnosis | | `/memory-promote` | Pre-promotion audit to prevent low-quality content from entering long-term memory | | `/soul-check` | Full SOUL.md integrity audit | --- ## How it works OpenClaw's memory pipeline has a structural weakness: ``` Retrieval noise (minScore=0.35 default + FTS literal matching) ↓ produces Short-term false positives (high-frequency low-quality entries) ↓ via Promotion miscalculation (frequency component ignores hit quality) ↓ pollutes MEMORY.md (append-only, no cleanup mechanism) ↓ causes Long-term agent behavior drift ``` openclaw-memhealth intercepts this chain at every stage — diagnosing retrieval quality from `queryHashes` and `avgScore` signals, auditing long-term memory against current source files, and checking `SOUL.md` for content that doesn't belong in an identity file. --- ## Relationship to memory-quality-mcp [memory-quality-mcp](https://github.com/ladyiceberg/memory-quality-mcp) handles **Claude Code** memory quality. **openclaw-memhealth** handles **OpenClaw** memory quality. Both tools are part of the **memhealth** product line — same approach, different ecosystems. Power users running both Claude Code and OpenClaw can use both tools side by side. --- ## Dashboard Preview    --- ## License MIT — see [LICENSE](LICENSE)