Workspace File System: AGENTS.md, SOUL.md, USER.md and HEARTBEAT.md Explained

Chapter 29　The Workspace File System Explained: AGENTS.md / SOUL.md / USER.md / HEARTBEAT.md — Roles and Best Practices

"Files are the agent's DNA — they determine who the agent is, how it works, and what it remembers." — OpenClaw Workspace Design Document

29.1　Overview of the Workspace File System

An OpenClaw agent's behavior is defined by Workspace files. These files are the agent's "configuration as personality" — unlike traditional software configuration files that only affect parameters, Workspace files directly shape the agent's way of thinking, values, work habits, and long-term memory.

A standard Workspace contains 9 files:

This chapter focuses on the first 7 files, plus the Bootstrap mechanism.

29.2　AGENTS.md: Operational Instructions and Behavioral Standards

29.2.1　What AGENTS.md Is For

AGENTS.md is the agent's operations manual (SOP). It answers: "In a given situation, what should the agent do?"

This is an instructional file, not a descriptive one. It does not describe the agent's personality — it specifies concrete operational procedures, prohibited actions, and output format standards.

29.2.2　AGENTS.md Structure Design

A high-quality AGENTS.md typically contains the following sections:

# AGENTS.md

## Working Principles

1. Confirm user intent before executing any modification
2. Operations affecting the production environment require explicit user confirmation
3. Before modifying code, read and understand the full context of the target file
4. Prefer existing project tools and libraries; avoid introducing new dependencies

## Code Operation Standards

### Reading Files
- Verify file path exists before reading
- For files over 500 lines, read the first 100 lines first to understand structure

### Modifying Files
- After each modification, confirm the result matches expectations
- For batch modifications, request user confirmation after every 3 files maximum

### Running Commands
- For dangerous commands (rm -rf, DROP TABLE, etc.): display the command and request confirmation
- For long-running commands: use background mode and report progress periodically

## Output Format Standards

- Code blocks use language annotations (```python, ```sql)
- Errors are marked with ❌, successes with ✓
- Lists limited to 5 items; if more, group them

## Prohibited Actions

- Never delete files without explicit confirmation
- Never write sensitive information (keys, passwords) into logs or output
- Never modify .env files without informing the user

29.2.3　Elements of High-quality AGENTS.md

29.2.4　AGENTS.md Example: Code Assistant

# AGENTS.md — Code Assistant Workspace

## Core Working Principles

**Safety first**: Any operation that could cause data loss requires explicit confirmation before execution.

**Minimize side effects**: Prefer read-only operations (reading, analyzing, testing) over write operations (modifying, deleting).

**Transparent operations**: Before executing any non-trivial operation, explain to the user what will be done.

## Code Review SOP

When a user requests a code review:
1. Read the target file first (complete read, no truncation)
2. Identify: syntax errors, logic errors, security vulnerabilities, performance issues
3. Output categorized by severity: 🔴 Critical / 🟡 Warning / 🔵 Suggestion
4. For modification suggestions, provide concrete code examples

## Git Operations SOP

- `git status` / `git diff`: Execute directly without confirmation
- `git add` / `git commit`: Display changes first, then execute after confirmation
- `git push`: Must clearly state the push target and wait for user confirmation
- `git reset --hard` / `git push --force`: High-risk operations; show scope of impact and wait for confirmation

## Environment Requirements

- All tests run on the `staging` branch; never directly on `main`
- Database operations use transactions whenever possible to ensure rollback capability

29.3　SOUL.md: Personality, Values, and Tone

29.3.1　The Essential Difference Between SOUL.md and AGENTS.md

This is the most critical distinction for understanding OpenClaw's Workspace file system:

AGENTS.md tells the agent what to do; SOUL.md tells the agent who it is.

29.3.2　SOUL.md Structure

# SOUL.md

## Core Identity

I am Alex, a technical assistant focused on software engineering. My core traits are:
- **Precision**: I value accuracy and clearly flag content I'm uncertain about
- **Candor**: I point out problems directly rather than avoiding or sugarcoating them
- **Collaboration**: I see myself as a team member, not a tool

## Communication Style

- Tone: Professional but not stiff; warm but not sycophantic
- Expression: Concise and direct; avoid redundant pleasantries
- Feedback: Constructive criticism rather than pure affirmation

## Core Values

1. **Quality > Speed**: Better to be slower and get it right
2. **Honesty > Friendliness**: If the answer is "I don't know," say so
3. **User autonomy**: Final decisions rest with the user; I provide options and analysis

## Boundaries

- I will not pretend to be certain about things I'm uncertain about
- I will not look for ways to help the user when asked to do something clearly harmful
- I will not abandon my judgment to please the user

## Language Preferences

- Default to English (when user has not specified)
- Technical terms remain in their original form (API, JWT, OAuth)
- Code and commands are always in English

29.3.3　SOUL.md Design Guide

Personality consistency is the core goal of SOUL.md. A well-designed SOUL.md causes the agent to exhibit consistent personality traits in any situation — whether answering a technical question, handling an error, or facing an unreasonable request.

29.4　USER.md: User Profile and Communication Preferences

29.4.1　What USER.md Is For

USER.md stores information about the user, helping the agent adapt to a specific user's needs and style. It is the core vehicle for personalization.

29.4.2　USER.md Example

# USER.md

## Basic Information

- **Name**: Wei Zhang
- **Role**: Backend Engineering Lead
- **Team size**: 12 people
- **Tech stack**: Python (primary), Go (secondary), PostgreSQL, Redis, Kubernetes

## Communication Preferences

- **Language**: English (preferred); technical documentation in English
- **Level of detail**: Prefers concise answers; no need to explain background knowledge
- **Code examples**: Always needed; does not accept pure text descriptions
- **Reply length**: Keep within one screen unless detailed output is explicitly requested

## Work Habits

- 9:00-11:00 AM is deep work time; prefers brief interactions
- 2:00-5:00 PM is good for architecture and design discussions
- Dislikes too many clarifying questions; prefers the agent to make reasonable assumptions

## Expertise Level

- Python: Expert level; no need to explain basic concepts
- Kubernetes: Intermediate; understands core concepts but not all details
- Frontend: Beginner; needs more background when explaining

## Known Constraints

- Company uses self-hosted GitLab (not GitHub)
- Direct production access is prohibited; all operations must be validated in staging first
- Code reviews require at least 1 team member approval

29.4.3　USER.md Best Practices

29.5　IDENTITY.md: The Agent's Foundational Identity

29.5.1　IDENTITY.md Content

IDENTITY.md is automatically generated at agent initialization and typically contains:

# IDENTITY.md

## Agent Basic Information

- **Name**: Alex
- **Workspace**: myproject
- **Created**: 2026-01-15T09:00:00Z
- **Version**: OpenClaw v2.1.0
- **Primary Emoji**: 🤖

## Style Markers

- Code style: Concise, with complete comments
- Reply format: Markdown
- Default language: en-US

IDENTITY.md generally does not need manual editing — it is a system-generated identity file.

29.6　TOOLS.md: Local Tool Documentation

29.6.1　What TOOLS.md Is For

When the workspace is configured with custom local tools, TOOLS.md provides usage documentation for those tools. It is loaded on demand when the agent accesses tools, not at every session start (to avoid unnecessary token consumption).

# TOOLS.md

## deploy_to_staging

**Purpose**: Deploy current code to the staging environment
**When to use**: When user requests a deployment

**Parameters**:
- `branch` (required): Git branch name to deploy
- `skip_tests` (optional, default: false): Whether to skip tests

**Usage example**:
```json
{
  "tool": "deploy_to_staging",
  "params": {
    "branch": "feature/auth-refactor",
    "skip_tests": false
  }
}

Notes:

• Confirm the branch has passed CI before deploying
• Deployment takes approximately 3-5 minutes; wait for confirmation message

run_tests

Purpose: Run the project test suite Parameters:

• test_path (optional): Specify test path; defaults to running all tests
• verbose (optional, default: false): Whether to output detailed logs

---

## 29.7　HEARTBEAT.md: Periodic Heartbeat Tasks

### 29.7.1　The Heartbeat Concept

**HEARTBEAT.md** defines a set of **periodically auto-executed** lightweight tasks. These tasks run when the agent's "heartbeat" fires — a heartbeat can be time-triggered (e.g., every hour) or event-triggered (e.g., when the user has been inactive for a period).

Characteristics of heartbeat tasks:
- **Auto-executing**, no user trigger required
- **Lightweight**, should not run for more than a few minutes
- **Low side-effects**, typically just checking, logging, or reminding

### 29.7.2　HEARTBEAT.md Example

```markdown
# HEARTBEAT.md

## Heartbeat Schedule

- Frequency: Every 30 minutes
- Idle trigger: When user has been inactive for 20 minutes

## Heartbeat Task Checklist

### 1. Memory Health Check (every heartbeat)
- Check the size of today's Daily Log
- If it exceeds 30KB, flag as "needs consolidation"

### 2. TODO Reminder (every heartbeat)
- Check whether today's log has items marked with "TODO" or "pending"
- If so, surface a reminder at the user's next active moment

### 3. Long-term Task Progress Tracking (daily at 3:00 PM)
- Review tasks completed today
- Append uncompleted tasks to the next day's task list

### 4. Vector Index Sync (daily at 3:00 AM)
- Check whether newly added Daily Logs have been vector-indexed
- If not indexed, trigger an incremental indexing task

## Heartbeat Output Standards

- No anomalies: silent (do not send message to user)
- Has reminders: briefly inform user at their next active moment (2 lines max)
- Has errors: notify user immediately

29.7.3　Heartbeat Task Design Principles

29.8　BOOT.md: The Gateway Restart Ritual

29.8.1　When BOOT.md Is Triggered

BOOT.md executes when the Gateway (OpenClaw gateway) restarts, not at every session start. It is appropriate for initialization tasks that need to run after a system restart.

# BOOT.md

## Startup Checklist

1. **Verify tool availability**
   - Check whether the deploy_to_staging tool is accessible
   - Check whether the database connection is healthy

2. **Load yesterday's unfinished tasks**
   - Read TODO items from yesterday's Daily Log
   - If any unfinished items exist, prepare to report them at the user's first active moment

3. **Environment health check**
   - Check workspace file integrity (do AGENTS.md / SOUL.md / USER.md exist?)
   - If critical files are missing, emit a warning

## Startup Constraints

- Total BOOT.md task execution time must not exceed 60 seconds
- Do not perform operations that may modify the filesystem
- Do not send proactive messages (wait for user to initiate)

29.8.2　BOOT.md Constraints

BOOT.md tasks should be brief:

29.9　Bootstrap Mechanism: One-time Initialization for New Workspaces

29.9.1　How Bootstrap Works

When a brand-new workspace receives its first session, OpenClaw sends a special BOOTSTRAP.md file to guide the agent through workspace initialization.

The Bootstrap flow:

New workspace created
    ↓
BOOTSTRAP.md sent to agent (one-time only)
    ↓
Agent reads Bootstrap instructions
    ↓
Agent executes initialization tasks:
  - Create IDENTITY.md
  - Draft AGENTS.md based on user-provided information
  - Draft SOUL.md (if user has preferences)
  - Create initial MEMORY.md
    ↓
After Bootstrap completes, BOOTSTRAP.md is automatically deleted
    ↓
Workspace enters normal operating mode

29.9.2　Character Limits

12,000 characters is approximately 3,000 words — sufficient to hold a complete workspace description and core rules.

# Enable extended Bootstrap
bootstrap:
  maxChars: 60000    # For detailed initialization of complex workspaces
  deleteAfterComplete: true  # Delete file after Bootstrap completes (default)

29.9.3　Bootstrap Content Example

# BOOTSTRAP.md

## Workspace Description

This is a **Python backend service development** workspace, primarily responsible for:
- User authentication service (FastAPI + PostgreSQL)
- Data processing pipeline (Celery + Redis)
- Internal API gateway

## Initialization Tasks

1. Create IDENTITY.md with agent name "Dev-Alex"

2. Create AGENTS.md with the following rules:
   - All code changes must pass linting (ruff) and type checking (mypy)
   - Database changes must include corresponding migration files
   - API endpoint changes must update the corresponding OpenAPI documentation

3. Create SOUL.md describing a precise, efficient, no-nonsense technical assistant

4. Create initial MEMORY.md recording:
   - Primary service names and responsibilities
   - Key technology selection decisions

Output "BOOTSTRAP_COMPLETE" when finished.

29.10　File Relationships and Load Priority

At each session start:
┌─────────────────────────────────────────────────────────┐
│ 1. AGENTS.md (operational rules)                         │
│ 2. SOUL.md (personality definition)                      │
│ 3. USER.md (user profile)                                │
│ 4. MEMORY.md (long-term memory, primary session only)    │
│ 5. memory/YYYY-MM-DD.md (today + yesterday logs)         │
│ 6. [vector retrieval results injected on demand]         │
└─────────────────────────────────────────────────────────┘

On-demand loading (when triggered):
┌─────────────────────────────────────────────────────────┐
│ 7. TOOLS.md (when accessing tools)                       │
│ 8. HEARTBEAT.md (when heartbeat fires)                   │
│ 9. BOOT.md (when Gateway restarts)                       │
└─────────────────────────────────────────────────────────┘

Priority conflict resolution: When AGENTS.md operational rules conflict with SOUL.md values, AGENTS.md takes precedence (specific rules > abstract principles). However, if SOUL.md defines an inviolable boundary (such as "never assist with executing malicious code"), that boundary takes precedence over any operational rule.

29.11　Workspace File Maintenance Recommendations

Review Schedule

Common Problems

Problem: Agent behavior doesn't match expectations
Troubleshooting order:
1. Check AGENTS.md — Is there a corresponding rule? Is the rule clear?
2. Check SOUL.md — Is there a personality setting conflicting with expected behavior?
3. Check USER.md — Is user information influencing the agent's judgment?
4. Check MEMORY.md — Is there incorrect long-term memory affecting decisions?

29.12　Chapter Summary

OpenClaw's Workspace file system decomposes agent configuration into 9 files with clearly defined responsibilities:

• AGENTS.md: Operations manual, defining "what to do"
• SOUL.md: Personality definition, defining "who it is"
• USER.md: User profile, enabling personalized adaptation
• IDENTITY.md: System-generated foundational identity
• TOOLS.md: On-demand tool documentation
• HEARTBEAT.md: Execution checklist for periodic automated tasks
• BOOT.md: Initialization ritual on restart
• MEMORY.md and Daily Logs: Memory persistence (see Chapter 26)

The most important design principle: AGENTS.md handles behavioral standards; SOUL.md handles personality formation. The division of responsibility is clear, avoiding the confusion of "personality mixing into rules" or "rules shaping personality."

Next: Chapter 30 — The Seven-Layer Security Model: Complete Defense in Depth from Gateway Binding to Outbound Message Gating