Your OpenClaw agent wakes up fresh every session. It does not secretly remember anything between conversations, and that is the whole trick to making it feel experienced: OpenClaw has no hidden state, and the model only knows what gets saved to disk. The file that carries the durable part of that memory is MEMORY.md, and it is one of the fastest ways to turn a forgetful agent into one that behaves like a well-briefed colleague.
This guide explains what MEMORY.md is, how it fits with your agent’s daily notes, what belongs in it, and the maintenance habits that keep it useful for months instead of turning into a noisy archive.
What MEMORY.md actually is
MEMORY.md is a plain Markdown file in your agent’s workspace, and it is the long-term memory layer: durable facts, preferences, standing decisions, and short summaries that should be available at the start of every session. OpenClaw loads it into context when a session begins, so anything written there is standing knowledge the agent starts with, not something it has to rediscover by reading old conversation history.
The right mental model is a colleague’s briefing document, not a diary. A briefing document holds the facts someone needs before walking into a meeting: who the stakeholders are, what was decided, what the rules are. A diary holds everything that happened. MEMORY.md is the briefing document. Your agent also keeps a diary, and the two files have a strict division of labor.
Daily notes versus long-term memory
Next to MEMORY.md, every agent workspace has a memory/ folder with dated notes like memory/2026-09-04.md. This is the working layer: detailed daily notes, observations, session summaries, and raw context that might be useful later. Today’s and yesterday’s dated notes load automatically on a fresh session, and every dated note is indexed for semantic search. Here is what a real agent’s memory folder looks like after a few months of daily use:
The division of labor between the two layers is simple. Daily notes stay raw: what happened, what was tried, what changed, what was learned mid-task. MEMORY.md holds the cleaned-up version, the part actually worth carrying forward. Raw notes are cheap to write and cheap to keep. Long-term memory should stay sharp, because it is read at the start of every session and competes for the same context budget as everything else the agent needs to do its work.
What belongs in MEMORY.md
Good long-term entries share a few qualities. They are durable: decisions, project context, working preferences, and ongoing tasks that matter across sessions. They are specific: a style rule, a workflow step, a recurring gotcha, a contact preference. And they are actionable where it counts: for notes about what the agent should do later, capture when it is safe to act on the note, not just the fact itself.
Operational notes earn their place too. On a content site, that means things like site setup details, the affiliate program inventory, content style rules, and recurring strategy decisions, the kind of facts a new session would otherwise have to rediscover from scratch. A well-kept MEMORY.md makes the agent feel like it has been on the project for months, because in a real sense it has been.
The structure matters less than the discipline, but a workable skeleton looks like this:
What stays out
Three categories do not belong in long-term memory. Secrets: credentials, tokens, and private data have no place in a Markdown file that is loaded into context and indexed for search. Volatile facts: anything that changes constantly, like a live status or a temporary workaround, belongs in daily notes where it ages out naturally. And noise: praise, filler, or entries that duplicate what the daily notes already say. If something is too private, too volatile, or too noisy, it does not belong in MEMORY.md.
There is one more privacy rule built into the design: MEMORY.md loads in main sessions only. Shared contexts like group chats never inherit personal memory, so an agent in a public channel is not carrying your private briefing document with it.
How the agent uses memory day to day
Writing a note is as simple as asking: tell the agent to remember that you prefer a certain tool, and it writes the note to the right file itself. Beyond the bootstrap load, memory is searchable. Semantic recall runs across MEMORY.md, the daily notes, and session transcripts, and exact excerpts can be pulled on demand when the agent needs to verify a detail before answering. The diagram shows how the pieces fit together:
Two behaviors keep the system honest. First, the agent writes to memory proactively: when a preference, a workflow, or a recurring project detail surfaces, it is captured before the session ends. Second, memory is reviewed and pruned: stale entries get removed, and durable material from daily notes gets folded up into MEMORY.md over time. On current OpenClaw builds the heartbeat flow and generated workspace instructions do this periodic distillation automatically, so you do not need to hand-edit MEMORY.md for every detail. The maintenance commands below cover the manual passes:
Common mistakes
The first mistake is never writing anything down, and then wondering why the agent forgets. The second is writing too much: dumping full transcripts or constantly changing facts into MEMORY.md until the file outgrows the context budget. When that happens, OpenClaw keeps the file intact on disk but truncates the copy it injects into context, which means the tail of your memory silently stops reaching the agent. Treat that as the signal it is: move detailed material into memory/*.md, keep only a durable summary in MEMORY.md, and check the injected size with /context list or openclaw doctor.
The third mistake is assuming chat history will be enough later. It will not. History is a transcript; memory is a distillation. If you want the agent to remember, write it down somewhere durable. The fourth is putting secrets in memory and calling it convenience, which is how tokens end up in a file that gets indexed and shared. Keep long-term memory clean, and keep secrets in the credential store where they belong.
Quick tips
- Capture durable decisions, not every detail.
- Keep secrets and volatile facts out of long-term memory.
- Use daily notes as the raw feed; fold the good parts up.
- Prune stale entries on a schedule, not when it hurts.
- Think briefing document, not journal.
MEMORY.md is one of the fastest ways to make an agent feel experienced instead of forgetful. It is part of the broader OpenClaw configuration story, and the full platform guide lives at 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
I always mix up MEMORY.md and session context so this cleared it up, session stuff disappears but the file stays right.
Exactly. Session context is temporary, MEMORY.md is where you preserve stable preferences, decisions, and recurring context that you want available later.
What kind of things should go in MEMORY.md, like only big decisions or also little preferences that come up a lot.
Put in things that save repeated explanation or improve future judgment. Stable preferences, long term projects, and important decisions are good candidates, tiny one off notes usually are not.
The proactive memory writing idea is interesting, I hadnt thought about making the agent update memory on its own.
It is underrated. A simple habit is to capture durable takeaways at the end of a task, then keep daily logs separate from long term memory so the file stays clean.
This finally made MEMORY.md click for me, session context is temporary but the memory file is the stuff you want to keep.
Yes, that is the clean distinction. Session context is working memory, MEMORY.md is persistent recall for stable facts and decisions.
Would you store tiny preferences in MEMORY.md or is that too much noise over time.
Only the tiny preferences that repeat often enough to matter. If a note will not change future behavior much, it probably does not belong there.
The idea of writing to memory proactively is smart, I can see that helping a lot with long projects.
It really helps. The trick is to keep daily logs separate from long-term memory so the persistent file stays focused and useful.