Concepts & Architecture

This page gives you a mental model of how InitRunner works before you dive into specific features.

The Role File

Every InitRunner agent starts with an agent file — a single YAML document that describes what the agent is, what it can do, and how it should behave. The file is the agent. There is no apiVersion / kind / metadata / spec wrapper.

name: my-agent
description: What this agent does
tags: [category, purpose]
model: openai:gpt-5-mini
prompt: |
  System prompt goes here.
tools: [...]
memory: { ... }
ingest: { ... }
triggers: [...]
sinks: [...]
autonomy: { ... }
reasoning: { ... }
guardrails: { ... }

Everything except name and prompt is optional — a minimal agent only needs a name and a system prompt. Old envelopes still load; convert them with initrunner doctor --fix. See Envelope Migration.

Architecture Overview

Input — An agent run is initiated by one of three paths: loading a role file directly, interactive CLI input, or an event trigger (cron, file watch, webhook, Telegram, Discord). Prompts can include multimodal attachments (images, audio, video, documents) — see Multimodal Input.

Runtime — The parser validates the YAML and hands it to the LLM Adapter — the internal client object that wraps a specific provider SDK (OpenAI, Anthropic, Google, etc.). This is distinct from the model.provider string in your agent file, which is just the name used to select the adapter. The adapter creates an agent that orchestrates tool calls, memory reads/writes, and document searches during execution.

Output — Results flow to configured sinks (Slack, email, file, delegate to another agent), the audit log (SQLite), and back to the caller as a response.

Core Building Blocks

Tools

Tools give agents the ability to act. InitRunner supports 28 configurable tool types plus auto-registered tools:

Each tool is sandboxed by the guardrails system. See Tools for the full reference.

Skills

Skills are reusable prompt-and-tool bundles that can be attached to any agent. They let you share common capabilities (e.g., "summarize a webpage", "query a database") across multiple agents without duplicating configuration. See Skills.

Memory

InitRunner's memory system has two distinct parts:

Session persistence (short-term) — Conversation history is saved to SQLite during REPL and daemon runs. Use --resume to reload the most recent session. This is not a "memory type" — it's automatic when memory is configured and is always available.

Long-term memory types — Three typed stores backed by vector embeddings:

• Semantic — Facts and knowledge. The agent stores and retrieves these explicitly via remember() and recall().
• Episodic — Records of what happened during tasks — outcomes, decisions, errors. Auto-captured in autonomous and daemon modes, or written explicitly via record_episode().
• Procedural — Learned policies and patterns, stored via learn_procedure() and auto-injected into the system prompt on every run.

Automatic consolidation extracts durable semantic facts from episodic records using an LLM. See Memory.

Ingestion & RAG

The ingestion pipeline converts documents into searchable vector embeddings:

1. Glob source files
2. Extract text (Markdown, PDF, DOCX, CSV, HTML, JSON)
3. Chunk into overlapping segments
4. Embed with a provider model
5. Store in LanceDB

At runtime, the auto-registered search_documents tool performs similarity search against the stored vectors. Retrieval can run as pure vector search or as hybrid search that combines vector and keyword scoring, and embeddings can come from a provider API or an in-process local: model. See Ingestion, RAG Guide, and Providers.

Execution Lifecycle

1. The user invokes the CLI with a role file and a prompt.
2. The runtime parses the YAML, resolves the provider, and sends the system prompt + user message to the LLM. If the prompt includes attachments, they are resolved (local files are read, URLs are fetched) and sent as multimodal content parts.
3. The LLM responds — possibly requesting tool calls.
4. The runtime executes each tool, logs the action to the audit database, updates memory, and feeds the result back to the LLM.
5. This loop continues until the LLM produces a final response (or a guardrail limit is hit).
6. The final response is returned to the user and sent to any configured sinks.

Execution Modes

InitRunner supports several execution modes for different use cases:

Choosing a multi-agent shape

The shape of the YAML decides which one you get, so there is no kind: to set:

Flows add routing on top of plain delegation: ensemble voting across several targets and loop-back routing that re-runs a step until a condition holds. Agents in a flow can coordinate through a shared blackboard, and a flow run checkpoints its state so it can resume after a restart (Durability).

Safety Layers

InitRunner enforces safety at multiple levels:

• Guardrails — Token budgets, tool call limits, iteration caps, and timeouts. Prevents runaway agents.
• Security — Shell command allowlists, filesystem sandboxing, confirmation prompts for destructive actions, HMAC webhook verification.
• Audit — Every tool call, LLM interaction, and agent run is logged to a SQLite database for inspection and compliance.

These layers work together so you can give agents powerful tools while keeping them within safe boundaries.