OpenClaw Memory Mastery: Architecture, Patterns, and Real Examples

Prerequisite: Start with Memory Configuration for basics. This page goes deeper into architecture and patterns.

Memory architecture layers

OpenClaw memory spans three layers:

  1. Session transcript buffer — recent messages sent to the model (token-limited).
  2. Persistent state files — long-lived facts, preferences, and summaries on disk.
  3. Agent persona files — SOUL, USER, and MEMORY markdown files that shape behavior (see file structure).

SOUL / USER / MEMORY layout

  • SOUL.md — agent identity, tone, boundaries, tool policies.
  • USER.md — stable facts about the human (timezone, preferences, projects).
  • MEMORY.md — curated long-term notes the agent maintains (not raw chat logs).

Treat these like code: review diffs, back up before experiments (backup guide).

Seven memory patterns

  1. Sliding window — last N messages only; cheap, forgetful.
  2. Summary compression — periodic LLM summaries into MEMORY.md.
  3. Entity cards — structured bullets per person/project in USER.md.
  4. Retrieval-augmented memory — skills or MCP tools fetch notes on demand.
  5. Per-channel memory — separate contexts for work vs personal (multi-agent).
  6. Ephemeral scratchpad — temp files cleared nightly via cron.
  7. Hybrid local+cloud — local model for summarization, cloud for reasoning (Ollama guide).

Example config snippet

# Memory section (illustrative — verify keys for your version)
memory:
  historyLimit: 40
  persistPath: ~/.openclaw/memory
  summarizeEvery: 25
  personaFiles:
    soul: SOUL.md
    user: USER.md
    longTerm: MEMORY.md

Validate with openclaw config validate. Troubleshoot regressions via memory troubleshooting.