How memory works

#The mental model

Imagine the assistant is a new employee on day one of every workday. It has notes from yesterday in a binder. It reads the binder, then starts the day. End of day, it writes notes back into the binder. Next morning: new instance, same binder.

In OpenClaw that binder is a set of files in~/.openclaw/workspace/:

MEMORY.md            curated long-term memory ("the binder")
memory/YYYY-MM-DD.md daily logs (raw, append-only)
AGENTS.md            workspace rules
USER.md              what the assistant knows about the user
IDENTITY.md          assistant's own identity
SOUL.md              how the assistant acts
TOOLS.md             local notes about tools used

Other runtimes use different paths but the pattern is the same: a few markdown files that get loaded into the prompt at the start of every session.

#What gets loaded on startup

Every new session, the runtime injects these files into the context BEFORE the first message arrives. So the assistant "remembers" anything written there. Anything said only in chat — gone, unless it was written down before the session ended.

#Three tiers of memory

🧠 Long-term — MEMORY.md

Curated. Things that matter for the long run: preferences, locked decisions, lessons learned, hard rules. Edit carefully, like a wiki.

• "User prefers English in chats, PT-BR for client comms."
• "Family domain @example.org is internal, not external — no pre-approval needed."
• "Long WhatsApp messages drop; default to short replies with links."

📅 Daily — memory/YYYY-MM-DD.md

Raw log of what happened today. Append-only. The assistant writes to this throughout the day. Periodically the important bits get distilled up into MEMORY.md.

💬 Working — the current session transcript

Everything in the current chat. Lives in context until either it gets written down or the context overflows (then it's gone).

#What this means for the user

Otherwise — it'll forget. Not because it wants to; because the next session won't see this conversation.

#How this sometimes goes wrong

• The assistant claims to remember something from a conversation that's outside the current session — it doesn't. It might be guessing from memory files, but might also be hallucinating.
• The assistant forgets to write something down even when told "save this." Pin it again if it doesn't confirm.
• Something gets written to the daily log but doesn't get elevated to MEMORY.md. The information lives, but the next-day instance has to dig.

#Probing what the assistant knows

Direct questions:

• "What do you have in MEMORY.md about X?"
• "Search memory for everything about Y."
• "What did we decide about Z?"
• "List the hard rules you're operating under."

#Resetting memory

Sometimes useful: a hard refresh.

• "Reread MEMORY.md from scratch and tell me what you find."
• "Forget the working assumption from earlier — start over on this decision."
• "Show me the section of MEMORY.md that covers Y."

#Privacy + safety

MEMORY.md contains private context. It loads only in direct chats — never in group chats, never in shared contexts. If you share the assistant with someone else, MEMORY.md doesn't go with it.