Workspace Profile Files

Use SOUL.md, IDENTITY.md, and USER.md from workspace roots as local context

Workspace Profile Files let Claw use supported root-level files from the active workspace as explicit context for chats and agents.

Configure this in Settings > General > Use workspace profile files.

Supported files

Claw currently loads only these filenames from the active workspace root:

  • SOUL.md
  • IDENTITY.md
  • USER.md

MEMORY.md and other OpenClaw-style files are not loaded by this feature yet. Use Memory Bank for durable Claw memory.

What each file is for

Use the files for concise, stable context.

  • SOUL.md: workspace-specific tone, values, style, and behavior expectations
  • IDENTITY.md: external-facing identity details such as agent name or presentation
  • USER.md: user or operator preferences relevant to the workspace

Keep these files focused. Long, stale, or contradictory profile files reduce output quality.

Precedence

Workspace profile files are treated as explicit workspace context, but they are not the highest-priority instruction source.

Precedence guidance:

  • Latest user instructions still matter most for the current turn
  • Project instructions and agent custom instructions take priority when there is a conflict
  • Workspace profile files can shape identity, user preference, and working style inside the workspace
  • Attached memory and Working Brief provide additional context, not replacement policy

If profile files conflict with actual project requirements, update the files instead of relying on repeated corrections in chat.

Loading behavior

When enabled:

  • Claw checks the active workspace root for supported filenames
  • Missing files are ignored
  • Empty files are ignored
  • Supported files are loaded into the prompt for workspace chats and agents
  • Each file is capped before loading so profile files do not dominate the context window

When disabled, Claw can detect that supported files exist but does not load their content into the model.

Recommended authoring pattern

Use short sections with concrete guidance.

Example USER.md structure:

# User Preferences

- Prefer direct answers and clear next steps.
- Flag risky assumptions before acting.
- Keep status updates concise.

Example SOUL.md structure:

# Workspace Style

- Be pragmatic and implementation-focused.
- Verify behavior with the smallest useful check.
- Do not over-explain routine changes.

Operational guidance

  • Review profile files before enabling the feature on a shared workspace
  • Keep sensitive credentials out of profile files
  • Keep files under source control only when the content is appropriate for the repo
  • Use Memory Bank for durable facts that should travel across workspaces
  • Re-test important agents after changing profile files

Troubleshooting

If profile guidance is not showing up:

  • Confirm the setting is enabled in Settings > General
  • Confirm the file is at the active workspace root
  • Confirm the filename is exactly SOUL.md, IDENTITY.md, or USER.md
  • Confirm the file is not empty
  • Check whether agent or project instructions are intentionally taking precedence

Related detail pages

Side Chat
Ask quick contextual questions without changing the main conversation
Context Scout
Use pre-send workspace discovery to attach relevant files, maps, and task context