OpenClaw Workspace Files Explained — SOUL.md, TOOLS.md,

OpenClaw's power comes from its workspace files. These are plain markdown files that live in ~/.openclaw/workspace/ and get injected into your agent's context every session. Understanding what each file does is fundamental to getting the most out of OpenClaw.

The Workspace Directory

~/.openclaw/workspace/
├── SOUL.md          # Who your agent is
├── MEMORY.md        # Long-term memories (main session only)
├── USER.md          # Who you are (private)
├── TOOLS.md         # Your tools and infrastructure
├── AGENTS.md        # Orchestration instructions
├── HEARTBEAT.md     # Scheduled check-in behavior
├── COMPANY.md       # Business context (private)
└── memory/
    ├── 2026-01-15.md  # Daily notes
    └── ...

SOUL.md — Your Agent's Identity

The most important file. Defines your agent's personality, communication style, decision-making principles, and behavior patterns. Loaded every session. Think of it as the character sheet for your agent.

# SOUL.md example
You're not a chatbot. You're an operator.
Be resourceful before asking.
Have opinions. Earn trust through competence.

## Communication
- Lead with outcomes, not process
- One message, not a thread
- Concise by default, detailed on request

See the full SOUL.md guide for detailed instructions.

TOOLS.md — Your Infrastructure Map

Documents your specific setup: API credentials (references to .env), service configurations, channel IDs, cron names, integration notes. Loaded every session so your agent knows exactly how to reach your tools.

# TOOLS.md example
### Slack Channels
- #engineering: C0A4G5T2DLM
- #sales: C0ACMC7HM18

### APIs
- Stripe: $STRIPE_SECRET_KEY (in .env)
- GitHub: gh CLI (pre-authenticated)

MEMORY.md — Long-Term Memory

Curated long-term memories the agent should always have. Things like: key decisions made, important context, ongoing projects, relationship notes. Only loaded in main sessions (not cron jobs).

USER.md — About You

Who you are: name, timezone, background, preferences, working style. Kept private. Helps the agent give contextually appropriate responses.

AGENTS.md — Orchestration Rules

Instructions for how your agent should orchestrate work — when to spawn sub-agents, how to handle different request types, communication norms, and workflow patterns.

HEARTBEAT.md — Scheduled Behavior

What your agent should do during scheduled heartbeat checks. Loaded by cron-triggered heartbeat jobs. Define: what to monitor, what to alert on, what to log.

Daily Memory Files

In memory/YYYY-MM-DD.md — daily working notes. Key decisions, issues encountered, team notes. These are append-only logs, not loaded automatically on every session.

How Files Are Loaded

On session start: SOUL.md + TOOLS.md + AGENTS.md + USER.md are always loaded. MEMORY.md is loaded only in main (direct chat) sessions. HEARTBEAT.md is loaded by cron heartbeat jobs. Daily memory files are loaded only when explicitly referenced.

Best Practices

• Keep SOUL.md focused — 200-400 words is plenty
• TOOLS.md is your cheat sheet — add anything the agent needs to operate effectively
• Never put API keys directly in markdown — use .env references
• Review and update workspace files monthly — stale context leads to degraded performance

Want the full OpenClaw setup guide? The OpenClaw Playbook covers everything — $9.99.