Workspace files, upgrade behavior, and how to customize agents
Each A.L.I.C.E. agent has its own isolated workspace directory where it stores its identity, instructions, and memory. Understanding how these files work lets you customize agent behavior without breaking upgrades.
Every agent gets its own workspace at:
~/.openclaw/workspace-{agentId}/
For example:
~/.openclaw/workspace-olivia/ — Olivia's workspace~/.openclaw/workspace-dylan/ — Dylan's workspace~/.openclaw/workspace-daphne/ — Daphne's workspaceEach workspace contains the files described below.
SOUL.md ⚠️ Overwritten on upgradeThe agent's core identity, values, tone, and domain focus. This defines who the agent is — their domain expertise, operating principles, and personality. Written by the A.L.I.C.E. team and reset on each upgrade to ensure consistency.
Don't edit this file. Changes will be overwritten on upgrade. Use PLAYBOOK.md to extend behavior instead.
AGENTS.md ⚠️ Overwritten on upgradeOperational instructions for the agent — how it should structure its work, how it receives tasks, what to do after tasks complete, and its behavioral red lines. Think of it as the agent's job description and operating procedure.
Don't edit this file. Use PLAYBOOK.md for custom instructions.
IDENTITY.md ⚠️ Overwritten on upgradeMinimal identity metadata: name, emoji, role label, and vibe. Used for display purposes and quick-reference context. Reset on upgrade.
TOOLS.md ⚠️ Overwritten on upgradeNotes about the tools and CLIs available to the agent in its domain. Documents what tools it should prioritize and any environment-specific notes. Reset on upgrade (though you can add environment notes to PLAYBOOK.md instead).
PLAYBOOK.md ✅ Preserved on upgradeYour primary customization file. Add your own instructions, preferences, conventions, and domain context here. The agent reads this alongside AGENTS.md at session startup — it's your layer on top of the defaults.
This is where you customize agents. Examples:
LEARNINGS.md ✅ Preserved on upgradePreserved local reflection notes. Older installs may contain task lessons here, and you can still add explicit human-authored notes. New recursive learning should go through RecordorAI proposals, review, and application instead of silent Markdown appends after every task.
You can read this to understand historical behavior. If you want the agent to learn something specific, prefer a RecordorAI memory proposal or an explicit PLAYBOOK.md instruction.
MEMORY.md / memory/ ✅ Preserved on upgradeLocal companion notes and migration source material. Agents may read bounded notes here, but autonomous durable learning no longer writes directly into MEMORY.md or memory/ after each session.
RecordorAI is the governed memory stack for the A.L.I.C.E. team. It owns retrieval, drawer storage, provenance, tombstones, WAL audit, lifecycle metadata, feedback, and approved proposal application.
Preserved across upgrades as local context, not as the autonomous learning write path.
FEEDBACK.md ✅ Preserved on upgradeUser feedback the agent should incorporate into future behavior. If Olivia (or you) flags that an agent responded poorly or should behave differently, notes can go here. The agent reads this at startup.
USER.md ✅ Preserved on upgradeContext about the user that the agent should know — name, timezone, preferences, relevant background. Preserved so agents stay familiar with you across upgrades and sessions.
| File | On Upgrade | Purpose |
|------|-----------|---------|
| SOUL.md | ⚠️ Overwritten | Core identity and values |
| AGENTS.md | ⚠️ Overwritten | Operating instructions |
| IDENTITY.md | ⚠️ Overwritten | Display metadata |
| TOOLS.md | ⚠️ Overwritten | Tool reference notes |
| PLAYBOOK.md | ✅ Preserved | Your custom instructions |
| LEARNINGS.md | ✅ Preserved | Local reflection notes and migration context |
| MEMORY.md / memory/ | ✅ Preserved | Local companion notes; RecordorAI is durable memory |
| FEEDBACK.md | ✅ Preserved | User feedback notes |
| USER.md | ✅ Preserved | User context |
Rule: never edit SOUL.md, AGENTS.md, IDENTITY.md, or TOOLS.md. Put customizations in PLAYBOOK.md.
Open ~/.openclaw/workspace-dylan/PLAYBOOK.md and add:
## Conventions
- Always use TypeScript. Never plain JavaScript.
- Use Prisma for database access unless explicitly told otherwise.
- Our API follows REST conventions — avoid GraphQL unless asked.
- Backend services live in `/services/`, shared utilities in `/lib/`.
## Environment
- Local dev: http://localhost:3000
- Staging: https://staging.example.com
- Production: https://app.example.com
Dylan will read this at the start of every session and apply these conventions automatically.
Open ~/.openclaw/workspace-daphne/PLAYBOOK.md and add:
## Documentation Standards
- Follow the Diátaxis framework: separate tutorials, how-tos, references, and explanations
- API docs must include request/response examples for every endpoint
- Always include a "Why this exists" section in architecture docs
- Use American English spelling
Add to both PLAYBOOK.md files:
## Brand Voice
- Direct, confident, slightly irreverent
- No corporate jargon ("synergy", "leverage", "circle back")
- Use active voice. Short sentences.
- Address the reader as "you", not "users" or "customers"
# List all agent workspaces
ls ~/.openclaw/
# View Olivia's playbook
cat ~/.openclaw/workspace-olivia/PLAYBOOK.md
# View Dylan's local historical notes
tail -50 ~/.openclaw/workspace-dylan/LEARNINGS.md
See also: Agent Roster | Olivia — Orchestrator