What are agents?

An agent is a persistent identity layered on top of Claude. The literal system prompt in src/gateway/agent.ts says:

“You are Claude, operating as a Daemion agent — your user’s AI copartner, responding via the Daemion mobile app.”

Agents are not separate AIs and are not rebrands. Per Anthropic licensing, every agent is Claude operating in a defined role with a specific soul, system prompt, model, permissions, and Engram memory group.

Two core agents ship with Daemion out of the box:

Daemion (sonnet) — the main orchestration agent. Coordinates jobs, routes to the right model, manages threads, and connects to the knowledge graph. This is the agent you talk to.
Pulse — the self-improvement engine. Analyzes how you use the system and files proposals to make it better. New agents, smarter prompts, better workflows. You review and approve.

Additional agents like librarian, researcher, and news-tracker can be created by chatting with Daemion or via the API.

What makes an agent?

Each agent is a directory under ~/.daemion/agents/ containing:

~/.daemion/agents/daemion/
  daemion.yaml          ← identity (model, icon, color, permissions, escalation)
  soul.md               ← per-agent personality and learned context
  system.md             ← task-specific system prompt (optional)
  agents/
    daemion.md          ← system prompt with YAML frontmatter (name, tools, model)
  skills/               ← agent-scoped capability extensions
  .claude-plugin/
    plugin.json         ← plugin metadata (name, description, version)

The registry (src/gateway/agent-registry.ts) reads these files at startup and hot-reloads them when POST /reseed is called. No restart required.

The soul system

Daemion separates two concerns that are often conflated:

system.md — the agent’s capabilities and instructions. What it knows how to do. Stable across users.

soul.md — the agent’s relationship context with this specific user. Communication style, preferences, things they’ve learned together. Built up over conversations.

A base soul at ~/.daemion/soul.md captures user-level facts shared across all agents. Each agent also has its own soul.md for relationship-specific context. On first conversation, the agent runs a structured onboarding to build the base soul from scratch.

Model routing

Each agent declares a model in its daemion.yaml:

Short name	Model ID	Use when
`haiku`	`claude-haiku-4-5-20251001`	Classification, quick lookups, cheap operations
`sonnet`	`claude-sonnet-4-6`	General purpose — the default
`opus`	`claude-opus-4-6`	Judgment, deep reasoning, architectural decisions

The agent-registry resolves short names to full model IDs at runtime via resolveModelId(). You can also pass a full model ID directly in daemion.yaml.

Permissions and escalation

Each agent’s daemion.yaml declares which tools it can use autonomously and which require user approval:

yaml

permissions: autonomous:

Read
Grep
Glob
WebFetch
WebSearch requires_approval: [] escalation:
when: “can’t resolve” to: user

The defaults allow read-only tools autonomously and escalate to the user when stuck. Agents that write files or execute commands should list those tools under requires_approval.

Engram memory groups

Each agent can access the shared Engram knowledge group (daemion by default, configurable via DAEMION_SHARED_GROUP) plus its own private group. Configure in daemion.yaml:

yaml

memory: engram: true groups:

auto # resolved to the agent’s own name
daemion # shared cross-agent group

auto resolves to the agent’s directory name. This lets each agent have private memory while still reading from the shared pool.

Q Are agents Claude?

Yes. Every agent is Claude operating in a defined role. The system prompt says so explicitly. Agents are not a rebrand, a fine-tune, or a separate model. This is required by Anthropic's usage policy.

Q How do I create a new agent?

The easiest way is to chat: tell Daemion what role you need and it will create the agent directory and YAML. You can also POST to /extensions with type agent, then call POST /reseed to sync it into the registry.

Q What happens if soul.md doesn't exist yet?

The agent runs the soul-building onboarding flow — a structured first conversation to learn about the user. When it has enough context, it calls the write_soul tool to persist the base soul file.

Q Can agents talk to each other?

Indirectly. Agents share a Engram memory group and can use search_all to read other agents' conversation turns. Direct agent-to-agent messaging is not a built-in feature — use job chains for orchestrated multi-agent workflows.

Always call POST /reseed after editing agent files

Editing daemion.yaml, soul.md, or system.md on disk does not automatically update the running gateway. Call POST /reseed to sync. No restart needed.

For the agents API and creating agent identities programmatically, see Agents and Identity API. For creating agents as extensions, see Extending: Agent.