Soul/Body Architecture#
Nebula separates an agent's identity from its execution environment. This separation is the foundation for concurrent multi-project work and context-aware execution.
Soul — The Agent's Identity#
The soul is everything that defines who the agent is:
- Name and role — injected into every system prompt
- Memory — persistent knowledge across all sessions
- Skills — custom and built-in capabilities
- MCP servers — external tool configurations
- Secrets — encrypted credentials
- CLAUDE.md — agent-specific knowledge file
The soul is shared across all of the agent's executions. When you update an agent's role or add a skill, every future session — regardless of context — picks up the change.
Body — The Execution Environment#
The body is a CLI process executing a specific task:
- A
node-ptysession running a CLI runtime (Claude Code, OpenCode, etc.) - Scoped to a specific conversation, project, or task
- Has its own working directory and git worktree (for project work)
- Receives context assembled specifically for this execution
Bodies are ephemeral relative to the soul. They're created when work needs to happen and can be reset or replaced without affecting the agent's identity.
One Soul, Many Bodies#
A single agent can have multiple concurrent bodies:
Agent "DevBot" (soul)
├── Body 1: Main conversation (direct chat)
├── Body 2: Project Alpha / feature/auth branch
├── Body 3: Project Alpha / fix/bug-123 branch
├── Body 4: Project Beta / main branch
└── Body 5: Cron task (daily report)
Concurrency Rules#
| Scenario | Behavior |
|---|---|
| Same agent, different branches in a project | Concurrent — each branch has its own worktree |
| Same agent, different projects | Concurrent — independent working directories |
| Same agent, main chat + project work + cron task | Concurrent — different execution contexts |
| Same agent, same project, same branch | Serialized — queued to prevent conflicts |
Same conversation (same CLI session via --resume) | Serialized — one message at a time |
| Inter-agent @mention routing | Concurrent — each agent runs in its own context |
Serialization uses a context key: agent:project:branch. Requests with the same key are queued; different keys run in parallel.
Per-Project Concurrency Cap#
For project work, each agent has a configurable max concurrent setting. This limits how many simultaneous sessions the agent can have within a single project, preventing resource exhaustion on large projects with many branches.
Configure this in Project Settings → Agents when assigning agents to a project.
Why This Matters#
The soul/body split has practical consequences:
- No identity fragmentation — memory and skills are consistent across all contexts
- Safe concurrency — worktree isolation means concurrent bodies never step on each other
- Independent lifecycle — resetting a body (clearing a session) doesn't affect the soul or other bodies
- Context-appropriate execution — each body gets exactly the context it needs, not a shared conversation window