You have MEMORY.md set up. You had a full conversation, the agent took notes, and everything looked fine. Then you start a new session and the agent has no idea who you are or what you were working on. The file exists. The agent is reading something. But it is not reading the file you are editing.
This is the most common memory failure in OpenClaw, and it is almost never a bug. It is a path problem: the agent reads memory from its workspace, and the workspace is not where you think it is. Here is how to find the real one, edit the right copy, and confirm the fix.
The most common cause: workspace path mismatch
OpenClaw agents read from a workspace directory. The default is ~/.openclaw/workspace on the machine running the gateway, and when you run the gateway locally and chat from the same machine, everything points at the same place. The mismatch appears the moment the setup is split across machines or agents.
Two splits cause it. First, remote mode: if your gateway runs on a VPS or a Mac mini and you connect from a laptop, the workspace the agent uses lives on the gateway host, not on your laptop. Any edits you make to MEMORY.md locally never reach the agent. Second, multiple agents: the shared default workspace belongs to the main agent, while every additional agent resolves to its own workspace directory. Editing the main agent’s file does nothing for an agent that reads its own copy.
On the host behind this site, the reality looks like this:
Every non-default agent gets its own workspace, which is why the diagnostic step matters more than it sounds: the question is never “where is MEMORY.md?” but “which workspace does this agent read?”
Step 1: Find out which workspace the agent actually uses
Check the defaults first, then the per-agent overrides:
# The default workspace openclaw config get agents.defaults.workspace # Per-agent workspaces and identity openclaw agents list
If you are in remote mode, the path in that output is on the gateway host. Compare it with wherever you have been editing MEMORY.md. Different machine or different directory means you have found the problem. Also worth knowing: the workspace is the default working directory and the home for file tools and workspace context, separate from ~/.openclaw, which stores config, credentials, and sessions. When the environment sets a profile or a workspace variable, the default shifts too, so reading the resolved value beats assuming the path.
Three environment details can move the default without touching openclaw.json, which makes reading the resolved path essential. An OPENCLAW_PROFILE other than default changes the default workspace to a profile-suffixed directory. OPENCLAW_WORKSPACE_DIR overrides both the profile default and the configured path when set. And agents defined in agents.list without an explicit workspace resolve to their own state-directory workspace rather than the shared default. Each of these silently changes which MEMORY.md the agent reads, and all of them show up in the commands from step 1.
Step 2: Edit the right file
If the gateway is remote, edit MEMORY.md on the gateway host, not locally. SSH in and edit it there, or keep the workspace in a git repository and pull changes on the host, which is the cleanest long-term setup for remote gateways because it keeps local and remote workspaces in sync without manual file transfers. A real workspace shows the whole file family the agent loads at startup:
Two hygiene rules prevent a repeat of this bug. Keep one active workspace: old installs sometimes leave an ~/openclaw folder around, and multiple workspace directories cause exactly this kind of confusing drift, so archive or trash the ones you do not use. And if you manage the workspace files yourself, disable bootstrap file creation so the system does not reseed a fresh MEMORY.md next to yours.
Step 3: Verify what the agent loaded
At the start of a new session, ask the agent directly what its MEMORY.md says. If it reads back something outdated or blank, the workspace path is still wrong. If it reads back your latest content, the path is correct and something else is going on. The diagram stacks the whole diagnosis on one page:
The verification habit is worth repeating until it is automatic: after any memory edit, start a fresh session and ask what MEMORY.md says before trusting the change. That one question catches path mismatches, wrong-agent edits, and write-instruction gaps in a single step, and it takes less time than the confusion it prevents.
Other reasons memory does not persist
If the workspace path is correct but memory still resets, work through these:
- The agent is not writing to memory. Memory only persists if the agent’s instructions tell it to update the file. Check AGENTS.md and SOUL.md for a clear instruction to write durable facts to MEMORY.md and daily notes to
memory/. - Isolated subagent sessions. Subagents run in isolated sessions by default and do not share the main session’s loaded context. A subagent will not automatically see or update MEMORY.md unless its brief says so, and even then it edits its own view of the workspace rules.
- Context compaction on long sessions. Very long sessions can compact away files that were loaded early. Keeping MEMORY.md concise is the real fix: the file is read at session start, so the shorter it is, the more reliably it survives.
- The wrong agent’s file. With several agents on one host, confirm you edited the workspace of the agent that is actually forgetting.
Quick debug commands
If you are on a remote setup and have been editing files locally while wondering why nothing sticks, this is almost certainly the issue. The agent lives on the gateway host, and its workspace is where all of its files need to be. For the full picture of what belongs in that MEMORY.md, MEMORY.md explained covers the file itself, and the memory search guide covers why recall can fail even when the file is right. The workspace-file family ties together under The Complete OpenClaw Guide.
Not Ready to Self-Host? Try ClawTrust
Building agents locally is powerful, but managing infrastructure, security, and scaling takes effort. ClawTrust provides managed OpenClaw hosting: your agents run securely in the cloud with automatic scaling, no DevOps overhead, and 24/7 monitoring.
This post contains affiliate links. If you buy through them, I may earn a small commission at no extra cost to you.
About The Author
