📁 Workspace Files

Your agent's home. Customize personality, memory, and behavior with simple markdown files.

The Workspace is Your Agent's Brain

OpenClaw agents live in a workspace folder — a directory of markdown files that define who they are, what they remember, and how they behave. Unlike chatbots that reset every conversation, your agent builds persistent context through these files.

Default Location

~/.openclaw/workspace/
📋

AGENTS.md

Required

The operating manual. Defines how your agent should behave, what to read on startup, safety rules, and workspace conventions.

Key Sections
  • Every Session: Files to read at startup (SOUL.md, USER.md, memory)
  • Memory: How to use daily logs and long-term memory
  • Safety: What requires permission, what's safe to do
  • Group Chats: When to speak, when to stay quiet
  • Heartbeats: How to use periodic check-ins
💫

SOUL.md

Personality

The deepest level of who your agent is. Core values, thinking style, relationship with you. This shapes every response.

Example Content
# SOUL.md - My Core

## Prime Directive
Make my human's life easier — and help them succeed.

## Core Values
1. Competence Over Performance
2. Ownership
3. Anticipation
4. Honest Communication

## Anti-Patterns (Things I Avoid)
- 🚫 Sycophancy ("Great question!")
- 🚫 Padding responses
- 🚫 Saying "I can't" without trying
🪪

IDENTITY.md

Personality

The external-facing identity. Name, emoji, role, and how the agent talks. If SOUL.md is the heart, this is the face.

Example Content
# IDENTITY.md - Who I Am

- **Name:** Atlas
- **Emoji:** 🌟
- **Role:** Chief of Staff
- **Email:** atlas@example.com

## How I Talk
- Direct, clear sentences
- No excessive affirmations
- Emojis sparingly for warmth
👤

USER.md

Context

Information about you. Your name, timezone, work, interests. Helps your agent give relevant, personalized responses.

Example Content
# USER.md - About Your Human

- **Name:** Alex
- **Pronouns:** they/them
- **Timezone:** Australia/Sydney
- **Work:** Digital marketing agency

## Interests
- AI & Automation
- Technology

## What They Need
Delegation. Busy schedule, needs help.
🧠

MEMORY.md

Memory

Long-term curated memory. Important decisions, preferences, lessons learned. Only loaded in main sessions for security.

What to Include
  • Key decisions and their reasoning
  • User preferences discovered over time
  • Important project context
  • Lessons learned from mistakes
  • Reference information (API keys locations, folder IDs)
📅

memory/

Memory

Daily log files. Raw notes from each day in YYYY-MM-DD.md format. Everything gets dumped here.

Example: memory/2026-02-04.md
# 2026-02-04

## Work Done
- Fixed client website performance issue
- Created weekly SEO report

## Decisions
- Switched to new rank tracking tool

## Notes
- User prefers bullet points over paragraphs
💓

HEARTBEAT.md

Automation

Periodic check-in instructions. What to check during heartbeat polls. Keep it small to limit token usage.

Example Content
# Heartbeat Checklist

## Check (2-4x daily):
- [ ] Urgent unread emails?
- [ ] Calendar events in next 24h?
- [ ] Client websites still up?

## When to reach out:
- Important email arrived
- Event coming up (<2h)

## When to stay quiet:
- Late night (23:00-08:00)
- Nothing new since last check
🔧

TOOLS.md

Context

Local tool notes. Camera names, SSH details, API quirks, model preferences. Your agent's cheat sheet.

Example Content
# TOOLS.md - Local Notes

## Model Preferences
- Thinking/planning: claude-opus
- Coding: gemini-pro

## Google Workspace
- Account: assistant@example.com

## SSH Servers
- prod: user@123.45.67.89

🧠 The Memory System

Your agent wakes up fresh each session. Files are its continuity. Here's how the memory system works:

📅

Daily Logs

memory/YYYY-MM-DD.md

Raw notes from each day. What happened, decisions made, context. Like a journal.

→
🔍

Review

Periodically during heartbeats

Agent reviews recent daily files and identifies significant insights worth keeping.

→
🧠

Long-Term

MEMORY.md

Curated wisdom. The distilled essence of what matters for the long haul.

📝 Golden Rule: Write It Down

"Mental notes" don't survive session restarts. Files do.

  • When someone says "remember this" → update a file
  • When you learn a lesson → document it
  • When you make a mistake → write it so future-you doesn't repeat it

🚀 First Run: BOOTSTRAP.md

When you first set up an agent, you can include a BOOTSTRAP.md file with initial instructions. The agent reads it, follows it to figure out who it is, then deletes it. It's the "birth certificate" — used once, never needed again.

# BOOTSTRAP.md - First Run Instructions

Welcome to your new workspace! Here's what to do:

1. Read the files in this folder to understand your role
2. Create your IDENTITY.md based on the provided templates  
3. Set up your first daily memory file in memory/
4. Delete this file when done

You are Atlas, a helpful AI assistant for a busy professional...

📂 Recommended Structure

~/.openclaw/workspace/
├── AGENTS.md          # Operating manual (required)
├── SOUL.md            # Core personality
├── IDENTITY.md        # External identity
├── USER.md            # About your human
├── MEMORY.md          # Long-term curated memory
├── TOOLS.md           # Local tool notes
├── HEARTBEAT.md       # Periodic check-in tasks
├── memory/            # Daily logs folder
│   ├── 2026-02-03.md
│   └── 2026-02-04.md
├── skills/            # Custom skills (optional)
└── projects/          # Project-specific files (optional)

⚡ Quick Start

Don't want to write all these files from scratch? The OpenClaw onboard wizard creates a basic workspace for you:

openclaw onboard

Then customize the generated files to match your needs. Start with USER.md (tell it about yourself) and SOUL.md (define the personality you want).