← Back to OpenClaw DocsComponent

Workspaces

A workspace is the directory OpenClaw uses to give your agent its identity, memory, and rules. It's just a folder with a few Markdown files — no database, no cloud sync. The agent reads them on startup and they shape every session that runs from that directory.

How to build context systems for AI agents — workspace files, memory, and agent identity

Description

OpenClaw treats the directory it's launched from as the workspace. Everything in that directory that matches a known filename (SOUL.md, USER.md, etc.) is automatically loaded into the agent's context on each session start.

This design means your agent's configuration is version-controllable — commit the workspace files alongside your code and every collaborator (or every device) gets the same agent behaviour. Update SOUL.md, push, and the change takes effect on the next session.

Each project can have a different workspace, so your coding agent, your personal assistant, and your home automation agent each have distinct identities and memories — without any naming conflicts or shared state.

The .claude/ subdirectory holds machine-readable configuration: tool permissions in settings.json, per-project skills in skills/, and memory files in memory/. The top-level Markdown files are for the agent to read as natural language — the JSON folder is for the runtime.

Workspace files

SOUL.mdrecommended

Defines the agent's personality, tone, and behaviour rules. Loaded on every session start. Think of it as the agent's identity card.

# SOUL.md
Be direct. Skip filler phrases like "Great question!"
Have opinions. Disagree when you know better.
When in doubt, check context before asking.
USER.mdoptional

Information about the person the agent is helping — name, timezone, role, preferences. Helps the agent tailor responses without being asked.

# USER.md
- Name: Alex
- Timezone: America/Sao_Paulo
- Role: Full-stack engineer
- Prefers: concise replies, no markdown tables
MEMORY.mdoptional

Index of persistent memory entries. Every line is injected into every session turn — keep it lean. Long MEMORY.md files slow down every response.

# MEMORY.md
- [Project context](memory/project.md) — current sprint and goals
- [Feedback](memory/feedback.md) — how the user likes to work
AGENTS.mdoptional

Agent-level rules specific to this workspace — coding conventions, file structure notes, things the agent should always do or never do here.

# AGENTS.md
This is a Next.js 15 project. Read node_modules/next/dist/docs/
before writing any Next.js code.
HEARTBEAT.mdoptional

Scheduled check-in tasks. Add items here to have the agent periodically verify something (e.g. check CI, ping a service). Leave empty to skip.

# HEARTBEAT.md
- Check that the dev server is still responding on :3000
IDENTITY.mdoptional

The agent's name, emoji, avatar, and self-description. Used for display purposes and to help the agent know how to introduce itself.

# IDENTITY.md
- Name: Claw
- Emoji: 🦞
- Vibe: sharp, curious, slightly dry
.claude/settings.jsonoptional

Project-scoped tool permissions, allowed commands, and environment overrides. Preferred over global settings — scope follows the repo.

{
  "permissions": {
    "allow": ["Bash(npm run *)", "Read", "Edit"]
  }
}
.claude/skills/optional

Directory for workspace-scoped skills. Skills here are available in all sessions using this workspace but not in other workspaces.

# Example: .claude/skills/deploy.md
---
name: deploy
trigger: /deploy
---
Run npm run build and deploy to production.

CLI commands

Minimum version:openclaw 2026.6.0+

Show which workspace directory is active

openclaw workspace

Initialise a new workspace (creates starter files)

openclaw init

Get a config value for the current workspace

openclaw config get <key>

Set a config value for the current workspace

openclaw config set <key> <value>

List all config values

openclaw config list

Tips

One workspace per project

Keep workspace files in the project root and commit them. Different projects get different agent personalities — your frontend agent and your backend agent don't need to share context.

Keep MEMORY.md short

MEMORY.md is injected on every turn. Each extra line costs tokens on every message. Use it as an index pointing to memory/ files, not as a dump of everything the agent has ever learned.

Use .claude/settings.json for permissions

Project-level tool permissions beat global ones — they're reviewable in PRs and scoped to the repo. Only allow the tools this project actually needs.

Workspace files are version-controlled

SOUL.md, USER.md and AGENTS.md can be committed and pushed. Anyone who clones the repo and runs openclaw gets the same agent setup.

← Sessions↑ All docs