MEMORY.md is one of eight markdown files that 📝OpenClaw auto-loads at the start of every agent session. It serves as the curated long-term memory layer — durable facts, user preferences, and key decisions that should persist across all conversations. The model only "remembers" what gets written to disk; there is no hidden state.

Two-Layer Memory Architecture

OpenClaw's memory system uses two complementary layers, both plain Markdown stored in the agent workspace (~/.openclaw/workspace/ by default):

Daily logs are the raw signal. MEMORY.md is the distilled, curated output — only facts worth loading into every single session belong there.

Agent-Facing Tools

OpenClaw exposes two tools for memory access:

memory_search — semantic recall over all indexed memory files (MEMORY.md, daily logs, everything in the memory/ directory). Uses a mix of keyword and meaning-based matching via sqlite-vec embeddings, with optional reranking to suppress near-duplicate daily log entries.
memory_get — targeted read of a specific Markdown file by path and optional line range. Degrades gracefully when a file doesn't exist (returns empty text instead of throwing ENOENT).

Both tools are enabled only when memorySearch.enabled resolves true for the agent. The index is stored per-agent in SQLite at ~/.openclaw/memory/<agentId>.sqlite.

Memory Flush (Pre-Compaction Save)

When a session approaches the context window limit, OpenClaw triggers a silent agentic turn that reminds the model to save important context to memory files before compaction summarizes the conversation. This prevents context loss during long sessions. Controlled via agents.defaults.compaction.memoryFlush — enabled by default, no configuration required.

Dreaming (Background Consolidation)

Dreaming is an optional background pass that collects short-term signals from daily logs, scores candidates, and promotes only qualified items into MEMORY.md. The review surface is DREAMS.md. Grounded backfill can replay historical daily notes via openclaw memory rem-backfill --path ./memory --stage-short-term, staging candidates into the short-term dreaming store rather than writing directly to MEMORY.md.

Best Practices

Keep MEMORY.md short. Anything that doesn't need to be in every session should live in daily logs — the agent will find it through memory_search when needed.
Never overwrite, only append or curate. SOUL.md should contain a golden rule explicitly banning overwrites. In-file write rules on the first line of every memory file add defense in depth.
Back up via Git. Run git init in the workspace directory with auto-commit via cron or heartbeat. Keep ~/.openclaw/credentials/ and openclaw.json out of the repo.
MEMORY.md is private-session only. Never load it in group channel contexts to prevent accidental leakage of personal memory into shared spaces.
Real files, not symlinks. OpenClaw's resolveAgentWorkspaceFilePath() runs a path escape security check — symlinks resolving outside the workspace root are silently rejected.

Workspace File Hierarchy

MEMORY.md is one of eight files auto-loaded at boot: SOUL.md, AGENTS.md, USER.md, TOOLS.md, IDENTITY.md, HEARTBEAT.md, BOOTSTRAP.md, and MEMORY.md. Each agent workspace in a multi-agent setup gets its own MEMORY.md and memory/ directory, though shared memory can be organized via _shared/ directories at the team level.

Ecosystem Extensions

The Markdown-as-source-of-truth memory model has been extracted into standalone libraries (e.g., memsearch by the Milvus team) and enhanced with knowledge graph overlays (e.g., Cognee integration) that add relationship reasoning on top of the flat vector search. Alternative memory plugins can be swapped in via plugins.slots.memory.

MEMORY.md was the precursor pattern to what MythOS now does at scale. The insight — that an agent's memory should be human-readable, human-editable files rather than opaque database entries — was what made BrianBot's early Clawdbot iterations feel like a real collaborator rather than a stateless tool. The architecture is elegant in its simplicity: the model only knows what's on disk, and what's on disk is markdown you can read in any text editor.

The main failure mode is curation discipline. Left unmanaged, MEMORY.md becomes a diary and loses its value as a boot-context file. The dreaming system addresses this with automated promotion, but in practice explicit curation ("write this to MEMORY.md" / "remove this from MEMORY.md") produces cleaner results than passive accumulation.

For BrianBot's current stack, MythOS has largely replaced MEMORY.md's role — the external brain is now the single source of truth, with agents pulling context via MCP rather than loading a local file. But the pattern itself remains foundational to how agentic memory systems work.

📝OpenClaw — the open-source AI assistant platform MEMORY.md belongs to
📝Markdown-File Agent Definition — the design pattern MEMORY.md belongs to
📝OpenClaw Memory Architecture — the seven-surface memory model with MEMORY.md at its center
📝OpenClaw + MythOS Integration — extension of MEMORY.md into shared external memory via MCP
📝BOOTSTRAP.md — the initialization file that loads MEMORY.md
📝Token Optimization for OpenClaw — why MEMORY.md trim is one of the highest-leverage cost levers