ClawPaneClawPane
How to set upPricingBlog
·ClawPane

OpenClaw Workspace Files: AGENTS.md, SOUL.md, MEMORY.md and More

OpenClawworkspaceAGENTS.mdSOUL.mdcustomizationsystem prompt

When OpenClaw starts an agent session, it reads a set of Markdown files from your workspace and injects them directly into the system prompt. These files are your primary interface for shaping how your agent thinks, what it knows about you, and how it behaves — without touching config JSON or writing code.

This guide covers every bootstrap file, what each one does, and links to real community examples.

How it works

At the start of each session, OpenClaw scans your workspace directory for a specific set of files. Any it finds get injected verbatim into the system prompt before the first message. The agent reads them and uses them as ground truth for the session.

The workspace directory defaults to ~/.openclaw/workspace but can be overridden per agent in openclaw.json:

{
  "agents": {
    "defaults": {
      "workspace": "~/projects/my-agent/workspace"
    }
  }
}

You can inspect exactly what's being injected with /context list and /context detail inside a session.

The Bootstrap Files

1. AGENTS.md

What it is: Instructions for the agent itself — how it should operate, what its primary job is, what tools it should prefer, and any constraints on its behavior.

What to put in it:

  • The agent's core task or role ("You are a research assistant that summarizes arXiv papers daily")
  • Preferred tools and workflows ("Always use exa-web-search-free for lookups before answering")
  • Constraints ("Never delete files without explicit confirmation")
  • Response format preferences ("Use bullet points for summaries, prose for explanations")

Example from the community:

  • agent-config — a skill that helps you intelligently modify agent core context files including AGENTS.md
  • agenticflow-skill — a guide for building AI workflows that covers AGENTS.md patterns

Tip: Keep AGENTS.md focused on behavior, not identity. Identity goes in SOUL.md or IDENTITY.md.

2. SOUL.md

What it is: The agent's personality, values, and sense of self. If AGENTS.md is the job description, SOUL.md is the character.

What to put in it:

  • Personality traits ("Direct, concise, skeptical of hype")
  • Communication style ("Use plain English, no corporate speak")
  • Values ("Prioritize privacy, never share user data with third parties")
  • How it should handle uncertainty ("Say you don't know rather than guessing")

Example from the community:

  • agent-church — identity formation for AI agents via SOUL.md
  • agent-identity-kit — a portable identity system that structures SOUL.md and IDENTITY.md together
  • A real example SOUL.md is referenced in claude-optimised, which covers writing and optimizing persona files for Claude-backed agents

Tip: SOUL.md is optional but high-value. Agents without one tend to drift toward generic AI assistant behavior. Even a short paragraph makes a noticeable difference.

3. IDENTITY.md

What it is: Factual identity — the agent's name, role, version, and any metadata about it.

What to put in it:

  • Name and persona label ("Name: Samantha | Role: Personal assistant")
  • Version or date ("Last updated: 2026-02-24")
  • Owner or team ("Built by: @yourhandle")
  • Contact or escalation info (for multi-agent setups)

Example from the community:

Tip: In multi-agent setups, IDENTITY.md helps agents recognize each other's roles. The agent-registry skill uses it for token-efficient agent discovery.

4. USER.md

What it is: Context about the human using the agent. The agent reads this to personalize responses without you repeating yourself every session.

What to put in it:

  • Your name and timezone
  • Your role and what kind of work you do
  • Preferences ("I prefer TypeScript over JavaScript", "I use Vim keybindings")
  • Things the agent should always remember ("I have a standup at 9am Monday–Friday")
  • Tools and accounts you use ("My primary calendar is Google Calendar, account: work@example.com")

Example from the community:

Tip: USER.md dramatically reduces the friction of starting new sessions. Without it, you re-explain yourself every time. With it, your agent already knows the basics.

5. MEMORY.md (and memory/*.md)

What it is: Persistent facts the agent should remember across sessions. Unlike session context (which resets), MEMORY.md is stable storage that gets re-injected every time.

What to put in it:

  • Key decisions ("Decided to use Postgres not SQLite for the project — 2026-01-15")
  • Important context ("Client X prefers weekly updates, not daily")
  • Ongoing task state ("Current sprint goal: ship auth by 2026-03-01")
  • Things you don't want to repeat ("API keys live in 1Password vault 'Dev'")

For larger memory needs, OpenClaw also supports a memory/ directory of individual .md files, each covering a distinct topic. The agent uses memory_search and memory_get to retrieve them selectively.

Example skills that help manage MEMORY.md:

Tip: Don't put everything in one MEMORY.md. Use the memory/ directory with focused files (memory/project-x.md, memory/clients.md, memory/preferences.md). The agent retrieves them selectively, so smaller focused files are more efficient than one giant file.

6. HEARTBEAT.md

What it is: Instructions for what the agent should do during scheduled heartbeat check-ins. OpenClaw can wake your agent on a timer (e.g., every 30 minutes) and run whatever is in HEARTBEAT.md.

What to put in it:

  • Recurring checks ("Check for new emails in the priority inbox")
  • Monitoring tasks ("Alert me if any AWS ECS service goes unhealthy")
  • Proactive nudges ("If it's after 4pm and I haven't checked my task list, remind me")
  • Scheduled summaries ("Every weekday at 9am, summarize overnight GitHub activity")

Configure the heartbeat timer in openclaw.json:

{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "30m",
        "target": "last"
      }
    }
  }
}

Set every: "0m" to disable heartbeats entirely if you don't use them.

Example from the community:

  • ai-daily-briefing — start every day focused; uses HEARTBEAT.md for morning routines
  • autonomous-brain — proactive monitoring and decision-making driven by heartbeat

Tip: HEARTBEAT.md is one of the most underused files. If your agent is only reactive, you're leaving significant value on the table. Even a simple "check my task list and flag anything due today" makes a real difference.

7. TOOLS.md

What it is: Documentation about tools and integrations available to the agent. Unlike AGENTS.md (which covers behavior), TOOLS.md covers what the agent can connect to and how.

What to put in it:

  • Available API integrations and their base URLs
  • Authentication notes ("GitHub token is in env var GITHUB_TOKEN")
  • Tool-specific quirks ("The Jira skill requires the project key prefix in all issue IDs")
  • Usage examples for complex tools

Example from the community:

  • agent-docs — creates documentation optimized for AI agent consumption, including TOOLS.md
  • danube-tools — provides 100+ API tool integrations that can be documented in TOOLS.md

8. BOOTSTRAP.md

What it is: A one-time setup file injected only on brand-new workspaces. Use it for first-run instructions — things you only need to tell the agent once.

What to put in it:

  • Initial setup steps ("Install the github and todoist-rs skills on first run")
  • Welcome context ("This workspace is for my consulting business")
  • One-time prompts ("Ask me to confirm my timezone before doing anything else")

Once the agent runs through bootstrap, it won't re-inject this file on subsequent sessions.

File size and token cost

Every file injected into the system prompt costs tokens. OpenClaw has limits controlled by:

{
  "agents": {
    "defaults": {
      "bootstrapMaxChars": 10000,
      "bootstrapTotalMaxChars": 50000
    }
  }
}

Keep files focused. A 200-line MEMORY.md covering ten unrelated topics is less useful — and more expensive — than five 40-line files each covering one topic.

A minimal working setup

Here is a simple starting set for a personal assistant agent:

AGENTS.md

You are a personal assistant. Your primary jobs are:
1. Manage tasks in Todoist
2. Summarize emails when asked
3. Take meeting notes and extract action items

Always confirm before deleting anything.

USER.md

Name: Alex
Timezone: America/New_York
Work hours: 9am–6pm weekdays
Primary task manager: Todoist
Primary calendar: Google Calendar

MEMORY.md

# Active projects
- Q1 product launch (deadline 2026-03-31)
- Vendor contract renewal (contact: contracts@vendor.com)

# Preferences
- I prefer bullet-point summaries
- Don't schedule meetings on Fridays

HEARTBEAT.md

Check Todoist for tasks due today and list them.
If it's Monday, also pull this week's calendar events.

Community resources

Keep model costs down as your workspace grows

Every workspace file you add increases the tokens consumed per session. If you are running high request volumes through OpenClaw, the per-session overhead adds up fast. ClawPane automatically routes each request to the cheapest model capable of handling its complexity — so enriched, context-heavy sessions go to a strong model, and lighter requests stay on budget models.

Set up smart routing →