OpenClaw Memory Setup: A Practical Guide to Files, Search, and Safe Recall

An agent that forgets every preference after a conversation is frustrating. An agent that remembers everything indiscriminately is difficult to audit and easy to mislead. OpenClaw takes a deliberately inspectable approach: durable memory is written to Markdown files in the agent workspace, and the model can only remember what has been saved there.

That design gives you control. You can open the files, correct stale information, move detail out of the bootstrap context, and keep sensitive material out of long-lived notes. It also means “memory” is not magic and is not an access-control system. A saved note can guide future behavior, but hard permissions, sandboxing, and scheduled-task settings still enforce operational boundaries.

This guide explains the memory layers, a practical first setup, retrieval versus session history, and a maintenance loop that keeps recall useful without turning your workspace into an unsearchable transcript. For adjacent workflows, see our OpenClaw Task Flow guide, OpenClaw Custom Skills guide, and OpenClaw Cron Jobs guide.

Quick Answer: How Does OpenClaw Memory Work?

OpenClaw's default agent workspace is ~/.openclaw/workspace. Memory is stored as plain Markdown rather than as hidden model state. The important layers are:

• USER.md for a compact user model: stable preferences and profile facts.
• MEMORY.md for curated, durable facts, decisions, and project context that should be available at session start.
• memory/YYYY-MM-DD.md for detailed daily notes and working observations.
• Optional dreaming or consolidation notes for summaries that a person can review.

The files have different jobs. Put “Prefers concise status updates” in the user-model layer, a durable architecture decision in MEMORY.md, and a detailed meeting recap in a dated note. Do not copy every event into the bootstrap files simply because it might be useful someday.

A good mental model is write, retrieve, review:

1. Write only information that will help a future task.
2. Retrieve the smallest relevant slice when needed.
3. Review and correct durable notes as the facts change.

The Four Memory Layers

USER.md: stable preferences and profile facts

Use USER.md for information about the person or team that changes how the agent should communicate or collaborate. Examples include a preferred programming language, a recurring formatting preference, or a stable role on a project. Keep this layer compact. A user model is more useful when it contains current directives instead of a contradictory history of every preference ever expressed.

When a preference changes, update or supersede the old entry rather than appending a second active instruction. If the file says both “use short answers” and “always provide extensive background,” future behavior becomes ambiguous and the correction cost moves to every later prompt.

MEMORY.md: curated durable context

MEMORY.md is the long-term layer for non-profile facts and decisions. A useful entry might record the chosen deployment architecture, a repository convention, or a project decision that will matter next month. It is not a raw transcript and should not become a dumping ground for every tool result.

Write the decision and enough context to interpret it later. Include a date or version when the fact can change. For example, “The service uses the staging queue for integration tests (reviewed 2026-08-04)” is more useful than a paragraph of unexplained historical output.

Dated memory notes: the working layer

Files such as memory/2026-08-04.md are the place for detailed daily observations, session summaries, and raw context that may still be useful. These notes can be more verbose because they are not intended to be injected into every turn. They remain searchable, so you can retrieve a relevant passage without spending the entire note as permanent bootstrap context.

A simple daily-note structure works well:

# 2026-08-04

## Decisions
- Chose the staging queue for the migration rehearsal.

## Open questions
- Confirm whether the vendor supports regional failover.

## Follow-up
- Recheck the deployment runbook after the next release.

Use factual headings and stable identifiers. Future retrieval works better when a note names the service, repository, or decision instead of saying “the thing we discussed.”

Optional consolidation and review notes

OpenClaw's documented memory workflow can consolidate useful material from daily notes into the curated layer through its dreaming sweep. Treat those summaries as reviewable output, not unquestionable truth. Consolidation is a chance to remove stale details, merge duplicates, and preserve the decision that matters rather than the entire chain of reasoning.

If a summary changes future behavior, review it as carefully as you would review a configuration change. Memory should remain understandable to a person opening the workspace directly.

A Practical First-Day Setup

You do not need to prepopulate a large knowledge base. Start with one small pass:

1. Choose the workspace and inspect what exists

Confirm which agent workspace is active, then inspect its Markdown memory files. Avoid creating a second “master memory” directory just because a tool or shell session started in a different location. The active agent workspace is the source of truth for that agent.

2. Add only three to five durable items

Write current preferences to USER.md, durable project decisions to MEMORY.md, and put detailed context in a dated note. Good candidates are facts that would otherwise be re-explained repeatedly. Poor candidates include transient chat small talk, unverified claims, credentials, and content that is useful only for one short-lived task.

3. Give entries a review signal

Use dates, versions, owners, or “supersedes” language when a fact can become stale. A note without a time boundary may look authoritative long after the system has changed.

4. Test retrieval with a bounded question

Ask for one known fact and verify the source note. If recall is wrong, inspect the file first; do not immediately add another duplicate entry. The goal is to find whether the problem is missing data, ambiguous wording, retrieval scope, or stale context.

5. Keep the bootstrap layer small

OpenClaw documents that an oversized MEMORY.md may remain on disk while the copy injected into context is truncated to stay within bootstrap limits. Treat truncation as a maintenance signal: summarize the durable part, move detail into dated notes, or adjust the relevant limits intentionally after measuring the cost.

Memory Search Is Not Session History

There are two different questions that often get confused:

• “What durable fact did we save?” Use the memory files and memory-search tools.
• “What did we say in that earlier conversation?” Use session-history recall.

A daily note may be indexed for memory search without being loaded into every new prompt. Conversely, a session transcript can contain useful context that was never promoted into durable memory. Searching one does not guarantee that you searched the other.

This distinction is especially important for decisions. If a choice should guide work across future sessions, promote a concise version into MEMORY.md after verifying it. If it is only evidence for reconstructing a past conversation, leave it in the session record or dated note instead of treating it as a permanent instruction.

Safe Recall and Action-Sensitive Notes

Some memories contain more than facts. They carry an action boundary: do not edit a system until approval arrives, treat an external report as untrusted evidence, or wait until a migration window opens. When that context matters, write the condition explicitly:

The billing migration is still in design review. Treat this note as planning input;
do not edit the production billing implementation from this thread until the owner
approves the migration plan.

This preserves useful context, but the note does not enforce the rule. Use permission settings, sandboxing, approval gates, and scheduler controls for hard safety requirements. Likewise, never store API keys, passwords, session cookies, or other secrets in ordinary durable memory. A memory file is readable workspace data, not a secret manager.

Maintenance: A Five-Minute Weekly Review

A small review prevents memory drift:

1. Remove duplicates and notes that no longer change decisions.
2. Supersede changed preferences instead of leaving contradictory active entries.
3. Move detailed evidence from MEMORY.md into dated notes.
4. Check that action-sensitive notes still have the right owner, timing, and approval condition.
5. Verify that sensitive values are absent.
6. Test one representative retrieval and inspect its source.

If OpenClaw recalls a wrong answer, classify the failure before editing. The fact may not have been saved, the wording may be ambiguous, the note may be stale, the relevant detail may live in session history, or the bootstrap copy may be truncated. Each cause has a different fix.

Common Problems

“OpenClaw forgot something I wrote”

Check that the information was saved in the active workspace and that it is in the right layer. A detailed note is searchable context, not necessarily a fact injected at the start of every session. Confirm the file name and date, then use a focused retrieval query.

“It remembers an old preference”

Edit the user-model entry so the current preference is unambiguous. Do not merely add a newer sentence below an older contradictory directive. Add an observed or reviewed date when the preference is likely to change again.

“Memory makes prompts too large”

Keep MEMORY.md curated. Move transcripts, logs, and long explanations to dated notes. The durable layer should summarize decisions and stable facts, not reproduce all supporting evidence.

“A memory note caused an unsafe action”

Separate context from enforcement. Remove or correct the misleading note, then configure the actual permission, sandbox, approval, or schedule boundary that should have prevented the action. Do not rely on prose alone for a high-impact control.

FAQ

Does OpenClaw have hidden memory outside the files?

The documented memory model is file-based: the model remembers what is written to the workspace. Session history and runtime state are separate concerns, so inspect the relevant source instead of assuming every past message is durable memory.

Should I put everything in MEMORY.md?

No. Keep it curated and compact. Use dated notes for detailed working context and the user-model layer for stable preferences.

Can memory make an agent more accurate?

It can provide useful, reviewed context, but it does not prove that a stored fact is current or that the model will interpret it correctly. Keep dates, sources, and review signals for information that matters.

Is memory a replacement for access control?

No. Memory can record approval context, but permissions, sandboxing, and scheduled-task settings enforce operational boundaries.

Sources

• OpenClaw: Memory overview — file layers, daily notes, imports, and safe action context.
• OpenClaw: Memory architecture — layered storage and retrieval model.
• OpenClaw: Memory search — retrieval behavior and search considerations.
• OpenClaw: Session search — recalling conversation history separately from durable memory.
• OpenClaw: Session management — session boundaries and lifecycle context.
• LobsterDome: OpenClaw Task Flow — durable multi-step workflow context.

Sources accessed August 4, 2026.