OpenClaw guide
What Is OpenClaw Memory? A Plain-English Guide
OpenClaw memory is the system that allows your OpenClaw agent to store information and retrieve it later — across turns within a session and, if configured correctly, across sessions. It's built on plain Markdown files in your workspace directory.
TL;DR
- OpenClaw memory is a set of Markdown files and retrieval tools that let your agent store and reference information across sessions.
- The system has four layers, but the most critical one — the memory flush — is disabled by default.
- Native memory works for simple use cases. For daily users carrying complex context, a plugin like Contexto or Mem0 fills the gaps.
OpenClaw memory is the system that allows your OpenClaw agent to store information and retrieve it later — across turns within a session and, if configured correctly, across sessions. It's built on plain Markdown files in your workspace directory.
That last part — "if configured correctly" — is where most users hit a wall.
What Are the Four Default Memory Mechanisms?
OpenClaw ships with four ways to persist information. Each operates differently and has different limitations.
1. Bootstrap Files (SOUL.md, AGENTS.md, USER.md)
These Markdown files live in your workspace root and are injected into the agent's context window at the start of every session. They're the closest thing OpenClaw has to permanent memory.
SOUL.md— defines the agent's personality and behavioral rulesAGENTS.md— sets operational guidelines, workflows, and directivesUSER.md— stores information about you, the user
Limitation: You write and maintain these manually. The agent doesn't update them on its own. They consume tokens from the context window, so the more you add, the less room the agent has for the actual conversation.
2. MEMORY.md
A curated file for long-term facts the agent should know. You or the agent can write to it during a session.
Limitation: Like bootstrap files, MEMORY.md sits inside the context window. It competes directly with your conversation for token space. As it grows, the agent gets less room to think.
3. Memory Folder (memory/YYYY-MM-DD.md)
A folder of daily log files. The agent can write session notes here, organized by date.
Limitation: The agent doesn't automatically read these at session start. The files just sit in the folder unless you explicitly tell the agent to search them, or unless you've added a retrieve-before-act directive to AGENTS.md. Most users don't know to do this.
4. Retrieval Index (memory_search)
OpenClaw includes a retrieval tool that can search across workspace files using semantic search or BM25. This is the most powerful native memory mechanism — when it works.
Limitation: The agent only uses it if instructed. There's no auto-recall. You have to add explicit directives like "search memory before responding" to AGENTS.md, and even then, the quality of retrieval depends on what's been stored and how.
Why Does Default Memory Have Limits?
Three structural problems:
The memory flush is disabled by default. OpenClaw has a pre-compaction memory flush that saves context before the context window resets. It's the single most useful native memory feature — and it ships turned off. Most users never know it exists. To enable it, you must set memoryFlush.enabled: true in your config.
Markdown files compete for the context window. Every fact stored in MEMORY.md or bootstrap files takes token space away from the active conversation. Store too much and the agent becomes slower and less responsive. Store too little and it forgets what matters. There's no good balance.
No auto-recall. The agent doesn't check its own memory folder or retrieval index unless you explicitly configure it to. By default, the memory/ folder is a filing cabinet the agent never opens.
How Does Native Memory Compare to Plugin-Enhanced Memory?
| Capability | Native OpenClaw Memory | Plugin-Enhanced (e.g., Contexto) |
|---|---|---|
| Auto-capture at session end | No (manual or flush if enabled) | Yes |
| Auto-recall at session start | No (requires directive in AGENTS.md) | Yes |
| Token competition | Yes (shares context window) | No (stored externally) |
| Setup required | Enable flush, add directives, curate files | One install command |
| Maintenance | Ongoing (prune files, manage token budget) | None |
| Relevance filtering | Basic (BM25/semantic search if configured) | Built-in relevance scoring |
| Works for simple sessions | Yes | Yes |
| Works for complex daily use | Poorly | Yes |
| Cost | Free | $20/month (Contexto) or varies (Mem0, Supermemory) |
Is Native Memory Enough for My Use Case?
Native memory is fine if:
- You use OpenClaw a few times a week, not daily
- Your sessions are short and self-contained
- You don't carry complex project context between sessions
- You're willing to manually curate
MEMORY.mdand bootstrap files - You've already enabled the memory flush and added a retrieve-before-act directive
Native memory isn't enough if:
- You use OpenClaw daily for real work
- You carry ongoing project context, decisions, and preferences across sessions
- You're tired of spending 3–5 minutes re-briefing your agent every morning
- You don't want to manually manage memory files
If you're in the second group, see the memory plugin comparison or jump straight to Contexto's docs.
Frequently Asked Questions
Does OpenClaw have memory by default?
Yes, but it's limited. OpenClaw has Markdown files (MEMORY.md, SOUL.md, AGENTS.md, USER.md), a memory/ folder for daily logs, and a retrieval index. However, the memory flush is disabled by default, and the agent doesn't auto-search its own notes unless explicitly configured.
Why does my OpenClaw agent forget everything between sessions?
Because OpenClaw is stateless by default. Each session starts with a fresh context window. The agent loads bootstrap files and nothing else. Without enabling the memory flush and adding a retrieve-before-act directive — or installing a memory plugin — the agent has no mechanism to recall past sessions automatically.
What is MEMORY.md in OpenClaw?
MEMORY.md is a workspace file where you or the agent can store long-term facts. It's injected into the context window at session start. The downside is it competes with your active conversation for token space — the bigger the file, the less room the agent has to work.
What is the memory flush in OpenClaw?
The memory flush is a pre-compaction feature that triggers a silent "agentic turn" to save important context to memory files before the context window resets. It's the most useful native memory mechanism and it's disabled by default. Enable it with memoryFlush.enabled: true.
How do I enable the memory flush?
Set memoryFlush.enabled: true in your OpenClaw configuration. Also set a softThresholdTokens buffer of at least 4000 to give the flush room to work before compaction kicks in. See the VelvetShark Memory Masterclass for the complete guide.
Should I use native memory or a plugin?
If your sessions are simple and infrequent, native memory with the flush enabled is sufficient. If you use OpenClaw daily and carry complex context across sessions, a plugin like Contexto or Mem0 automates capture and recall without the manual overhead.
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) · [The Cold Start Problem](/blog/cold-start-problem-ai-agents) · [How OpenClaw Memory Works Technically](/blog/how-openclaw-memory-works-technically)