OpenClaw Workspace Files: The Configuration System

Every AI agent platform has a configuration layer. Most hide it behind GUIs, dashboards, or proprietary formats. OpenClaw puts it in plain sight: seven markdown files, each controlling a specific dimension of agent behavior, sitting in your workspace directory where you can read, edit, and version-control them.

This is not a simplification. It is a deliberate architectural choice that trades visual interfaces for expressiveness, proprietary formats for portability, and abstraction for transparency. The result is a configuration system that non-developers can write, developers can automate, and both can understand at a glance.

Key Takeaways

• Seven workspace files control all agent behavior -- from personality to permissions to proactive scheduling
• SOUL.md and AGENTS.md are the highest-impact files, defining personality and workflow behavior respectively
• MEMORY.md is the only file that the agent writes to, creating a persistent learning loop across conversations
• HEARTBEAT.md enables proactive agents that reach out on schedules rather than waiting for user input
• The workspace file pattern mirrors Claude Code's CLAUDE.md system, suggesting configuration-as-markdown is becoming an industry standard

The Seven Files

Overview

The division is clean. Six files are primarily written by you. One file -- MEMORY.md -- is primarily written by the agent. This separation is critical: it means you define the rules, and the agent accumulates knowledge within those rules.

IDENTITY.md: Who the Agent Is

The simplest file. It answers the existential question every agent must resolve: who am I?

# Identity

Name: Meridian
Role: Strategic research analyst
Creator: Jason Wood
Version: 2.3

Meridian is a research-focused AI analyst specializing in technology
markets, competitive intelligence, and trend analysis. Created for
the aiskill.market editorial team.

Why it matters: Without a clear identity, agents produce generic responses. With one, they maintain consistency across conversations and channels. An agent that knows it is a "strategic research analyst" frames its responses differently than one that thinks it is a "friendly helper."

Design tip: Include version numbers. As you refine your agent, version tracking helps you roll back if a change worsens performance.

SOUL.md: How the Agent Thinks and Communicates

This is the highest-leverage file in the system. SOUL.md defines the agent's personality, communication style, values, and boundaries. It is what makes your agent feel like a specific entity rather than a generic AI chatbot.

Structure that works:

# Soul

## Communication Principles
- Lead with the answer, then provide supporting detail
- Use data and specific numbers whenever possible
- Match the user's formality level -- formal question gets formal answer
- Never pad responses with unnecessary caveats or disclaimers

## Analytical Framework
When analyzing any topic:
1. State the current situation (what is)
2. Identify the key tension or question (what matters)
3. Present evidence for competing positions (what the data says)
4. Offer a clear assessment (what we think)
5. Flag uncertainties explicitly (what we do not know)

## Values
- Intellectual honesty over comfort
- Specificity over generality
- Evidence over opinion
- Conciseness over comprehensiveness (unless asked for depth)

## Boundaries
- Acknowledge the limits of available information
- Distinguish between established facts and emerging trends
- Never fabricate sources or statistics
- Flag when a question requires expertise outside the agent's domain

The difference between good and great SOUL.md files is specificity. "Be helpful" is useless. "Lead with the answer, then provide supporting detail" is actionable. The AI treats these instructions literally, so precision in language translates directly to precision in behavior.

Comparison with CLAUDE.md: Claude Code users will recognize this pattern. Anthropic's CLAUDE.md file serves a similar function -- defining how the AI should behave within a specific project. The key difference is scope: CLAUDE.md configures a coding assistant within a repository, while SOUL.md configures a general-purpose agent across all interactions. We explored this parallel in our analysis of how different agent approaches compare.

AGENTS.md: What the Agent Does

If SOUL.md is personality, AGENTS.md is behavior. This file defines workflows, response patterns, conditional logic, and multi-step processes.

# Agent Behavior

## Message Processing
For every incoming message:
1. Classify intent: question, task, feedback, or social
2. For questions: research and respond using the analytical framework
3. For tasks: confirm understanding, execute, report results
4. For feedback: acknowledge, update MEMORY.md, confirm the update
5. For social: respond briefly and warmly, do not over-engage

## Research Workflow
When asked to research a topic:
1. Search available knowledge and installed skill outputs
2. Cross-reference at least 2 sources before stating facts
3. Present findings in structured format (headers, bullets, tables)
4. Include confidence level: high (multiple sources agree),
   medium (some sources, some inference), low (limited data)
5. Suggest follow-up questions the user might not have considered

## Escalation Rules
- If a question involves legal, medical, or financial advice: redirect
- If confidence is consistently low: suggest the user consult a specialist
- If the user expresses frustration: simplify language, slow down, ask what they need

Advanced pattern -- conditional behavior:

## Channel-Specific Behavior
- Telegram: Keep responses under 300 words, use emoji sparingly
- Slack: Use threading, format with code blocks when relevant
- Email: Use full sentences, include subject-line summaries
- WhatsApp: Ultra-concise, use voice note responses when available

This channel-specific configuration is possible because OpenClaw supports 8+ messaging channels. The same agent behaves differently on Telegram than on Slack -- not because the personality changes, but because the communication conventions differ.

TOOLS.md: What the Agent Can Access

TOOLS.md acts as a permission system. It declares which tools, integrations, and skills the agent can use:

# Tools

## Core Permissions
- web-search: enabled
- file-read: enabled (workspace only)
- file-write: enabled (MEMORY.md only)
- external-api: enabled (with rate limits)

## Installed Skills
- research-summarizer v2.1: Summarize web pages and documents
- data-analyzer v1.4: Process CSV/JSON data and generate charts
- email-drafter v3.0: Compose emails matching user's writing style

## Disabled
- social-media-posting: disabled until Q3 review
- financial-transactions: permanently disabled

Security implication: TOOLS.md is your guardrail. An agent without explicit tool permissions cannot access those tools. This is important when running agents that interact with external services, handle sensitive data, or operate on behalf of clients.

The 13,000+ skills on ClawHub integrate through this file. Install a skill, it appears in TOOLS.md. Disable it, it disappears from the agent's available actions.

USER.md: Context About the Human

USER.md stores information about you that the agent should always know:

# User Profile

## Preferences
- Timezone: GMT (London)
- Working hours: 8 AM - 6 PM weekdays
- Communication style preference: direct, data-driven
- Default output format: markdown with headers and bullets

## Context
- Role: Editor at aiskill.market
- Focus areas: AI skills, agent ecosystems, developer tools
- Current projects: OpenClaw coverage series, Q2 content calendar

## Do Not
- Send notifications outside working hours
- Summarize topics I have already marked as understood
- Repeat information from previous conversations without new context

The difference between USER.md and MEMORY.md: USER.md contains stable facts that you provide. MEMORY.md contains learned observations that the agent accumulates. You are the authority on USER.md. The agent is the author of MEMORY.md.

HEARTBEAT.md: Proactive Schedules

Most agents are reactive -- they respond when spoken to. HEARTBEAT.md makes agents proactive:

# Heartbeat Schedule

## Daily
- 8:30 AM: Morning briefing -- top 3 industry news items relevant to current projects
- 5:30 PM: End-of-day summary -- tasks completed, items pending, tomorrow's priorities

## Weekly
- Monday 9:00 AM: Week overview -- upcoming deadlines, scheduled meetings, content calendar
- Friday 4:00 PM: Week review -- accomplishments, metrics, suggested improvements

## Monthly
- 1st of month: Monthly trends report -- shifts in AI skills landscape
- 15th of month: Content performance review -- which posts performed, why, what to do next

## Triggered
- When a monitored competitor publishes a new blog post: summarize and analyze within 1 hour
- When ClawHub trending skills list changes: flag new entries

Why this matters: Proactive agents deliver value without being asked. A morning briefing that surfaces relevant news before you check your feeds. An end-of-day summary that captures what happened without you writing it. These are the behaviors that make agents feel like teammates rather than tools.

MEMORY.md: The Agent's Evolving Knowledge

MEMORY.md is unique. It is the only file primarily written by the agent itself, creating a persistent knowledge layer that improves over time:

# Memory

## User Preferences (Learned)
- Prefers comparison tables over prose for multi-option analysis
- Wants sources linked, not just mentioned
- Gets frustrated by responses longer than 500 words unless they asked for depth
- Uses "interesting" as a signal to go deeper on a topic

## Domain Knowledge (Accumulated)
- OpenClaw ecosystem: 13,000+ skills on ClawHub as of April 2026
- Agent37 managed hosting: $3.99-$9.99/month tiers
- Key competitor: Claude Code skills via aiskill.market
- Emerging trend: configuration-as-markdown standardizing across platforms

## Interaction Patterns
- Most active: Tuesday and Wednesday mornings
- Least active: weekends (respect do-not-disturb)
- Average conversation length: 8-12 exchanges
- Most requested task type: competitive analysis

The persistent memory system is what transforms a stateless chatbot into an evolving assistant. We explored this trajectory in depth in our coverage of persistent memory and the future of AI skills.

Configuration-as-Markdown: An Emerging Standard

OpenClaw is not the only platform adopting this pattern. Claude Code's CLAUDE.md, Cursor's rules files, and various agent frameworks now use markdown for configuration. This convergence suggests a standard is forming.

Why markdown wins for agent configuration:

The trend is clear: the best way to tell an AI what to do is to write it down in the same language you would use to tell a human. Structured formats add precision at the cost of accessibility. Visual builders add approachability at the cost of depth. Markdown sits in the productive middle.

For more context on how this compares to Claude Code's approach, see our analysis of how OpenClaw and Claude Code represent two different philosophies.

Best Practices for Workspace Files

Start sparse, add density. Begin with minimal files and add specificity as you discover what the agent gets wrong. Over-specified agents are brittle. Under-specified agents are vague. The sweet spot is instructions that cover 90% of cases and let the agent reason through the rest.

Review MEMORY.md monthly. The agent accumulates knowledge continuously. Some of it becomes outdated. Schedule a monthly review to prune stale entries and correct inaccuracies.

Version control your workspace. Put your workspace files in a Git repository. When you change SOUL.md and the agent's behavior degrades, you can diff against the previous version and roll back.

Treat AGENTS.md as a living document. Your workflows evolve. New skills get installed. New channels get connected. AGENTS.md should reflect your current operational reality, not your initial aspirations.

FAQ

Can workspace files conflict with each other?

They can create tension but not technical conflicts. If SOUL.md says "be concise" and AGENTS.md defines a 10-step verbose workflow, the agent will attempt to be concise within a verbose structure. The resolution depends on the underlying model's interpretation. In practice, AGENTS.md workflow instructions tend to take precedence over SOUL.md style preferences when they conflict.

How large can workspace files be?

There is no hard limit, but practical limits exist. Very long files consume context window tokens, reducing the space available for conversation. Keep each file under 2,000 words for optimal performance. If a file grows beyond that, consider splitting responsibilities across files or compressing instructions.

Do I need all seven files to run an agent?

No. IDENTITY.md and AGENTS.md are the minimum. SOUL.md is strongly recommended. The others add capabilities but are not required. Start with three files and add the rest as your agent matures.

Can I use workspace files with models other than the default?

Yes. Workspace files are model-agnostic. The same configuration works across all 12+ supported providers. A SOUL.md written for Claude works identically when you switch to GPT or Gemini. The markdown-to-behavior translation is handled at the OpenClaw platform level, not the model level.

How do workspace files interact with installed ClawHub skills?

Installed skills appear in TOOLS.md as available capabilities. AGENTS.md can reference these skills in workflow definitions. SOUL.md can include instructions about when and how to use specific skills. MEMORY.md may accumulate knowledge about which skills work best for which tasks. The files form a coherent system, not isolated silos.

The Configuration Layer Is the Product

When you build an OpenClaw agent, you are not writing code. You are writing a specification -- a detailed description of what you want an AI to do, how you want it to behave, and what it should remember. The workspace files are that specification, expressed in the most natural format possible.

This matters for the broader ecosystem because it makes AI agents composable and shareable. A workspace configuration that works for one research analyst can be adapted for another. A SOUL.md that creates a great customer support personality can be forked and customized. The skills community grows not just through code contributions but through shared configurations.

The future of AI agent customization is not more sophisticated GUIs. It is better writing.

Explore production-ready AI skills at aiskill.market/browse or submit your own skill to the marketplace.