OpenClaw Memory: How It Works, How to Check and Fix It

When an OpenClaw agent forgets something, the cause is usually one of two gaps: what's stored on disk versus what's injected into the prompt, or what you said versus what the agent wrote down. OpenClaw has a command for each: /context list shows what's injected, and openclaw memory status shows what's stored and indexed.

Below: how the memory system works today, how to check it, and what makes it more reliable. Every file name, limit and command below is checked against the OpenClaw docs as of October 2026.

How does OpenClaw memory work?

OpenClaw remembers by writing Markdown files in the agent's workspace (~/.openclaw/workspace by default), and the docs are blunt about it: the model only remembers what gets saved to disk, and there is no hidden state.

Four files do the remembering:

• USER.md (optional): your stable preferences, communication style and active projects, written as dated directives. Loaded every session, with its own 4,000-character budget.
• MEMORY.md: long-term memory for durable facts and decisions. Loaded at session start, but only in the main, private session, not in shared or group chats.
• memory/YYYY-MM-DD.md: daily notes. Today's and yesterday's load automatically on a bare /new or /reset; the rest are indexed for the memory_search and memory_get tools.
• DREAMS.md: a review log of what the dreaming sweep promoted, for you to read.

Alongside them sit the workspace files OpenClaw injects into every prompt: AGENTS.md (operating rules, plus a ## Tools section for local conventions), SOUL.md (persona and tone), IDENTITY.md (the agent's own name and vibe, not yours) and BOOTSTRAP.md on first run. Older guides list eight bootstrap files, including TOOLS.md and HEARTBEAT.md; current docs fold tool notes into AGENTS.md and retire heartbeat monitors, and openclaw doctor --fix turns old HEARTBEAT.md content into ordinary scheduled jobs (heartbeat migration). If you put your profile in IDENTITY.md or a custom file like profile.md, move it to USER.md.

What are OpenClaw's memory limits?

Each injected file is cut at 20,000 characters (agents.defaults.bootstrapMaxChars), and all injected files together are capped at 60,000 (agents.defaults.bootstrapTotalMaxChars), per the agent workspace docs. USER.md keeps its separate 4,000-character cap. If you read a 150,000 total elsewhere, that number is out of date. Past a limit, the file on disk stays whole and only the injected copy is truncated, so nothing looks wrong until the agent misses the end of it.

How does OpenClaw decide what to remember?

Mostly, the agent decides, and three mechanisms back it up.

1. Explicit saves. Ask "remember that I prefer TypeScript" and the agent writes it to the right file. Mention it in passing and it may not.
2. Memory flush. Before compaction summarizes a long conversation, OpenClaw runs a silent turn reminding the agent to save what matters. It's on by default (agents.defaults.compaction.memoryFlush.enabled).
3. Dreaming. A background sweep, on by default and scheduled for 3 a.m. daily, scores what the agent keeps recalling and promotes items that clear score, recall-frequency and query-diversity thresholds into MEMORY.md (dreaming docs). Check it with /dreaming status.

Older guides describe dreaming as opt-in; the current docs ship it switched on, so a missed save now has a second chance. Memory still depends on judgment, either the model's or a scoring threshold's.

How do you see what OpenClaw has loaded into context?

Run /context list inside a session. It's the command most people skip, and it explains most memory complaints.

Bootstrap max/file: 20,000 chars
Injected workspace files:
- AGENTS.md: OK | raw 1,742 chars | injected 1,742 chars
- USER.md: OK | raw 388 chars | injected 388 chars

What to look for:

• Missing files. A file that isn't listed has zero effect on the agent.
• Truncation. If raw and injected sizes differ, the agent sees a cut copy. OpenClaw also adds a short notice in the prompt when this happens.
• The wrong session. In a group chat, MEMORY.md won't appear. That's by design.

/context detail breaks the prompt down per file, tool schema and skill; /context map draws it as a treemap; openclaw doctor reports raw versus injected sizes from the command line (context docs).

How do you check what OpenClaw has stored?

Use openclaw memory status for the index and openclaw memory search for the contents (CLI reference).

openclaw memory status                  # index state and provider, fast
openclaw memory status --deep           # also probe vector store and embeddings
openclaw memory status --index          # reindex if the store is dirty
openclaw memory status --fix            # repair stale recall locks
openclaw memory search "deploy notes" --max-results 20
openclaw memory index --force           # full rebuild

Add --agent <id> to scope any of these, or --json for scripts. One practical detail: search routes through the running Gateway, but status, index and most other memory commands need the Gateway stopped first. If you changed embedding settings and status shows an index identity warning, run status --deep, then index --force, then status again.

If a search returns nothing, the fact was either never written or isn't indexed. Open MEMORY.md and today's daily note to tell which.

Why does OpenClaw forget things?

Five causes cover nearly every case:

• It was never written. The agent said "noted" without saving. Ask it to write the fact down, then check the file.
• It's in an old daily note. Only today's and yesterday's notes load; older ones need a memory_search the agent has to choose to run.
• It was truncated. A long MEMORY.md or AGENTS.md lost its tail at 20,000 characters, or the 60,000 total ran out.
• Compaction summarized it. A long session compresses older turns; the memory flush catches some of it, not all.
• Search is broken. OpenClaw uses OpenAI embeddings by default, and a missing key or misconfigured provider quietly limits recall. memory status --deep shows it.

How do you make OpenClaw memory better?

Curate first, configure second.

• Keep MEMORY.md short. It's a curated summary, not a log. When it grows, move detail into memory/*.md, where search can still reach it.
• Write USER.md as directives. One line per preference, with a date, and supersede old entries instead of appending contradictions.
• Set the search provider explicitly. memory.search.provider accepts Gemini, Voyage, Mistral, Bedrock, Ollama, LM Studio, local GGUF and others. A local model removes the API cost and the external dependency.
• Let dreaming run, and read DREAMS.md. The sweep runs as a cron job OpenClaw manages for you, so if it never runs, check that the cron scheduler isn't disabled (cron.enabled: false), and run openclaw doctor --fix after upgrading from an older version.
• Try another engine if files aren't enough. OpenClaw supports Honcho (user modeling across sessions) and LanceDB as plugins, plus a memory-wiki plugin that compiles memory into a structured vault.
• Import what you already have. The Control UI imports memory from Claude Code, Codex and Hermes into memory/imports/. It's a one-time copy, so treat it as a starting point.

When is OpenClaw memory the wrong tool?

When the context you need was never said to OpenClaw in the first place. Your role, your clients and this week's priorities live in Gmail, your calendar, Notion and Slack. Better tuning can't make OpenClaw remember a meeting it never saw, and USER.md gives you 4,000 characters to summarize it by hand.

That's the job of a personal context layer. Unabyss builds your context from those apps, keeps it current, and serves it to OpenClaw over MCP (you connect it with a token and a setup prompt), and to Claude, ChatGPT, Cursor and Hermes from the same source. In an August 2026 Unabyss benchmark run in Claude Code, that context cut cost by 36% and time by 38% against connected tools alone (What Structured AI Context Is Worth). OpenClaw's memory still handles what you discussed last week; the context layer covers who you are. More options side by side in the best AI memory tools across ChatGPT, Claude and Cursor.

Related

• Hermes vs OpenClaw vs Claude Code: What's the Difference?
• Can OpenClaw and Claude Share Memory?
• How Does Hermes Memory Work?