Blog

OpenClaw internal memory files: what each one does

OpenClaw can keep stable behavior across sessions, but only if your workspace files are structured correctly. This guide explains each internal-memory file, what to put in it, and the config switches that matter.

The short map

In a standard workspace, these files define behavior, identity, tools, cadence, and memory: AGENTS.md, SOUL.md, USER.md, IDENTITY.md, TOOLS.md, HEARTBEAT.md, BOOT.md, BOOTSTRAP.md, MEMORY.md, and daily logs in memory/YYYY-MM-DD.md.

Per-file guide

AGENTS.md

Primary instruction file. Keep this as your top-level operating contract: priorities, boundaries, workflow, and quality bar.

Tip: put stable rules here, not temporary tasks.

SOUL.md

Behavioral core. Define voice, temperament, values, and non-negotiable constraints that should stay consistent over time.

Tip: use this for personality and ethics, not project tickets.

USER.md

User-facing preferences and style defaults: communication tone, output formatting, recurring preferences, known constraints.

Tip: treat it as the personalization layer.

IDENTITY.md

Structured identity profile (name, role, goals, voice). Useful when you want to re-apply a known identity consistently.

Config: apply with openclaw agents set-identity --from-identity.

TOOLS.md

Operational environment notes for tools: host quirks, path conventions, aliases, risky commands, and adapter behaviors.

Tip: keep this practical and environment-specific.

HEARTBEAT.md

Defines periodic heartbeat behavior (check cadence + ritual). Good for recurring scans, reminders, and passive maintenance loops.

Config: tune cadence with agents.defaults.heartbeat.every.

BOOT.md

Startup ritual prompt for boot hooks. This is optional and only runs when internal hooks are enabled.

Config: enable hooks via hooks.internal.enabled: true and openclaw hooks enable boot-md.

BOOTSTRAP.md

First-run interview script for gathering identity/context and writing the initial workspace files from that conversation.

Config: skip after setup with agent.skipBootstrap: true when managing files manually.

MEMORY.md

Long-lived memory document for persistent facts and compressed history that should survive daily churn.

Config: memory flush behavior is controlled with agents.defaults.compaction.memoryFlush.

memory/YYYY-MM-DD.md

Daily working memory notes. OpenClaw auto-preprompts today's file and can pull older notes through memory search.

Config: extend search roots with agents.defaults.memorySearch.extraPaths.

Recommended configuration workflow

Initialize templates once: openclaw setup.
Set workspace location explicitly if needed: agents.defaults.workspace.
Fill AGENTS.md, SOUL.md, USER.md, and TOOLS.md first.
Apply identity profile from IDENTITY.md with openclaw agents set-identity --from-identity.
Enable optional flows (BOOT.md hook and HEARTBEAT.md cadence) only if you need them.
Keep durable truths in MEMORY.md, short-lived context in daily memory/ notes.

Common mistakes to avoid

Putting temporary task lists in SOUL.md (creates unstable behavior).
Overloading AGENTS.md with personal preferences that belong in USER.md.
Treating MEMORY.md like a raw transcript instead of a compact, maintained memory.
Enabling boot hooks without defining a clear BOOT.md ritual.