OpenClaw Memory Not Working? Complete Troubleshooting Guide

If your OpenClaw agent isn't remembering things it should, the problem is almost always one of 8 known failure modes. This page walks through each one with the exact symptom, root cause, and fix.

Issue 1: Agent Forgets Everything After Compaction

Symptom: Agent works fine within a long session but loses all context when compaction runs.

Cause: The memory flush is disabled. Without it, compaction summarizes and discards context without saving key details first.

Fix:

memoryFlush.enabled: true
softThresholdTokens: 4000

Set softThresholdTokens to at least 4000 so the flush has enough room to work before compaction takes over. This is the #1 fix for memory loss in OpenClaw. See How OpenClaw Memory Works for the full explanation.

Issue 2: Agent Doesn't Search Its Own Memory Files

Symptom: You've saved notes in MEMORY.md or the memory/ folder, but the agent never references them.

Cause: No retrieve-before-act directive in AGENTS.md. The agent doesn't check memory unless explicitly told to.

Fix: Add this to your AGENTS.md:

## Memory Protocol
Before responding to any question about past work, 
decisions, or ongoing projects, search the memory 
folder using memory_search. Reference any relevant 
findings in your response.

This forces the agent to check its own filing cabinet before answering.

Issue 3: Plugin Install Fails — "Plugin not found: @ekai/contexto"

Symptom: openclaw plugins install @ekai/contexto returns an error saying the plugin wasn't found.

Cause: OpenClaw version too old, network issue, or registry unreachable.

Fix:

1. Check OpenClaw version: openclaw --version
2. Run openclaw plugins list to confirm the plugin registry is reachable
3. Try with --force: openclaw plugins install @ekai/contexto --force
4. If behind a corporate proxy, ensure registry.openclaw.ai is accessible

Issue 4: Plugin Returns "401 Unauthorized"

Symptom: Plugin is installed but memory operations fail with a 401 error.

Cause: API key is missing, expired, or incorrectly entered.

Fix:

openclaw contexto auth --reset

Re-enter your API key from getcontexto.com/dashboard. If you're on the free trial and it expired, you'll need to subscribe to restore access.

For Mem0: check your plugin config JSON for typos in the API key field. A single extra character causes silent failure.

Issue 5: Memory Recall Returns Irrelevant Results

Symptom: Agent recalls memories, but they're unrelated to the current conversation.

Cause: Relevance threshold too low, or old/outdated memories are polluting results.

Fix:

1. If using Contexto: set contexto.recallThreshold to 0.8 (default is 0.7)
2. Reduce recall volume: set contexto.maxRecallItems to 5
3. Open the memory dashboard and delete outdated or irrelevant memories
4. If using native memory: prune the memory/ folder of old daily logs that are no longer relevant

Issue 6: MEMORY.md Has Grown Too Large

Symptom: Agent responses are slow. Context window fills up faster than usual. Agent seems "dumber" — shorter, less detailed responses.

Cause: MEMORY.md is consuming too many tokens from the context window, leaving less room for the actual conversation.

Fix:

1. Check the file size: a file over 2,000 words is likely too large
2. Move older entries from MEMORY.md to the memory/ folder (which isn't auto-loaded into context)
3. Keep only the most critical, current facts in MEMORY.md
4. Consider switching to a memory plugin that stores memories externally (Contexto, Mem0) — this eliminates the token competition problem entirely

Issue 7: Agent Captured Memories Are Empty or Missing

Symptom: You expected the agent to save context at session end, but the memory store is empty.

Cause: Auto-capture didn't fire — session ended abruptly, or capture is disabled.

Fix:

1. Check plugin config: ensure auto-capture is enabled (contexto.autoCapture: true)
2. Enable debug mode: contexto.debug: true — check console for [contexto] Captured X memories
3. End sessions cleanly — closing the terminal mid-conversation prevents the agent_end hook from firing
4. If using native memory (no plugin), the agent only saves to memory files if explicitly instructed or if the memory flush triggers before compaction

Issue 8: Two Memory Plugins Causing Conflicts

Symptom: Duplicate memories in context. Agent repeats itself. Conflicting information injected.

Cause: Two memory plugins (e.g., Contexto + Mem0) both hooking into before_prompt_build and injecting memories independently.

Fix: Uninstall one plugin. Running two memory systems simultaneously is never recommended — they'll both capture and recall independently, causing duplicate injections and wasted context window space.

openclaw plugins uninstall @mem0/openclaw-mem0

Keep whichever plugin better fits your needs. See the comparison page for help deciding.

How Do I Verify Memory Is Actually Working?

Run this test procedure:

1. Start a session with debug mode enabled
2. Tell the agent a unique fact: "My project is called ProjectAlpha and it uses Rust."
3. End the session cleanly
4. Start a new session
5. Ask: "What's my project called?"
6. If the agent answers "ProjectAlpha" — memory is working
7. If the agent asks what your project is — memory is not working

Check the debug console output between steps 3 and 5 for memory capture/recall logs.

When Should I Reset vs Debug?

Debug first if:

• Memory was working before and recently stopped
• You changed a configuration recently
• You installed or updated a plugin
• The issue is intermittent

Reset if:

• Memory database is corrupted (error messages referencing SQLite integrity)
• Outdated memories are consistently polluting recall
• You want a clean start after changing your workflow significantly

Reset command for Contexto:

openclaw contexto reset --confirm

This deletes all stored memories. Export first if you want a backup:

openclaw contexto export --format json > backup.json

Frequently Asked Questions

Why is the memory flush disabled by default in OpenClaw?

Likely a performance/cost trade-off. The flush adds an extra LLM call before every compaction, increasing latency and API costs. OpenClaw ships with it off to optimize for speed. For users who need memory, the performance cost is negligible compared to the context preservation benefit.

How do I know if my memory plugin is actually running?

Enable debug mode in the plugin config. For Contexto: set contexto.debug: true. For Mem0: check its log output. You should see capture/recall entries in the console at session start and end.

Can a corrupted SQLite database cause memory failures?

Yes. If the Contexto SQLite file is corrupted (e.g., from a power failure during write), memory operations will fail. Export what you can and reset: openclaw contexto reset --confirm.

What's the most common memory issue in OpenClaw?

The memory flush being disabled. Most users never know it exists, never enable it, and wonder why their agent forgets everything after compaction. Enable it. It's the single biggest improvement you can make to native memory.

Do memory plugins work in all OpenClaw modes (Telegram, CLI, etc.)?

Memory plugins hook into the agent lifecycle, not the interface layer. They should work in Telegram, CLI, and any other OpenClaw interface.

How do I check how much context window space my memory is using?

Enable debug logging to see the full prompt sent to the LLM at each turn. Count the tokens allocated to bootstrap files, injected memories, and conversation history. If injected memories are consuming more than 10% of the context window, reduce maxRecallItems or raise the relevance threshold.

Built by [Ekai Labs](https://ekailabs.xyz). Questions: [Discord](https://discord.com/invite/5VsUUEfbJk) · om@ekailabs.xyz · [getcontexto.com](https://getcontexto.com)

Install Contexto: openclaw plugins install @ekai/contexto

Related: [Contexto Docs](/docs) · [How OpenClaw Memory Works](/blog/how-openclaw-memory-works-technically) · [What Is OpenClaw Memory?](/blog/what-is-openclaw-memory)