Multi-Agent Migration: Promoting Ephemeral Sub-Agents to Permanent Agents

The Problem with Pure Ephemeral Agents

If you've been running multiple agents in OpenClaw using sessions_spawn, you might have noticed a limitation: ephemeral sub-agents have no persistent memory. Every time they run, they start fresh. For one-shot tasks like "search the web for X" or "format this data," that's fine. But for specialized workers you rely on repeatedly—like a research agent or a coding agent—losing context between runs is painful.

Community member kevink recently shared a migration plan in Discord that addresses this exact issue: promoting high-value ephemeral sub-agents to permanent agentId configurations while keeping simple tasks ephemeral.

When to Go Permanent vs. Stay Ephemeral

Make Permanent (their own agentId):

• Research agents (Scout) - builds context about your projects, domains, preferences
• Coding agents (Bolt) - learns your codebase patterns, remembers past decisions
• Analytics agents (Lens) - accumulates domain knowledge over time

Keep Ephemeral (via sessions_spawn):

• Event-driven responders
• One-shot formatters
• Standalone utilities
• Intern tasks that don't need history

The rule of thumb: if an agent would benefit from remembering yesterday's work, make it permanent.

The Migration Pattern

Here's the step-by-step approach kevink laid out:

1. Verify Tool Access First

Before changing anything, confirm your sub-agents can access the tools they need. Check that read, message, web_search, exec, and browser work as expected.

Important limitation discovered: memory_search is currently unavailable to sub-agents. Plan your memory strategy accordingly.

2. Enable Agent-to-Agent Messaging

Permanent agents communicate via sessions_send rather than being spawned and discarded. Set this up before adding permanent agents.

3. Add Permanent Agents One at a Time

Don't add Scout, Bolt, and Lens all at once. Add Scout first, test it end-to-end, then add the next. Each permanent agent gets:

• Its own AGENTS.md
• Its own MEMORY.md
• A memory/ directory under the shared workspace

4. Update Documentation

Replace the spawn templates in your main agent's AGENTS.md with instructions to use sessions_send for permanent agents.

The Communication Flow

Instead of spawning and waiting, your main agent delegates:

User Request → Main Agent (Captain) ↓ sessions_send ┌─────────┼─────────┐ ↓ ↓ ↓ Scout Bolt Lens (research) (code) (analytics) ↓ ↓ ↓ [own output channels] ↓ ↓ ↓ └─────────┼─────────┘ ↓ Main Agent synthesizes

Key Rules to Follow

1. Don't separate workspaces. Keep all agents in the same workspace for file sharing.
2. Don't add all agents at once. Sequential migration, verified per step.
3. Don't remove sessions_spawn. Keep it as a fallback for ephemeral tasks.
4. Don't let workers manage cron or respond to Discord directly. The main agent remains the coordinator.
5. Use full model paths. Model aliases don't resolve for sub-agents—use anthropic/claude-sonnet-4-6 instead of sonnet.

Success Criteria

• Permanent agents (Scout/Bolt/Lens) persist knowledge between runs
• Main agent delegates via sessions_send successfully
• Ephemeral spawn still works for one-shot tasks
• No gateway errors during handoffs

---

Thanks to kevink for sharing this migration pattern in the OpenClaw Discord #help channel. If you've implemented a similar setup, share your experience in the comments!

Further Reading

• Multi-Agent Routing docs
• sessions_send API reference
• Memory and Context docs