OpenClaw Workspace Files Explained: SOUL.md, AGENTS.md, HEARTBEAT.md and More

You deployed OpenClaw. You have a folder. It has a bunch of .md files and you're not entirely sure what each one actually does.

This is the guide that answers that. Every file, what it controls, what happens if you skip it, and a real example of each. Bookmark it — you'll come back.

What Are OpenClaw Workspace Files?

OpenClaw agents don't live in databases or configuration panels. They live in plain text files inside a workspace folder. When OpenClaw starts an agent session, it reads these files and assembles the agent's identity, behavior rules, memory, and task schedule on the fly.

This means you can edit your agent with any text editor. Version-control it with Git. Copy it to another server and have an identical agent running in minutes. The files are the agent.

Here's the full set:

my-agent/
├── SOUL.md
├── IDENTITY.md
├── AGENTS.md
├── USER.md
├── TOOLS.md
├── HEARTBEAT.md
└── MEMORY.md

Let's go through each one.

SOUL.md — Who Your Agent Is

SOUL.md defines your agent's personality, values, tone, and behavioral boundaries. It's the first file OpenClaw injects into the agent's context at the start of every session.

Think of it as the "character sheet." Without it, your agent is just a raw language model with no persistent identity.

What it controls:

• Name and role ("You are Aria, a customer support agent for...")
• Tone and communication style
• Hard limits ("Never discuss competitor pricing", "Always recommend consulting a professional for legal questions")
• Core behaviors ("Teach first, sell second", "Always cite sources")

Real example snippet:

# SOUL.md

## Who You Are
You are Aria, the customer support agent for Meridian SaaS.
You answer billing questions, help with onboarding, and escalate
technical issues to the engineering queue.

## Tone
Direct, friendly, patient. Never condescending. Admit when you
don't know something — and say you'll find out.

## Hard Limits
- Never share internal pricing formulas
- Never promise refunds without checking USER.md for approval levels
- Always recommend a human review for any disputed charge over EUR 100

What happens if you skip it: Your agent will still work, but it'll behave like a generic AI assistant with no defined role. Every session starts fresh with no character. Fine for testing. Not fine for production.

IDENTITY.md — Display Info and Agent Metadata

IDENTITY.md is the lightweight public-facing card. It stores the agent's name, ID, role label, and any metadata OpenClaw needs to identify and route the agent correctly.

What it controls:

• Agent name (how it signs messages)
• Agent ID (used for routing in multi-agent setups)
• Role label
• Avatar or display info (platform-dependent)

Real example:

# IDENTITY.md

**Name:** Aria
**Agent ID:** support
**Role:** Customer Support Agent for Meridian SaaS

This file is short by design. Heavy behavior logic belongs in SOUL.md and AGENTS.md.

AGENTS.md — The Operating Manual

AGENTS.md is where you put the procedural rules. If SOUL.md answers "who are you?", AGENTS.md answers "what do you do and how?"

This is the largest and most important file for agents with complex workflows.

What it controls:

• Session behavior (what to do at the start/end of each session)
• Memory rules (what to log, what to remember long-term)
• File access patterns (what the agent reads/writes and when)
• Workflow steps (numbered procedures for common tasks)
• Multi-agent coordination (how this agent hands off to others)

Real example snippet:

# AGENTS.md - Aria Operating Manual

## Every Session
1. Read USER.md for any flagged priority issues
2. Check memory/YYYY-MM-DD.md for today's context
3. Load open ticket queue from /data/tickets.json

## Ticket Workflow
1. Greet the user, confirm the issue
2. Check MEMORY.md for known patterns
3. Resolve if in scope (see SOUL.md boundaries)
4. Escalate via Slack #eng-escalations if not
5. Log resolution summary to today's memory file

## Memory Rules
- Log all resolved tickets with outcome
- Flag repeated issues (3+ similar in a week) in MEMORY.md

Common mistake: Dumping everything into SOUL.md when it belongs in AGENTS.md. Personality in SOUL, procedures in AGENTS.

USER.md — What the Agent Knows About You

USER.md gives the agent context about the human it's working with. This is what makes an agent feel like it actually knows you, rather than starting cold every session.

What it controls:

• Name, timezone, location
• Background and expertise level
• Preferences ("Rob likes concise replies, no padding")
• Access levels ("Can approve refunds up to EUR 50 without escalating")

Real example:

# USER.md

**Name:** Roberto (Rob)
**Timezone:** Asia/Makassar (UTC+8) — Bali, Indonesia
**Background:** Software developer, 35+ years in IT
**Preferences:** Direct answers. No filler. Real examples over theory.
**Refund authority:** Can approve up to EUR 50 without manager approval

This file stays static until you manually update it. It's not a live database — it's a context card the agent reads each session.

TOOLS.md — What the Agent Can (and Can't) Use

TOOLS.md documents which tools your agent has access to and any usage notes specific to your setup. It's part documentation, part instruction set.

What it controls:

• Available tools list (read, write, exec, browser, etc.)
• Usage notes ("Always set exec timeout to 300s for image generation")
• External service configs ("Use GOG_KEYRING_PASSWORD env var for Drive uploads")
• What the agent should NOT try to do ("No browser access — research is Scout's job")

This file doesn't grant or revoke permissions — OpenClaw handles that in config. TOOLS.md tells the agent how to use the tools it already has, and which ones to reach for when.

HEARTBEAT.md — Recurring Tasks Without Manual Triggers

HEARTBEAT.md defines tasks that run on a schedule. Think of it as cron for your agent, expressed in plain English.

What it controls:

• Polling tasks ("Check disk usage every 30 minutes, alert if over 85%")
• Monitoring ("Verify SSL cert expiration weekly, log result")
• Scheduled reports ("Every Monday at 8am, send Rob a ticket volume summary")
• Health checks ("If no heartbeat response in 60 minutes, send alert to admin")

Real example:

# HEARTBEAT.md

## Checks

Every 30 minutes:
- Verify /data/tickets.json is writable
- Log active session count to memory/health.log

Every Monday at 08:00 UTC+8:
- Generate weekly ticket summary from memory logs
- Send summary to Rob via Telegram

On startup:
- Confirm all required files exist (SOUL.md, USER.md, AGENTS.md)
- Log startup timestamp to memory

What happens if you skip it: Nothing breaks. Your agent just won't do anything proactively. Every interaction requires a manual trigger.

MEMORY.md — Long-Term Memory

MEMORY.md is the agent's persistent memory store. It's where patterns, preferences, and important facts accumulate over time.

Unlike USER.md (which is static context you write), MEMORY.md grows as the agent works. You can seed it with starting information, and the agent appends to it based on rules in AGENTS.md.

What it controls:

• Long-term facts the agent should always remember
• Patterns discovered over time ("Users in APAC timezone tend to ask billing questions on Monday mornings")
• Preferences calibrated through use ("Rob prefers daily summaries at end of day, not morning")
• Important one-off context ("Server migration scheduled for March 15 — warn users if asked about downtime")

Daily working notes live in memory/YYYY-MM-DD.md files. MEMORY.md is for things that matter across weeks and months.

The Config Snippet — Wiring It All Together

Outside the workspace folder, there's a JSON config block that tells OpenClaw where the workspace lives, which channels to connect, and what tools to enable. This is generated by the wizard along with the markdown files.

It references the workspace folder path, assigns channel IDs, and sets tool permissions. Without it, OpenClaw doesn't know the agent exists.

Common Mistakes

Putting procedures in SOUL.md. SOUL.md is for personality and limits. Numbered workflows belong in AGENTS.md. Mixing them makes both files harder to maintain.

Leaving USER.md empty. Your agent will work, but every session starts with zero context about you. Five minutes filling this in saves hours of re-explaining preferences.

Not seeding MEMORY.md. An empty MEMORY.md is fine — but pre-loading it with known facts (your timezone, your naming conventions, key contacts) makes the agent useful immediately instead of after a week of calibration.

Over-engineering HEARTBEAT.md. Start with 1-2 checks. It's easy to add more. It's harder to debug an agent that's constantly doing things you forgot you told it to do.

Sharing workspace files publicly without redacting USER.md. That file has real information about you. Keep it out of public repos.

Security Guardrails

Never put API keys, passwords, or tokens in workspace files. These are plain text files — they should never contain secrets. Use environment variables or your server's secret manager. Reference them in TOOLS.md as $ENV_VAR_NAME, never inline.

Scope your tool permissions tightly. If your support agent doesn't need exec access, don't enable it. OpenClaw lets you restrict tools per-agent in the config — use that.

Review AGENTS.md before production. Poorly written workflow instructions can cause agents to take unintended actions. Test in a sandboxed environment first.

Set meaningful limits in SOUL.md. Explicit "never do X" rules in SOUL.md are a last line of defense against prompt injection and unexpected inputs.

Generate Your Workspace in 5 Minutes

Writing these files from scratch takes time. OpenAgents.mom generates the complete set through a guided interview -- you answer questions about your agent's purpose, personality, channels, and tools. You get a ready-to-deploy ZIP with all seven files and the config snippet.

It takes about 5 minutes. Compare that to a day of reading docs and trial and error.