OpenClaw Memory Architecture is the layered system by which an 📝OpenClaw agent persists, retrieves, and reasons over context across sessions — combining seven distinct markdown surfaces (identity, relational, curated, raw, temporal, registry, external) into a single coherent memory model. The architecture's defining commitment is that everything the agent "remembers" lives in human-readable files on disk; the model has no hidden state.

Why the Layering Matters

A single memory layer cannot serve every use case an agent encounters. Boot-time context must be tight to avoid wasting tokens on every session start. Conversational context must be append-only so nothing is lost. Curated knowledge must be carefully shaped to remain useful across hundreds of sessions. Cross-agent context must live somewhere both legible and replicable. The seven-surface architecture is the answer to those competing demands — each layer optimized for a specific durability, scope, and write pattern, with bridges between them.

The Seven Memory Surfaces

The architecture composes seven distinct memory surfaces, each with a defined purpose, lifecycle, and load pattern.

Identity — 📝SOUL.md (personality, values, voice) and 📝IDENTITY.md (role, boundaries, affiliations). Constant. Loaded every session.
Relational — 📝USER.md, a long-term dossier on the human collaborator. Slowly evolving. Loaded only in DM sessions.
Curated — 📝MEMORY.md, durable facts, decisions, and lessons distilled from conversations. Edited deliberately.
Raw — memory/YYYY-MM-DD.md daily logs. Append-only conversation transcripts. Today and yesterday auto-load at boot; the rest is searchable on demand.
Temporal — 📝HEARTBEAT.md, scheduled tasks and autonomous pulse. Tells the agent what it should be doing on a rhythm.
Registry — 📝TOOLS.md (capabilities), 📝SKILLS.md (installable modules), 📝AGENTS.md (sub-agent registry). What the agent can reach, call, or delegate to.
External — 📝MythOS via 📝MythOS MCP, cross-agent shared memory. Loaded implicitly on the first tool call.

How Layers Interact in a Session

At session start, 📝BOOTSTRAP.md reads the identity, relational, curated, temporal, and registry surfaces into context. During conversation, the agent reasons over this loaded context and calls memory_search or memory_get against the raw daily-log layer for episodic recall. When the conversation approaches the model's context window limit, memory_flush triggers a silent agentic turn that saves important state to MEMORY.md before summarization compresses the rest. If the agent has the External layer wired in, every MCP call also pulls fresh augmentation context — Soul, Style, Human, Memory — through 📝Implicit Loading, keeping the agent's understanding of the human current across every machine and every client.

Durability and Curation

The architecture's resilience depends on disciplined movement between layers. Raw daily logs accumulate quickly; without curation, they become noise. Three mechanisms move signal upward:

Explicit curation — the operator or agent writes a fact to MEMORY.md ("remember this"), or removes it ("forget this"). Most reliable.
Dreaming — an optional background pass collects short-term signals from daily logs, scores candidates, and promotes qualified items into MEMORY.md via a DREAMS.md review surface.
Cross-session reinforcement — facts that the agent encounters repeatedly in daily logs become candidates for promotion, even without explicit instruction.

The same logic runs in reverse: stale MEMORY.md entries should be pruned. A bloated curated layer dilutes attention on every session start. 📝Token Optimization for OpenClaw treats MEMORY.md trim as one of the highest-leverage cost levers in the architecture.

External Memory and the MythOS Bridge

The local layers stop at the workspace boundary. For multi-agent ecosystems or multi-device operators, OpenClaw extends through MCP into MythOS. 📝OpenClaw + MythOS Integration covers the full pattern, but the architectural addition is simple: MythOS becomes a shared brain that any OpenClaw agent in the workspace can read from and write to, with augmentation context auto-loaded on every tool call. Local MEMORY.md remains agent-specific; MythOS becomes the cross-agent layer. The seven-surface model survives — it just gains an external eighth.

📝OpenClaw — the platform the architecture belongs to
📝Markdown-File Agent Definition — the broader pattern the architecture implements
📝MEMORY.md — the curated layer at the center of the system
📝The Augmentation Stack — Memory → Mind → Mouth, of which this is the Memory layer
📝OpenClaw + MythOS Integration — extension into shared external memory
📝OpenClaw Glossary — terms used across the architecture

Contexts

🏷️#openclaw