Workspace Boot

Type: OpenClaw session initialization mechanism

Definition

At every session start, the agent reads a set of files from the workspace to restore identity, context, and operating procedures. SOUL.md provides identity (tone, principles, domain expertise), MEMORY.md provides persistent cross-session facts, AGENTS.md defines routing rules and agent configurations, and USER.md provides operator context. These files are read fresh at each session start — they are not stored in conversation history but loaded from disk at initialization time.

How It Works

When a session starts (or when the agent is invoked after a long gap), the Gateway loads the workspace by reading key files in order. First, SOUL.md — the agent's identity file that defines who it is, how it communicates, what principles guide it, and what domain expertise it has. This shapes all behavior going forward. Second, AGENTS.md — the operating manual that defines the router's role, named agents, routing rules, quality gates, and escalation protocol. Third, MEMORY.md — persistent cross-session memory storing routing decisions, operator preferences, system configuration, and known issues. Fourth, USER.md — profile information about the operator (name, timezone, professional context, goals).

Beyond these core files, the workspace convention also includes: memory/ folder with daily logs (memory/YYYY-MM-DD.md), projects/ folder for active work with per-project context files, protocols/ for operating procedures like HEARTBEAT.md, and data/ for structured JSON/CSV files.

The key insight is that these files drive behavior but are NOT stored in conversation history. If SOUL.md is updated, the agent's behavior changes immediately on the next session — without requiring a restart. This makes the workspace the single source of truth for agent configuration and memory.

Config files are layered: openclaw.json controls runtime behavior (needs restart on change), while SOUL.md, AGENTS.md, MEMORY.md, and USER.md are hot-reloaded at each session start with no restart required.

Key Properties

  • Hot-reload at session start — SOUL/MEMORY/AGENTS/USER are read fresh each session; no restart needed
  • Layered config — openclaw.json needs restart; SOUL/MEMORY/AGENTS/USER do not
  • Five canonical workspace files — SOUL.md, AGENTS.md, MEMORY.md, USER.md, TOOLS.md
  • Workspace directory structure — memory/ (daily logs), projects/ (context files), protocols/ (procedures), data/ (structured data)
  • Identity restoration — SOUL.md shapes tone, principles, and domain expertise at every session
  • Cross-session persistence — MEMORY.md survives session restarts; conversation history does not
  • five-layer-memory — workspace files map to the 5-layer memory system's layers 1-3
  • kelly-router — the Router reads AGENTS.md to understand routing rules and agent configurations
  • daily-logs — memory/YYYY-MM-DD.md daily logs are part of the workspace structure

Source Chapters