OpenClaw Workspace Files: SOUL.md, MEMORY.md, AGENTS.md Explained (2026)

ByL.B. Kaelin

Out of the box, OpenClaw runs as a capable but generic AI agent. It processes messages, responds to commands, and executes tools. But it does not know who it is, what it should prioritize, or what happened in its last conversation. That is where workspace files come in.

The OpenClaw workspace is a directory on disk, typically located at ~/.openclaw/workspace/, that contains plain text files loaded into the agent’s context at every session start. These files are the difference between a throwaway chatbot and a production agent with memory, personality, and operational discipline. They define who the agent is, what it knows, and how it behaves.

This article covers every workspace file: what it does, how to write it, and what common mistakes to avoid. By the end you will know exactly how to configure an OpenClaw agent for any use case, from a personal assistant to a multi-agent production deployment.

How Workspace Files Work: Loaded at Session Start

When an OpenClaw agent receives a message (from Slack, Telegram, a cron trigger, or any configured channel), the gateway daemon injects the contents of the workspace files into the agent’s system prompt before the LLM processes the request. This means the agent reads these files fresh every single session. Every message, every cron trigger, every heartbeat.

This is a critical design decision. Because workspace files are loaded at session start, the agent never has to guess whether its instructions are current. Editing a workspace file takes effect on the next message. There is no recompile step, no restart required, no stale cache to clear. You modify a file on disk and the agent sees the new content within one session.

The default workspace path is ~/.openclaw/workspace/, but this is configurable in openclaw.json through the plugins configuration for memory and workspace settings. The directory does not need to exist before OpenClaw starts. The gateway creates it on first run if it does not exist yet.

Files are loaded in a specific order, but all files share the same context window. The agent sees SOUL.md, MEMORY.md, AGENTS.md, and any other workspace file as part of a single combined prompt. There is no “this file has priority over that file” rule within the workspace. Instead, you use each file for a different purpose and let the content itself establish precedence.

Not every file is required. OpenClaw works fine with a workspace directory containing only SOUL.md. Every other file is optional. But as your agent’s responsibilities grow, you will want each file for a specific reason.

SOUL.md: Your Agent’s Identity and Core Behaviors

SOUL.md is the most important file in the workspace. It defines who the agent is, what it values, and how it should behave in every situation. It is loaded at every session start without exception.

Think of SOUL.md as the agent’s constitution. It contains the rules that cannot be overridden by task-specific instructions. A well-written SOUL.md covers four areas:

  • Identity – Name, origin, purpose. The agent’s reason for existing.
  • Role – What the agent does and does not do. Domains of responsibility.
  • Values and principles – How the agent thinks. Prioritization frameworks. Decision-making heuristics.
  • Hard constraints – What the agent must never do. Safety rules. File permissions. Communication boundaries.

Here is a simplified example showing the structure of an effective SOUL.md:

# Agent Name - Role

## Identity

You are [Name]. Your job is [specific purpose].
You were created on [date] for [reason].
You are [tone - sharp? warm? clinical?].

## Core Behaviors

- [Behavior 1 with specific detail]
- [Behavior 2 with specific detail]
- [Boundary: what you never do]

## How You Make Decisions

[Framework or process the agent follows]

## Communication Rules

- [Who you talk to and how]
- [Format preferences]
- [Who you ignore]

## Critical Protections

- [File X] - Never modify without approval
- [File Y] - Append only, never overwrite

The key rule: keep SOUL.md under 3,000 tokens. Every session injects this file into the prompt, so a bloated SOUL.md eats into the context window available for the actual conversation. Be specific but concise. Prefer concrete rules (“Never modify openclaw.json without explicit approval”) over vague principles (“Be careful with configuration files”).

In multi-agent setups, SOUL.md requires explicit approval to modify. This is a safety mechanism, not a bureaucratic hurdle. If every agent could rewrite its own identity, the system would have no behavioral guarantees. The approval chain ensures that identity changes are deliberate and auditable.

MEMORY.md: Long-Term Memory That Persists Across Sessions

MEMORY.md is the agent’s long-term memory. It persists facts, decisions, preferences, task history, and lessons learned across every session. It is the only file in the workspace that grows continuously over time.

The file follows a strict append-only discipline. The agent never overwrites MEMORY.md. It only adds new content at the end, typically at the end of a session. This preserves the entire history of the agent’s operation and prevents information loss due to overwrites.

Each entry in MEMORY.md should include a date stamp and a topic label:

### 2026-04-27 - SEO Content Queue Built

- Created 105-item content queue for PrepperIntel
- Queue controller script at seo-queue/queue-controller.py
- Auto-refill threshold set at <20 remaining items
- RedRook queue verified intact: 105 items RR-001 to RR-105

Good things to store in MEMORY.md:

  • Facts about the user (name, timezone, preferences)
  • Decisions that should not be revisited every session
  • Task and proposal tracking (status, verdicts, next steps)
  • Infrastructure changes (cron jobs created, credentials updated)
  • Lessons learned (what worked, what broke, how it was fixed)
  • Project state (launch checklists, pipeline status, blockages)

Over time, MEMORY.md can grow large. OpenClaw handles this by loading only the most recent portion depending on context window limits. The full file stays on disk, but the agent sees the tail entries first, which means recent history is always available even when older entries get truncated.

The one rule that must never be broken: MEMORY.md is append-only. Never overwrite. Never replace. Every session adds to the record. This is non-negotiable because overwritten memory is permanently lost and there is no version control built into the filesystem layer.

AGENTS.md: The Operational Handbook

AGENTS.md is the operational protocol file. If SOUL.md is the agent’s constitution, AGENTS.md is its employee handbook. It contains session start and end procedures, communication routing rules, file permission boundaries, and task workflow instructions.

This file exists because agents in a multi-agent system need coordination protocols. A typical AGENTS.md includes:

  • Session start procedure – What files to read and in what order at the beginning of every session.
  • Session end procedure – What to write to MEMORY.md and where to deliver summaries.
  • Communication rules – Which agents to tag, which channels to use, which messages to keep concise.
  • File permission boundaries – Which directories the agent can read, write, or must never touch.
  • Task routing – How to receive tasks, where to deliver outputs, who evaluates results.
  • Slack and channel protocols – When to tag specific agents, how to format proposal announcements.

Here is an excerpt from a real AGENTS.md showing session start procedures:

## Session Start
1. Read SOUL.md
2. Read MEMORY.md
3. Check commons/agents/prism/ for monetization analysis tasks
4. Check commons/agents/scout/ for new market intelligence
5. Check commons/agents/gambit/ for execution feasibility reports
6. Only then respond to incoming messages or begin analysis

The session start procedure in AGENTS.md is critical because it ensures the agent has full context before it acts. Without this file, the agent might skip context gathering and respond immediately, losing important information from other agents or pending tasks.

HEARTBEAT.md: The Periodic Check-In File

HEARTBEAT.md is a checklist file used with OpenClaw’s cron-driven heartbeat system. A cron job sends a heartbeat message to the agent at regular intervals. The agent reads HEARTBEAT.md, executes each check in order, and either reports issues or replies with the exact string HEARTBEAT_OK.

The HEARTBEAT_OK reply is special. OpenClaw’s gateway monitors for this exact string and suppresses the notification when it appears. The agent checked in, everything is fine, and nobody gets pinged. Only when the agent finds something that needs attention does it trigger a visible notification.

A typical HEARTBEAT.md looks like this:

# Heartbeat Checklist
- Check agents/inbox for new tasks from other agents
- Check shared folders for pending files
- Check API health endpoints
- Check cron pipeline output for failures
- If nothing needs attention, reply HEARTBEAT_OK

This pattern enables silent 24/7 monitoring. You can run heartbeats every 30 minutes without notification fatigue. Your agent stays vigilant. You stay focused on your actual work.

Optional Files: IDENTITY.md, USER.md, TOOLS.md, BOOTSTRAP.md

Beyond the core files, OpenClaw supports several optional workspace files that serve specific purposes.

IDENTITY.md

IDENTITY.md lets an agent define a visual persona. It stores the agent’s name, creature type (AI, robot, digital familiar), vibe, emoji signature, and avatar path. This is purely cosmetic but valuable for agents that interact with users directly and need a consistent personality across sessions.

The file is simple:

# IDENTITY.md

- Name: (pick something you like)
- Creature: (AI? robot? familiar?)
- Vibe: (sharp? warm? chaotic?)
- Emoji: (your signature emoji)
- Avatar: (path or URL)

USER.md

USER.md stores information about the human the agent serves. Name, what to call them, timezone, pronouns, and contextual notes about their projects, preferences, and communication style.

This file is updated over time as the agent learns more about the user. It is the ethical alternative to storing personal information inside MEMORY.md where it gets mixed with operational data. Keeping user context in its own file makes it easier to review, correct, or reset.

# USER.md

- Name:
- What to call them:
- Timezone:
- Notes:

## Context

(What do they care about? What projects? What annoys them?)

TOOLS.md

TOOLS.md is the infrastructure cheat sheet. Skills define how tools work as a shared library. TOOLS.md stores the local specifics that are unique to one deployment: camera names and locations, SSH hosts and aliases, preferred TTS voices, speaker or room names, device nicknames, and anything environment-specific.

Separating this from skills means you can update either file independently. If a skill gets a new version, you keep your local notes. If you reconfigure your home network, you update TOOLS.md without touching the shared skill logic.

### Cameras

- living-room: Main area, 180 degree wide angle
- front-door: Entrance, motion-triggered

### TTS

- Preferred voice: Nova (warm, slightly British)
- Default speaker: Kitchen HomePod

BOOTSTRAP.md

BOOTSTRAP.md provides initial context for new sessions. It answers “what do I do first?” It is useful for agents that run specific onboarding procedures at session start, such as checking for new credentials, validating directory structure, or running initial diagnostic checks.

Not every agent needs BOOTSTRAP.md. It is most valuable for agents that operate autonomously and need to confirm their environment is ready before they begin their primary work.

The Cache Boundary: Static vs. Dynamic Context

OpenClaw caches workspace file content for performance. The cache boundary is an HTML comment placed directly into a workspace file that tells OpenClaw which parts to cache and which parts to load fresh each session.

The cache boundary uses the following marker:

<!-- OPENCLAW_CACHE_BOUNDARY -->

Everything above this line in a workspace file is cached and re-used across sessions. Everything below it is loaded fresh every session. This matters most for files like AGENTS.md or SOUL.md where you have both stable instructions and dynamic content.

The practical rule: put static, permanent facts above the cache boundary. Put dynamic data, current task state, and today’s date below it. This gives you the performance benefit of caching without the risk of the agent acting on stale task context.

The cache boundary is optional. Most agents never need it. But for production deployments with high session volumes and large workspace files, it can meaningfully reduce token consumption and latency on every message.

File Safety Rules: What Never to Overwrite

Workspace files live on a plain filesystem with no version control built in. A careless write can destroy months of accumulated context in milliseconds. OpenClaw’s safety rules exist to prevent exactly this.

Three rules are universal across all well-configured OpenClaw agents:

  1. SOUL.md is never modified without explicit approval. Identity changes require a deliberate decision from the user or a designated supervisor agent. This prevents runaway agents from rewriting their own personalities.
  2. MEMORY.md is append-only. Never overwrite or replace. Every session adds to the record. History is preserved. When old entries are truncated from context, the file on disk still contains the full record for reference.
  3. openclaw.json is never modified without explicit approval. The configuration file controls model routing, channel access, security permissions, and cron schedules. Unauthorized changes risk the entire deployment.

Additional safety rules can be defined per-agent in SOUL.md or AGENTS.md. Common examples include: never write to another agent’s workspace directory, never install plugins without approval, and never edit files outside assigned directories.

These rules are not suggestions. They are enforced through the agent’s system prompt. If an agent is instructed at every session start that MEMORY.md must never be overwritten, it will refuse to do so even if a downstream task instruction conflicts. The workspace file content always takes precedence over task-specific prompts because it is loaded earlier in the context and establishes the agent’s behavioral foundation.

Writing Good Workspace Files: Principles and Examples

A poorly written workspace file is worse than no file at all. A vague instruction (“be helpful”) produces vague behavior. A specific, well-structured file produces reliable, predictable agent behavior. Here are the principles that separate effective workspace files from ineffective ones.

Be specific, not vague

Bad: “Prioritize important tasks.”
Good: “Prioritize tasks in this order: revenue-impacting issues first, user requests second, self-maintenance third.”

The agent does not infer meaning. It follows instructions literally. If you say “be careful with configuration,” that means nothing to an LLM. If you say “never edit openclaw.json without asking the user first,” that produces guardrails the agent can actually follow.

Include examples, not just rules

Every rule in a workspace file should be paired with a concrete example. Show the agent what a correct output looks like. Show it what a forbidden action looks like. Examples anchor abstract rules in specific behavior the agent can reproduce.

Bad: “Write good session summaries.”
Good: “At session end, write to MEMORY.md with this format: ### [date] [topic] then bullet points for key actions, decisions, and next steps.”

Use markdown headers

Workspace files are read by the agent, not by a visual UI. Markdown headers (H2, H3) structure the content for the agent’s comprehension. A well-structured file with clear section headers helps the agent find the relevant instructions faster and follow them more accurately.

Keep SOUL.md under 3,000 tokens

SOUL.md loads into every session context. If it exceeds 3,000 tokens, it crowds out the actual conversation. Be ruthless about trimming. Put operational procedures in AGENTS.md, not SOUL.md. Put task-specific context in temporary workspace files, not SOUL.md.

Use the cache boundary for dynamic content

If your AGENTS.md or SOUL.md has sections that change frequently (task lists, daily briefings, status updates), put those sections below the <!-- OPENCLAW_CACHE_BOUNDARY --> marker. The static identity and rules stay in the cached portion. The dynamic data loads fresh every session.

Separate agent context from web publishing

Workspace files use markdown freely because only the agent reads them. But if your agent writes to WordPress or similar CMS, all published content must be pure HTML. Markdown syntax (##, bold with **, markdown-style links) will render as literal text on the page. The safest approach is to include a markdown-to-HTML conversion step in your publishing pipeline and verify no raw markdown syntax exists before sending.

Sources

This article draws from direct analysis of live OpenClaw workspace files and agent behavior in a production multi-agent deployment. For additional context on the broader OpenClaw ecosystem:

Similar Posts