Memory & Sessions

Understand OpenClaw MEMORY.md, daily notes, session history, compaction, memory search, QMD, active memory, dreaming, and memory wiki.

OpenClaw memory starts as plain Markdown files in the agent workspace. There is no hidden personal memory outside the files and indexes you configure: if the agent should remember something durably, it needs to write it down.

Memory Files

The default workspace is usually ~/.openclaw/workspace. These files matter most:

Do not use lowercase memory.md as the root long-term memory file. The root file OpenClaw expects is MEMORY.md.

What Goes Where

Put stable operating rules in workspace instructions:

• AGENTS.md for workflow rules and priorities
• SOUL.md for persona, tone, and boundaries
• USER.md for basic user profile facts
• TOOLS.md for local tool conventions

Put learned continuity in memory:

• MEMORY.md for facts that should survive across weeks
• daily notes for detailed session traces and observations
• DREAMS.md for reviewable consolidation output
• explicit reminders or automations for time-bound commitments

Action-sensitive memories should include permission, timing, expiry, owner, and whether the agent may act without asking again.

Sessions and Compaction

Sessions store conversation, tool calls, and routing context. Each agent has its own session store under its agent path, separate from the workspace.

When a session grows, OpenClaw summarizes older context while preserving recent messages. Automatic memory flushes can save important context before compaction, but compaction is not the same as long-term memory.

Useful commands:

openclaw sessions list
openclaw sessions show <session>
openclaw transcripts list
openclaw transcripts show <session>

For recall, prefer bounded memory/session tools over dumping raw transcripts into the prompt.

Memory Tools

The active memory plugin provides the agent-facing recall tools:

• memory_search searches indexed memory chunks
• memory_get retrieves a specific memory item

The CLI mirrors the same operational surface:

openclaw memory status
openclaw memory search "project decision"
openclaw memory index --force

Memory search lets the agent retrieve relevant prior information without injecting every memory into every prompt.

Search Backends

The built-in memory backend is SQLite. OpenClaw can also use QMD, Honcho, LanceDB, or provider-specific embedding/search configurations.

QMD is a local-first sidecar for Markdown memory. In the default workspace collection it tracks:

• MEMORY.md
• the memory/ tree

QMD can also index extra paths and, when explicitly enabled, session transcripts. If QMD is unavailable, OpenClaw can fall back to the built-in engine.

Active Memory

Active memory is optional and plugin-owned. For eligible interactive sessions, a narrow memory sub-agent can run before the main reply and inject relevant recall.

Use it when the assistant should remember context without the user explicitly asking for a search every time. Keep it scoped to the right agent and chat type.

Be careful with:

• stale facts
• overly broad recall
• private data crossing agent boundaries
• memory that overrules current user intent

Session toggles include:

/active-memory status
/active-memory off
/active-memory on

Memory Wiki

Memory wiki is a bundled plugin that compiles durable memory into a provenance-rich wiki vault. It does not replace the active memory plugin. Use memory_search for broad recall and wiki tools for curated, source-aware knowledge.

Dreaming

Dreaming is optional and disabled by default. When enabled, it performs background consolidation:

• Light and REM phases write review output, not long-term memory
• Deep phase can promote distilled memory into MEMORY.md
• human-readable review output goes to DREAMS.md or memory/dreaming/

Operational Checks

openclaw memory status
openclaw memory search "project decision"
openclaw status --usage

If memory seems wrong, inspect whether the problem is MEMORY.md, daily notes, session context, compaction, search indexing, active memory injection, or workspace instructions.