What are agents?

An agent is a persistent identity layered on top of Daemion. The runtime system prompt says:

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

Agents are not separate AIs and are not rebrands. Every agent is a Daemion agent operating in a defined role with a specific soul, system prompt, model, permissions, and knowledge surfaces.

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 substrate. 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 identity and role specialization.

user-profile.md — the user’s preferences, communication style, and working patterns.

A base soul at ~/.daemion/soul.md captures the shared Daemion identity. A shared user profile at ~/.daemion/user-profile.md captures user-level facts shared across all agents. Each agent also has its own soul.md for role-specific identity and can optionally have an agent-specific user-profile.md override.

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.

Knowledge memory

Each agent can access the shared knowledge substrate plus its own personal wiki. Configure in daemion.yaml:

yaml

memory: knowledge: true

Each agent gets its own wiki at ~/.daemion/agents/<name>/knowledge/ and also reads shared knowledge from ~/.daemion/knowledge/wiki/.

Q Are agents Claude?

Every agent is a Daemion agent operating in a defined role. Agents are not a separate model or product rebrand; they share the same runtime identity and specialize through soul, system prompt, and model choice.

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 user-profile.md doesn't exist yet?

The agent runs the user-profile-building onboarding flow — a structured first conversation to learn about the user. When it has enough context, it calls the write_user_profile tool to persist the shared user profile.

Q Can agents talk to each other?

Indirectly. Agents share the knowledge substrate 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.