OpenClaw Memory Not Working — How to Diagnose and Fix It

Memory issues are among the most frustrating OpenClaw problems because they're subtle — the agent seems to work fine, it just doesn't remember what it should. Here's a systematic approach to diagnosing and fixing it.

Understand How Memory Works First

OpenClaw has no implicit memory. Everything the agent knows between sessions comes from files. If something wasn't written to a file, it doesn't exist in the next session. Memory issues are almost always file issues.

Step 1: Verify AGENTS.md Has Correct Load Instructions

cat ~/.openclaw/workspace/AGENTS.md | grep -A 10 "Every Session"

You should see something like:

## Every Session
1. Read SOUL.md
2. Read USER.md
3. Read COMPANY.md
4. If in MAIN SESSION: also read MEMORY.md

If MEMORY.md isn't listed, add it. If the instructions are missing entirely, your agent has no instruction to load any workspace files.

Step 2: Check MEMORY.md Exists and Has Content

ls -la ~/.openclaw/workspace/MEMORY.md
wc -l ~/.openclaw/workspace/MEMORY.md
head -20 ~/.openclaw/workspace/MEMORY.md

Step 3: Verify the Agent is Reading Files

# Ask the agent directly in Slack or chat:
"What do you know about me from your workspace files?"
"What's in your MEMORY.md?"

# If it says it doesn't have memory files or can't access them,
# the file loading instructions in AGENTS.md aren't being followed.

Step 4: Check You're in the Right Session Type

MEMORY.md is only loaded in main sessions. Cron jobs and sub-agents don't load it by default (by design — it keeps crons fast and cheap).

# To verify you're talking to the main agent:
openclaw gateway status
# Shows connected channels and active agent IDs

# If you're messaging in a channel that's connected to a
# sub-agent or secondary agent, that agent may not have MEMORY.md loaded.

Step 5: Force a Memory Write

If you want the agent to save something specific, be explicit:

# In Slack:
"Save this to your MEMORY.md: 
[whatever you want remembered]
Mark it under section 'Key Decisions - 2026-03'"

Step 6: Add Auto-Memory Rules to SOUL.md

# Add to SOUL.md:
## Memory Rules
When Rahul shares:
- A final decision on anything
- A strong preference I should remember
- Key context about a project
- Something they explicitly say to remember

Write it to MEMORY.md IMMEDIATELY before responding.
Confirm you've saved it with a brief note.

Step 7: Check File Permissions

ls -la ~/.openclaw/workspace/
# MEMORY.md should be readable and writable:
# -rw-r--r-- or -rw-rw-r-- is fine
# If it shows ---------- or is missing, that's the issue

chmod 644 ~/.openclaw/workspace/MEMORY.md

Common Root Cause Summary

• MEMORY.md not listed in AGENTS.md load instructions
• Talking to a cron/sub-agent context that doesn't load MEMORY.md
• Information was shared verbally but never written to file
• MEMORY.md got too large and is being truncated in context
• File permissions preventing read/write

For the full memory management guide including archiving strategies and knowledge base design, The OpenClaw Playbook covers it in depth for $9.99.