You told your OpenClaw agent something important yesterday and today it has no idea what you are talking about. The conversation is gone, your preferences vanished, and the agent acts like you just met. This is the most common complaint in the OpenClaw community, and it almost always traces back to one of five specific causes.
In about 80% of cases reported in the OpenClaw community, memory loss comes from compaction wiping context that was never saved to disk. The remaining 20% splits between file path errors, permission issues, and a known bug with the /new and /reset commands. This guide walks through every cause, gives you exact diagnostic commands, and ends with a backup strategy so it does not happen again.
Quick Triage: Find the Problem in 60 Seconds
Before reading the full guide, run these three commands in your OpenClaw terminal. They tell you where the problem is.
# 1. Check if MEMORY.md is loaded
/context list
# 2. Check if memory flush is enabled
get compaction memory flush enable
# 3. Check today's daily note
ls ~/.openclaw/workspace/memory/$(date +%Y-%m-%d).md
If MEMORY.md is not in the context list, jump to Wrong File Path or Filename.
If memory flush returns false, jump to Compaction Clearing Memory.
If today’s daily note does not exist, jump to Heartbeat Not Writing Daily Notes.
If all three look fine, work through the causes below in order.
Compaction Clearing Memory
This is the number one cause. OpenClaw has a 200,000-token context window. When conversation fills past a threshold (default: around 80,000 tokens used), OpenClaw compresses older messages into a summary and discards the originals. That compression is lossy.
If you told your agent your timezone, a client deadline, or a project preference during conversation and it was never written to a file, compaction erases it. The agent kept the gist but dropped the specifics.
How to Confirm
Enable verbose mode and watch for compaction events:
/verbose
Then continue your conversation. When compaction fires, you will see a log entry. If important context disappears right after that log entry, compaction is your culprit.
The Fix: Enable Memory Flush
The memory flush tells OpenClaw to save important context to disk before compaction runs. Two commands enable it:
set compaction memory flush enable to true
set memory search.experimental.session memory to true
Then shape what the flush captures by adding this to your AGENTS.md:
## Memory Flush Rules
When flushing memory before compaction, prioritize:
1. Decisions made and their reasoning
2. New preferences or corrections to existing preferences
3. Project state changes (completed tasks, blockers, deadlines)
4. Contact information or relationship updates
5. Lessons learned or patterns observed
Do NOT save: routine acknowledgments, small talk, or restated information already in MEMORY.md.
Tuning the Thresholds
Two parameters control when compaction fires:
| Parameter | Default | Effect |
|---|---|---|
reserveTokensFloor | 40,000 | Minimum free tokens. Higher values trigger compaction earlier, giving the flush more time. |
softThresholdTokens | 50,000 | Early checkpoint where important context is flushed before compaction runs. |
For long working sessions, raise reserveTokensFloor to 60,000. This gives the flush more breathing room. Do not go above 120,000 unless your workflow demands multi-hour uninterrupted conversations.
The v2026.2.23 Fix
A compaction bug in earlier versions could silently skip the memory flush under certain token boundary conditions. If you are running an OpenClaw version from before late February 2026, update immediately. Run openclaw --version to check.
For our complete guide on configuring all four memory layers, see our OpenClaw memory configuration guide.
Wrong File Path or Filename
OpenClaw auto-loads exactly eight filenames at boot: SOUL.md, AGENTS.md, USER.md, TOOLS.md, IDENTITY.md, HEARTBEAT.md, BOOTSTRAP.md, and MEMORY.md. Any other filename is ignored.
A common mistake is creating memory.md (lowercase), Memory.md (mixed case), memories.md, or MEMORY.txt. None of these load. The agent starts every session without your stored context, and you wonder why it forgot everything.
How to Confirm
/context list
If MEMORY.md does not appear in the output, the file either does not exist, has the wrong name, or is in the wrong directory.
The Fix
Verify the file exists in your workspace root with the exact name:
ls -la ~/.openclaw/workspace/MEMORY.md
If the file is somewhere else or has the wrong name:
# Move it to the correct location
mv /path/to/your/memory-file.md ~/.openclaw/workspace/MEMORY.md
If you have a custom workspace path, check your configuration:
get workspace.directory
The file must be in whatever directory that command returns. Not a subdirectory. The workspace root.
File Permission Issues
This one catches people on Linux VPS deployments and Docker containers. OpenClaw needs read and write access to the workspace directory and every file inside it. If the process runs as a different user than the file owner, writes fail silently.
How to Confirm
# Check who owns the workspace files
ls -la ~/.openclaw/workspace/
# Check who the OpenClaw process runs as
ps aux | grep openclaw | grep -v grep
If the ownership does not match, you found the problem.
The Fix
# Option 1: Change ownership to match the OpenClaw process user
sudo chown -R $(whoami):$(whoami) ~/.openclaw/workspace/
# Option 2: Fix permissions on specific files
chmod 644 ~/.openclaw/workspace/MEMORY.md
chmod 755 ~/.openclaw/workspace/memory/
For Docker deployments, make sure your volume mount maps to a writable path inside the container. Add this to your docker-compose.yml:
volumes:
- ./openclaw-workspace:/home/openclaw/.openclaw/workspace:rw
The :rw flag is important. Without it, some Docker configurations default to read-only.
The /new and /reset Memory Wipe Bug
This is a documented bug (GitHub issue #21382) that catches people off guard. When you run /new or /reset, OpenClaw archives the session conversation history but the markdown memory file stays empty. The flush logic runs on normal session exit, but these commands bypass the exit flow before the flush executes.
In practice: you have a productive session, your agent learned new preferences, you type /new to start fresh, and everything from that session that was not already in a file is gone.
The Workaround
Until this bug is fixed upstream, manually flush before resetting:
Save everything important from this conversation to MEMORY.md and today's daily note.
Wait for the agent to confirm the write. Then run /new or /reset.
You can also add a standing instruction to your AGENTS.md:
## Pre-Reset Rule
Before executing /new or /reset, always write any unsaved context to MEMORY.md and today's daily note. Confirm the write completed before proceeding with the reset.
Heartbeat Not Writing Daily Notes
OpenClaw uses daily markdown files (memory/YYYY-MM-DD.md) as a running journal. If the heartbeat daemon is not running or is misconfigured, these files never get created or updated. That means the memory flush has nowhere to write session-specific context.
How to Confirm
# Check daemon status
openclaw daemon status
# Check if today's file exists
cat ~/.openclaw/workspace/memory/$(date +%Y-%m-%d).md
If the daemon shows as stopped or the daily file does not exist, your heartbeat is not running.
The Fix
# Restart the daemon
openclaw daemon restart
# Verify it is running
openclaw daemon status
Then add memory maintenance instructions to your heartbeat.md:
## Memory Maintenance (every 30 minutes)
1. Create today's daily note if missing (memory/YYYY-MM-DD.md)
2. Log: decisions, new contacts/projects, completed tasks, preference corrections
3. Promote durable insights from daily notes to MEMORY.md
4. If MEMORY.md exceeds 15,000 characters, compress stale entries
For more on heartbeat scheduling, see our heartbeat configuration guide.
Preventing Future Data Loss: Backup Strategies
Fixing the immediate problem is step one. Preventing recurrence is step two. Memory files are plain markdown. Treat them like any other critical data.
Git-Based Versioning
The most reliable approach: put your workspace under version control.
cd ~/.openclaw/workspace
git init
git add MEMORY.md AGENTS.md SOUL.md USER.md memory/
git commit -m "initial memory snapshot"
Add a cron job that commits changes daily:
# Add to crontab (crontab -e)
0 2 * * * cd ~/.openclaw/workspace && git add -A && git commit -m "daily memory backup $(date +\%Y-\%m-\%d)" 2>/dev/null
If something goes wrong, you can restore any previous state with git log and git checkout.
Cloud Sync
If your workspace is on a VPS, sync it to a cloud folder:
# rsync to a backup server (daily cron)
0 3 * * * rsync -avz ~/.openclaw/workspace/ user@backup-server:/backups/openclaw/
MEMORY.md Size Management
Keep MEMORY.md under 15,000 characters. The bootstrap limit is 20,000 characters per file, and 150,000 characters total across all bootstrap files. If your MEMORY.md exceeds this, it gets silently truncated. The agent sees the first 20,000 characters and ignores the rest.
Run a weekly review: promote valuable daily notes to MEMORY.md, archive notes older than 30 days, and remove stale entries. You can tell your agent to do this: “Review the last 7 daily memory files. Promote important items to MEMORY.md and flag stale entries for removal.”
For a full backup and restore workflow, see our OpenClaw backup and restore guide.
Frequently Asked Questions
Why does my OpenClaw agent forget everything after a long conversation?
Compaction. When the context window fills past its threshold, OpenClaw summarizes older messages and discards the originals. If important facts were never written to a file, they are lost in the summary. Enable the memory flush to prevent this: set compaction memory flush enable to true.
Does MEMORY.md get created automatically when I install OpenClaw?
No. You create it yourself. Either tell your agent “Create a MEMORY.md file in the workspace root and start logging important things you learn about me,” or create it manually with a text editor. The file must be named exactly MEMORY.md in the workspace root directory.
How do I check if my agent is loading MEMORY.md?
Type /context list in your OpenClaw session. This shows every file loaded into the current context. If MEMORY.md is not listed, check the filename (must be uppercase), the location (must be workspace root), and file permissions (must be readable by the OpenClaw process).
Why does /new or /reset erase my agent’s memory?
It is a known bug. The /new and /reset commands archive conversation history but bypass the normal exit flow where the memory flush writes unsaved context to disk. Workaround: manually tell your agent to save everything to MEMORY.md and the daily note before running either command.
Can I back up my OpenClaw memory files automatically?
Yes. The workspace is just a folder of markdown files. Use git for versioning (git init in the workspace, then a daily cron job to commit), rsync for remote backup, or any cloud sync tool. See the backup strategies section above for exact commands.
What is the maximum size for MEMORY.md?
The bootstrap limit is 20,000 characters per file. Content beyond that is silently truncated. Keep your MEMORY.md under 15,000 characters to leave a safety margin. If you are hitting the limit, move project-specific details into separate files and link to them.
Should I use Mem0 or stick with native OpenClaw memory?
Starting with native memory configured properly is the best approach for most users. Most persistence problems come from misconfiguration, not limitations in the native system. If you follow this guide and still find the agent losing critical context, third-party plugins like Mem0 (automatic capture), Cognee (knowledge graphs), or Hindsight (zero-config) can fill specific gaps. But they add complexity and cost.
My agent writes to memory but cannot find it later. What is wrong?
The retrieval index may not be configured. OpenClaw needs an embedding provider (OpenAI, Gemini, Voyage, or Mistral) to build searchable indices. Without one, memory_search returns nothing even though the files exist. Check your embedding configuration and add an explicit instruction to AGENTS.md: “Always search memory before answering questions about preferences, contacts, projects, or past decisions.”
Key Takeaways
- Compaction is the leading cause of memory loss. Enable the memory flush with
set compaction memory flush enable to trueand shape what it captures in AGENTS.md. - MEMORY.md must be exactly that filename, in the workspace root, with read/write permissions for the OpenClaw process. Anything else is silently ignored.
- The
/newand/resetcommands bypass the memory flush. Manually save context before using them until the bug is fixed upstream. - Keep MEMORY.md under 15,000 characters. Content beyond the 20,000-character bootstrap limit is silently truncated.
- Put your workspace under git version control with a daily cron commit. It takes 2 minutes to set up and gives you full recovery capability.
- If your heartbeat daemon is stopped, daily notes never get created and the memory flush has nowhere to write. Check with
openclaw daemon status.
SFAI Labs
