Merlin Docs

Identities

Agent specs define local personas, models, skills, tools, and memory scope.

An identity is a local agent spec plus the files and capabilities it points at. The runtime loads it only when selected by channel metadata, mesh routing, @<id>, or explicit @agent:<id>.

Agent Spec

Save agent specs as agents/<id>.json:

{
  "id": "planner",
  "name": "Planner",
  "soul": "agents/planner/SOUL.md",
  "prompt": "agents/planner/PROMPT.md",
  "skills": ["planning"],
  "tools": ["bash", "cronjob", "claw_mesh", "memory"],
  "provider": "openai-codex",
  "model": "gpt-5.5",
  "thinking": "low",
  "memoryScope": "agent"
}

Field	What it controls
`id`, `name`	The addressable local identity.
`prompt`, `soul`	Workspace-local text files loaded into the system prompt.
`skills`	Filters visible skills to this identity.
`tools`	Filters available runtime tools.
`provider`, `model`	Overrides the folder defaults for this identity.
`thinking`	Sets reasoning effort when the selected model supports it.
`memoryScope`	Can pin memory to `agent:<id>` instead of the channel session.

Provider and model resolution uses send input or CLI flags first, then the agent spec, .claw/config.json, environment variables, the selected provider’s default model, and finally fake.

Routing

Use @planner make a plan from chat, or route through rooms and mesh when one persona should hand work to another.