OpenClaw Memory Doctor

Diagnose and restore OpenClaw memory reliability with evidence, minimal risk, and verifiable outcomes.

Positioning

• One-line value: find the real cause of memory degradation fast and recover reliable recall with proof.
• Audience: OpenClaw operators responsible for recall quality and memory stability.
• Use when: there is a concrete memory symptom.
• Do not use when: the issue is unrelated to memory (UI, network, auth, unrelated plugin failures) or the user asks for broad speculative tuning.
• Difference: this is not generic troubleshooting, it is a symptom-driven memory runbook with confidence scoring and strict verification.

Scope

Handle only:

1. weak or empty semantic recall;
2. poor or empty memory search results;
3. Dreaming off or stalled;
4. stale, empty, or drifting memory index;
5. poor promotion quality (noise, duplicates, weak usefulness).

Non-Goals

• Do not troubleshoot all OpenClaw problems.
• Do not perform broad config rewrites without explicit approval.
• Do not claim a fix is complete before verification gates pass.
• Do not ask users to paste secrets in chat.

Required Operating Mode

Follow this sequence every time:

1. Pin symptom

   • State one primary symptom in one sentence.

2. Collect evidence (read-first)

   • Start with read-only diagnostics.

3. Diagnose with confidence

   • Separate fact, inference, and hypothesis.
   • Assign confidence: high, medium, or low.

4. Apply minimal safe fix

   • Apply the smallest change with lowest blast radius.
   • Ask for approval before broad changes.

5. Verify outcome

   • Confirm using objective checks, not intuition.

6. Return structured report

   • Use the Output Contract exactly.

Baseline Triage (always first)

openclaw status
openclaw doctor --non-interactive
openclaw memory status
openclaw memory status --deep

If commands are unavailable, report the blocker and provide the minimum command set for the user to run.

Symptom Routes

A) Recall is empty or weak

openclaw doctor --non-interactive
openclaw memory status --deep

Check for:

• provider readiness;
• embedding/dependency failures;
• fallback mode behavior;
• signals of empty or corrupted index.

B) Dreaming is off or stalled

openclaw memory status

Validate:

• plugins.entries.memory-core.config.dreaming.enabled;
• schedule, frequency, timezone correctness;
• freshness of memory artifacts (for example DREAMS.md and daily memory files).

C) Index is stale or empty

openclaw memory status --deep
openclaw memory index --force
openclaw memory status --deep

Validate:

• files/chunks > 0;
• expected memory sources are indexed;
• metrics improved after reindex.

D) Promotion quality is poor

openclaw memory promote --limit 10
openclaw memory promote-explain "<candidate text>"

Check:

• relevance and recency;
• noise and duplicates;
• thresholds too strict or too loose;
• candidate quality mismatch.

Safety Guardrails

• Prefer read-only checks before edits.
• Apply one change per iteration, then verify.
• Request approval for high-blast-radius edits.
• If uncertainty is above medium, provide top-2 hypotheses and the next discriminating test.
• Explicitly report conflicting evidence.

Verification Gates (mandatory)

After each fix:

openclaw memory status --deep
openclaw doctor --non-interactive

Only mark success when all are true:

1. readiness and health are acceptable for the intended mode;
2. index is non-empty and consistent;
3. Dreaming state matches target configuration;
4. control query shows measurable recall improvement.

Output Contract (mandatory)

Always return:

1. Symptom
2. Evidence (facts + commands + key outputs)
3. Diagnosis (root cause or top-2 causes + confidence)
4. Fix applied (minimal change)
5. Verification (passed/failed checks)
6. Residual risk
7. Next best action

Response Style

• Be concise and technical.
• Never mix facts with hypotheses.
• Never claim complete recovery without passing verification gates.
• Return actionable deliverables, not generic prose.

Author

Vassiliy Lakhonin