Five-Layer Memory System

Type: OpenClaw persistent memory architecture

Definition

OpenClaw uses a five-layer memory system to persist context across sessions and survive context window compaction. Layer 1: SOUL.md (agent identity and principles). Layer 2: MEMORY.md (persistent cross-session facts, preferences, and configurations). Layer 3: Daily memory logs (memory/YYYY-MM-DD.md). Layer 4: Project context files (projects/{id}/context.md). Layer 5: Structured data files (data/.json, CSVs). Each layer serves a distinct purpose, and together they ensure that important context survives session restarts and context overflow events.

How It Works

Layer 1 — SOUL.md: The agent's identity file. Written once, updated rarely. Defines tone, communication style, core principles, domain expertise, and recurring rules. Read at every session start and shapes all behavior. Should include explicit memory-writing rules that trigger the agent to update MEMORY.md after significant tasks.

Layer 2 — MEMORY.md: Persistent cross-session memory. Stores routing decisions, operator preferences, system configuration, known issues, escalation patterns, learnings. The agent writes to it when it learns something worth remembering; the operator edits it when context changes. It's the catch-all for information that needs to persist but doesn't fit elsewhere.

Layer 3 — Daily memory logs: memory/YYYY-MM-DD.md files record operational events each day — projects initiated and completed, failures and resolutions, gate passes and fails, operator decisions, notable findings. These are append-only and form a chronological record of work done.

Layer 4 — Project context files: projects/{id}/context.md accumulates project-specific state updated as projects evolve. Enables sub-agents spawned months later to read history and resume work without re-doing earlier steps. Critical for long-running projects with gaps between active work periods.

Layer 5 — Structured data: data/.json, CSVs, and other machine-readable files. Read and written by processes, not directly by agents. Enables programmatic data manipulation without text parsing.

The key principle: don't rely on conversation history for important state. Files survive session restarts; conversation history doesn't. When context overflows, recovery involves writing current state to a file and resuming with that file as context.

Key Properties

  • Layer 1 SOUL.md — identity and principles; read at every session start; rarely changes
  • Layer 2 MEMORY.md — cross-session facts; agent writes after significant discoveries; operator edits on context changes
  • Layer 3 daily logs — memory/YYYY-MM-DD.md; chronological operational record; append-only
  • Layer 4 project context — projects/{id}/context.md; long-running project state; survives for months
  • Layer 5 structured data — data/.json and CSVs; process-readable; agent doesn't directly parse
  • Files over history — important state must be written to files; conversation doesn't persist
  • daily-logs — layer 3 of the memory system (memory/YYYY-MM-DD.md)
  • context-window — the pressure that drives need for layered memory
  • workspace-boot — SOUL.md and MEMORY.md are read at session start as part of workspace boot

Source Chapters