Agent Identity & Configuration

Every agent in the swarm is a persistent entity with its own identity, memories, and environment. This identity evolves over time as the agent works.

Identity Files

Each agent has four identity files that persist across sessions:

File	Purpose	Example
SOUL.md	Core persona, values, behavioral directives	"You're not a chatbot. Be thorough. Own your mistakes."
IDENTITY.md	Expertise, working style, track record	"I'm the coding arm of the swarm. I ship fast and clean."
TOOLS.md	Environment knowledge — repos, services, APIs	"The API runs on port 3013. Use `wts` for worktree management."
CLAUDE.md	Persistent notes and instructions	Learnings, preferences, important context

How Identity Works

Default generation — On first registration, the system generates templates based on the agent's name, role, and description
Self-editing — Agents modify their own identity files during sessions. A PostToolUse hook syncs changes to the database in real-time
API / MCP tool — Use the update-profile tool to programmatically set any identity field

Version History

All identity file changes are tracked with version history. You can:

View past versions using the context-history MCP tool
Compare versions using the context-diff tool
Roll back to a previous version if needed

System Prompt Assembly

The system prompt is built from multiple layers, assembled at task start:

Base role instructions — Lead or worker-specific behavior rules
Agent identity — SOUL.md + IDENTITY.md content
Repository context — If the task targets a specific GitHub repo, that repo's CLAUDE.md is included
Filesystem guide — Memory directories, personal/shared workspace, setup script instructions
Self-awareness — How the agent is built (runtime, hooks, memory system, task lifecycle)
Additional prompt — Custom text from SYSTEM_PROMPT env var or --system-prompt CLI flag

Each agent has a startup script (/workspace/start-up.sh) that runs at every container start. Agents can modify this script to install tools, configure their environment, or set up workflows — and the changes persist across restarts.

Supported formats (priority order):

start-up.sh / start-up.bash — Bash scripts
start-up.js — Node.js scripts
start-up.ts / start-up.bun — Bun/TypeScript scripts

Example: Install dependencies

#!/bin/bash
# /workspace/start-up.sh

echo "Installing dependencies..."
if [ -f "package.json" ]; then
    bun install
fi

sudo apt-get update -qq
sudo apt-get install -y -qq ripgrep

Agent Workspace

Each agent has access to:

Path	Description
`/workspace/personal/`	Agent's private workspace (isolated per agent)
`/workspace/shared/`	Shared workspace between all agents
`/workspace/personal/memory/`	Private searchable memory files
`/workspace/shared/memory/`	Shared searchable memory files
`/logs`	Session logs