Overview
When several persistent agents work for one person, give each its own brain and give one agent, the main brain, ownership of everything shared. A brain is an agent’s persistent state: its persona files, memory, skills, session history, and credentials. OpenClaw builds agents this way: each has its own workspace, state directory, and session store, the default agent id is main, and memory search covers only the agent’s own memory unless a shared folder is added explicitly. The rule that keeps it working is one writer per file: specialists read shared knowledge and propose additions, and the main brain decides what is promoted.
Draw the line between private and shared
| Layer | Per-agent brain | Main brain | Shared, read-only to specialists |
|---|---|---|---|
SOUL.md | Own voice and scope | Own voice | No |
MEMORY.md | Facts about its domain | Cross-domain decisions | No |
USER.md | Reads a copy | Owns and writes | Yes |
| Skills | Domain skills | Coordination skills | A shared baseline |
| Knowledge base | Reads | Writes after review | Yes |
| Sessions and credentials | Own only | Own only | Never |
OpenClaw’s skill config mirrors the Skills row: agents.defaults.skills sets a shared baseline, and a per-agent list replaces it rather than merging.
Keep one writer per file
Two agents appending to one MEMORY.md produce duplicates under different wording and silent overwrites, the same failure two writers cause in a vault (team-vaults). Give every file exactly one writing agent. A specialist that learns something cross-cutting returns it to the main brain as a proposal; the main brain checks it against what it already holds and writes it, or drops it.
research-agent -> proposes: "User's paper deadline moved to 2026-12-05"
main -> checks USER.md, replaces the old deadline, logs the change
writing-agent -> reads USER.md next session; never writes itNever share a state directory
OpenClaw’s docs are direct: “Never reuse agentDir across agents; it causes auth/session state collisions.” The same holds for any runtime. Separate session stores alone do not isolate agents: OpenClaw turns cross-agent session access on by default under tools.agentToAgent. Turn it off, or narrow it to the agents that need it, so one agent’s tool output, which may contain injected text, stays out of another agent’s context (prompt-injection-defense).
Share knowledge through an explicit folder
Put reference material every agent needs in one directory and add it to each agent’s search path; OpenClaw uses memory.search.extraPaths for this, since cross-agent transcript search was removed. A vault-architecture vault works well as that folder: typed notes, one claim per file, and a single promotion path, with agents divided by pipeline stage as in vault-orchestration.
Keep the main brain’s private memory out of group contexts
OpenClaw loads MEMORY.md only in the main, private session, never in shared or group chats. Follow the same rule anywhere: an agent answering in a team channel should not carry the person’s private notes into its prompt, where any participant can draw them out.
Split agents by role or channel, not by mood
Add a second brain when the work needs a different tool set, a different audience, or a context that would crowd the first: a coding agent with repository access, a family assistant on a messaging app, a research agent with web search. Do not split for a different tone; that is a line in SOUL.md. Each extra brain is another memory to curate and another set of credentials to scope, and the token cost of multi-agent systems is covered in multi-agent.
Hand off with summaries, not shared memory
When the main brain delegates, pass a typed brief and take back a typed result (structured-output). Do not grant the worker write access to the main brain’s memory to save a step; the handoff is where the main brain decides what to keep.
Related
- agent-persona-files: the files inside one brain.
- agent-memory-files: memory tiers, caps, and write rules.
- self-improving-agents: what each brain may learn on its own.
- multi-agent: orchestrator-worker patterns and caps.
- vault-orchestration: agents working a shared vault.
- team-vaults: one naming authority for many writers.