Three-layer memory architecture for persistent OpenClaw agent context

Memory architecture for persistent agent context

A developer running a multi-agent OpenClaw operation for real estate encountered persistent context loss where agents would start each session from zero, requiring re-explanation of previous work. This led to concrete business costs including agents treating warm leads like strangers and missing deadlines due to lack of state.

The solution is a 3-layer memory architecture built on OpenClaw's existing workspace and memory infrastructure. Information flows downward through the layers and is never duplicated across them.

Layer 1: Brain (workspace files)

OpenClaw injects a fixed set of workspace files as project context into every turn automatically. These seven files form the agent's operating system:

• SOUL.md: personality, voice, values
• AGENTS.md: role, rules, lane
• MEMORY.md: what's active right now (one line per item, present tense)
• USER.md: how the user thinks and what they need
• TOOLS.md: machine-specific commands and workarounds
• IDENTITY.md: name, role, quick reference
• HEARTBEAT.md: standing tasks for recurring checks

The developer established a budget rule: while OpenClaw allows up to 20,000 characters per file, they target 500-1,000 tokens per file, keeping total L1 under 7,000 tokens. This ensures agents actually read everything instead of skimming bloated files. A trim command enforces this limit.

Stability rule: only the user or a checkpoint updates L1 files. Agents don't randomly change their own rules, with the exception that MEMORY.md can update to reflect current state.

Layer 2: Memory (semantic search)

This is long-term recall using OpenClaw's built-in memory_search tool that semantically searches across MEMORY.md and everything inside the memory/ directory. When an agent is asked about prior work, decisions, or context, it searches L2 automatically.

Two types of files live here:

• Daily notes: memory/YYYY-MM-DD.md (OpenClaw convention) containing session history, decisions made, completed work, and corrections
• Breadcrumb files: memory/[topic-name].md (developer addition) containing curated facts organized by situation, with 4KB max per file, one fact per line

Every key fact in breadcrumb files includes a pointer to L3: → Deep dive: reference/filename.md. This creates a bridge between L2 and L3 so agents don't need to load full reference documents just to remember one relevant fact.

Critical insight: L2 accuracy depends entirely on what gets written into it. If an agent takes an action and doesn't capture it before moving on, the state file starts returning stale information.

Layer 3: Reference (on-demand)

This is entirely the developer's addition, not an OpenClaw convention. A reference/ directory contains deep context: SOPs, frameworks, playbooks, and research.

Agents reach into L3 on demand when a specific task requires depth. It's not searched by memory_search by design to avoid burning context loading things that rarely matter.

The complete flow: L1 (always loaded) → search L2 (memory) → open L3 (reference) on demand.