Skip to content

04 — Core Concepts

This is the vocabulary chapter. Every term The Aetherium Engine uses in the rest of this documentation set is defined here, in one place. Later sections cross-link back when they need a precise definition; if a concept feels unclear in §05 or §06 or §11, this is where the unambiguous source lives.

An Agentic AI primer

If you have already shipped something with CrewAI, LangGraph, or AutoGen, skim this section and move on. If you are arriving fresh from a "single prompt in, single answer out" mental model of LLM apps, the next five paragraphs are the minimum vocabulary the rest of the doc set assumes.

LLMs as function callers. A modern instruction-tuned LLM does more than emit text — it can emit structured tool calls in its response. The host application supplies a list of available tools (JSON Schema for each), the model chooses to call zero or more of them in its turn, the host executes them, and the host hands the results back to the model on the next turn. The model never executes anything itself; it only proposes calls. This is the entire foundation.

The ReAct loop. Reason → Act → Observe → repeat. The host reads the user's message, asks the LLM to think and choose a tool, executes that tool, feeds the result back in, asks the LLM to think again, and continues until the LLM emits a turn with no tool calls — that turn is the final answer. This is the loop that drives every agent in the Engine.

Multi-agent patterns. One model running one loop hits ceilings fast. Production agentic systems split work across multiple cooperating agents: a supervisor that plans and delegates, workers that specialize, sometimes a pipeline where each stage hands off to the next, sometimes a panel where everyone weighs in. Trading off cost against quality against predictability is most of what designing an agentic system is about.

What MCP standardizes. The Model Context Protocol is the contract between a host that runs LLMs and a server that exposes tools. The server advertises tool schemas, the host invokes tools by name with structured arguments, the server returns structured results. The point of the standard is interop — a tool server written once can plug into any compliant host. The Engine hosts its MCP servers in-process, so the wire protocol becomes method invocations on classes registered in the DI container, but the schema discipline is the same.

Why local-LLM orchestration is hard. Smaller, locally-hosted models follow tool-call conventions less reliably than frontier models. Context windows are finite, so long conversations need truncation. Different models have different quirks around JSON formatting, instruction following, and when they will or will not stop calling tools. The Engine's design — the scheduler, the context manager, the planning loops, the circuit breakers — is mostly there to make small local models behave like reliable workers despite these constraints.

Agent

An Agent is the basic unit of execution in the Engine. The shape is the same four pieces every time:

  • Persona — a human-readable identity (name, role title, description).
  • System prompt — the prose that defines how the agent thinks and acts.
  • Tool allowlist — the specific tools the agent is allowed to call.
  • Model assignment — which LLM runs the agent's turns.

A concrete example, lifted directly from Templates/fullstack-web.json:

Piece Value
Name Backend Developer
Role worker
Model google/gemma-4-e4b
Description API routes, database models, middleware, and server-side logic.
Tools read_file, write_file, edit_file, list_files, search_files, todo, revert_file, run_shell, read_logs, web_search, send_message_to, reply
MCP server allowlist workspace, shell, research, team, orchestration

The system prompt itself is a few paragraphs of prose that tells the agent its job is to build the API, where its files belong on disk, what port to listen on, and that writing files is not enough — it must npm install and start the server. Four pieces. Nothing else.

Role, Persona, Team

A Role is the database representation of an Agent. When a Project is created, every agent in the team becomes one row in the roles table — that row carries the persona, system prompt, tool allowlist, and model assignment forward across sessions. "Agent" is the runtime concept; "Role" is the persistence-side name for the same thing.

Note: the word "role" appears in two contexts in the Engine. Inside a template JSON, role is the agent's kind — "supervisor", "worker", or similar. In the database, Role is the row that persists an agent's configuration. These are different uses of the same word; context tells you which.

A Persona is the human-readable identity an agent presents in the UI — name, role title, description, and (eventually) avatar. The Backend Developer's persona is "Backend Developer" with the description above.

A Team is a group of Agents wired together by a Topology.

The four topologies

The Engine ships four topologies for wiring a Team together. They are exactly:

Topology When to use Typical agent count Example template
Hierarchical Complex tasks with clear delegation paths 3–8 fullstack-web
Sequential Pipelines where each stage builds on the previous 2–5 sequential-docs
Roundtable Brainstorming, debate, multiple perspectives 3–6 roundtable-review
Single One agent, one task 1 quick-script

Here is what each shape looks like as an agent graph:

flowchart TB
    subgraph H[Hierarchical]
        direction TB
        HS[Supervisor]:::sup
        HW1[Worker 1]:::wrk
        HW2[Worker 2]:::wrk
        HW3[Worker 3]:::wrk
        HS --> HW1
        HS --> HW2
        HS --> HW3
    end
    subgraph S[Sequential]
        direction TB
        SA[Stage 1]:::wrk
        SB[Stage 2]:::wrk
        SC[Stage 3]:::wrk
        SA --> SB --> SC
    end
    subgraph R[Roundtable]
        direction TB
        RU((User)):::ext
        RA[Agent A]:::wrk
        RB[Agent B]:::wrk
        RC[Agent C]:::wrk
        RU --> RA
        RU --> RB
        RU --> RC
    end
    subgraph SI[Single]
        direction TB
        SIA[Agent]:::wrk
    end

    classDef sup fill:#B87333,stroke:#2D2D2D,stroke-width:2px,color:#FFFFFF
    classDef wrk fill:#8FA68A,stroke:#2D2D2D,stroke-width:1.5px,color:#1A1A1A
    classDef ext fill:#D5C3B0,stroke:#2D2D2D,stroke-width:1.5px,color:#1A1A1A

In Hierarchical, the supervisor (an agent whose role is to plan and delegate) reads the task, builds a plan, and dispatches each step to a worker via the delegate tool. In Sequential, every stage receives the original task as its message, with the previous stage's output injected once as a labeled context block; a stage that owes files and did not leave them gets two repair turns carrying the gate's own sentence, and a stage that still fails aborts the pipeline with a failed-at-stage-N status instead of letting later stages run on stale input. A checking stage that ends on VERDICT: FAIL sends the work back: each earlier stage whose files the report names is re-run once with the report's lines about those files, then the checker checks again. A checker whose FAIL report names no file another stage owes is refused once and shown those files, so it can say which one is wrong; a FAIL that still names none, or survives the one send-back, fails the run with the report. The plan path does the same for a checker step and the steps that own the files it names, and also when the checker's own quality check (a failing run_tests, say) names files an earlier step owns: those steps are re-run with the failure lines about their files instead of the checker being asked to repair code it does not own. Each stage also writes only its own lane: a write to a file another stage owes is refused, so a later stage cannot change an earlier stage's checked work — a site stage rewriting the narration script after it was recorded had left a recording of a script that no longer existed. In Roundtable, discussion runs over a configurable number of rounds (config.discussion_rounds, default 2): round one collects every agent's independent answer in parallel, later rounds show each agent the others' previous-round responses to critique and reconcile, and the final round doubles as consolidation of the shared workspace artifact. In Single, one agent runs the ReAct loop alone; when its node owes files, it is held to them like a Sequential stage, with the same two repair turns, and an agent still owing after them fails its step and the run. None of the shipped Single templates owes files. A fifth dispatch shape, dynamic-parallel, exists in the orchestrator for advanced patterns where worker count is decided at planning time rather than at template-design time — it powers research-team.json today. It is not promoted to a first-class topology in templates and is covered in §08 — Templates.

Project, Workspace, Template

Three more terms, in creation-to-execution order:

  • Template — the JSON blueprint that wires a Team's topology, agents, tools, and scaffolding. Templates/fullstack-web.json is a Template. The locked product name for a Template surfaced in the UI is a Workflow Template.
  • Project — what gets created when you instantiate a Template. The database row plus the chat history plus the team's working area; the thing you click on in the sidebar.
  • Workspace — the on-disk directory tree where agents read, write, and execute files for a Project. Bind-mounted into the per-project Docker container that the agents shell into.

Quick Create and Unified Studio

Quick Create is the natural-language alternative to picking a Template: describe what you want, the Engine's team generator builds a Team for you. The result is still a Project plus a Workflow Template — Quick Create just bypasses the catalog and synthesizes the JSON on demand.

Unified Studio is the visual workspace where you chat with the team, watch tool calls stream in, and inspect the team graph. You opened it in §02 — Getting Started the first time the chat input went live after the workspace finished provisioning.

MCP server, Tool, and the three-layer permission model

An MCP server in the Engine is a focused capability boundary — a class that groups related tools and exposes them to agents through a single contract. The Engine ships twelve MCP server classes (one each for workspace files, shell execution, web research, knowledge base access, code quality, planning, user communication, orchestration, team messaging, image and video generation via ComfyUI, voice-over, and the Steam Frame headset). The depth — which class hosts which tools, how to add new ones — lives in §07 — MCP Architecture.

A Tool is one method on an MCP server class — write_file, run_shell, delegate, search_knowledge, and so on. Each tool is described by a JSON Schema that the LLM sees during tool-call discovery, so the model knows what arguments to send.

The three-layer permission model controls which agents can call which tools. The layers, in order:

  1. Connection layer. Each agent's template entry declares an mcp_servers allowlist (the list of MCP server classes the agent is even allowed to see). The Backend Developer above can reach workspace, shell, research, team, and orchestration — nothing else.
  2. Capability layer. Within an allowed MCP server, the agent's tools list narrows further to specific methods. McpToolRouter filters tool schemas to exactly that subset before the LLM ever sees them, so the model cannot call a tool it does not know about.
  3. Runtime layer. Some tools are tagged with a security level — Standard, Elevated, or Restricted — and ToolApprovalService intercepts calls based on the level. Standard executes immediately with basic audit. Elevated logs full input and output. Restricted requires a human approval gate before execution.

§07 — MCP Architecture covers the mechanism end-to-end.

Knowledge base and RAG

The Knowledge base is the searchable store of background information available to a team. It lives in ChromaDB and is split into per-project collections (the project's own knowledge, seeded from docs and templates), domain collections (a team's target_collections, shared by every team that names them, and taking a project's document only once the owner approves it) and one global collection holding the curated knowledge packs. Each agent reads a scope of it: its team's packs, its domains and its project. An agent with the search_knowledge tool in its allowlist queries that scope like any other tool, and the Engine injects the best matches before an agent's turn.

RAG is the retrieval pattern that backs it: retrieval-augmented generation. A query string is embedded into a vector, ChromaDB's approximate-nearest-neighbor index returns the most similar chunks within the scope, and those chunks are injected into the LLM's prompt as reference data. The implementation — embedding model, chunking strategy, score thresholds — lives in §06 — Key Services under ChromaDbRagService.

Memory

Memory is the per-agent state that survives across turns. The Engine keeps two tiers:

  • Working memory — overwritten per session, like a scratch pad of the current task and recent state. The orchestrator updates it as the conversation progresses.
  • Long-term memory — append-only, accumulated across sessions. The supervisor and the LessonService write to it; agents read it at turn start.

Memory rows can be scoped at the Project level (every agent on the team can read them) or at a specific agent (only that agent sees them). The mechanism — when the orchestrator injects memory into the prompt, the token budget, the relevance scoring — is in §06 — Key Services.

Knowledge vs Memory

Knowledge base Memory
Scope The team's packs, domains and project Per-project, optionally per-agent
Storage ChromaDB PostgreSQL
Lookup Semantic search via search_knowledge, and injection before a turn Automatic injection by the orchestrator at turn start
Who writes Deliberate ingestion (KB tools, seeding workflows) The orchestrator and the lesson service; agents read
Who reads Any agent with search_knowledge in its allowlist Only the agent the memory belongs to

The knowledge base is shared, queried, and large. Memory is private, automatic, and small.

Plan, Reflection, Lessons, Re-planning, Circuit breaker

A Plan is a structured step list that a supervisor builds via the create_plan tool. Each step names what gets done, which agent is responsible, and which tools that agent must invoke to count the step as complete. The supervisor delegates the team against the plan in order, marks each step done as it succeeds, and synthesizes the final response when the plan finishes. A step that fails — by its gate, its timeout or an exception — puts back the text files it changed to what it found when it started, so a re-plan or a send-back starts from the last good state rather than a half-rewritten page. Files the step created stay for the re-plan to see, and so do its own verdict reports. One failure keeps its files instead: when a step's only failure is its own run_tests, and its last run passes more tests than its first, fails fewer and runs no fewer, the step's files stay (logged [STEP-KEEP]) and the re-plan is told which tests still fail. A step that owes the project's root package.json, or writes it or the file its start script runs, must also start (and is started again after a verifier repair that changed either): the Engine runs its npm start in the team container for up to 20 seconds and fails the step, with the start script's error lines as the repair note, when nothing answers on the port project-config.md names. A step that owes a page is checked against the app's own server: the Engine copies the workspace, starts the app from the copy on the container's second published port (so the check's submits never reach the project's data), and in a headless browser submits the page's first form twice with two different entries or presses its main button. It fails the step when any same-origin /api/ request answers 4xx or 5xx other than 409 (a server refusing on its data's state, such as an item out of stock), naming the method, path, status and body, or when the page leaves its submit or checkout control disabled for the next entry. A later step that changes the app's code reads the run's other pages again, a page whose reading failed is read again at every later check until one passes, and before the run is finalized every page the run owes is read once more against the code it finished with: a failure there fails the run. Both checks pass a step they cannot run (no container, no start script, no browser).

Four further orchestration internals build on top of Plans:

  • Reflection — a deliberate self-critique turn the supervisor takes between a worker's reply and the synthesis step. Handled by ReflectionService.
  • Lessons — per-task notes accumulated by the supervisor and persisted by LessonService for use in later planning.
  • Re-planning — when a step fails or produces an unexpected result, the supervisor amends the running plan with update_plan rather than blindly retrying; it cannot replace the plan with a new one.
  • Circuit breaker — a fail-fast threshold (max turns per agent, step timeout, re-plan cap, infinite-loop detection) that halts runaway loops before they burn the GPU. CircuitBreakerService enforces it.

The depth — exactly when each fires, the trigger conditions, the recovery paths — is in §06 — Key Services.

Context window

A context window is the LLM's input length limit, measured in tokens. The Engine's ContextManager enforces a per-team window configured per-template (typically in the tens of thousands of tokens, depending on the model and the workload). When the budget runs out, the manager truncates older conversation — keeping the first message (system prompt and task framing) and the last two messages (recent context), and dropping oldest middle messages first. The implementation, the precise budget math, and the per-template configuration are in §06 — Key Services and §09 — Configuration.

How a message flows — naming every concept

Here is a real Hierarchical message flow with every concept above named as it appears:

The user sends a message into a Project. The message lands at the supervisor Agent (Project Lead). The supervisor reads the Workspace's project-config.md via the read_file Tool, queries the Knowledge base for relevant background via search_knowledge (this is the RAG call), and the orchestrator injects any relevant Working memory into the prompt at turn start.

The supervisor builds a Plan via create_plan, then delegates the first step to a worker — this is the Hierarchical Topology in action. The worker's call to write_file is allowed because (a) workspace is in its MCP server allowlist (connection layer), (b) write_file is in its Tool allowlist (capability layer), and (c) write_file is a Standard-level tool so ToolApprovalService lets it through (runtime layer). That is the three-layer permission model.

The worker writes the file, replies to the supervisor, and the supervisor runs a brief Reflection turn before moving on. A step run by a reporting role (one the role library marks requires_evidence) also passes an evidence gate first: it fails unless the agent searched, cited a source, and every URL it cited appeared in a search result or a fetch during the step. A step that wrote files but failed that gate is recorded as an evidence gap: its files are moved out of the workspace to .evidence-rejected/step-N/, the step's status is skipped, and the run carries on with what is sourced instead of re-planning. Any later step whose description names one of the withdrawn files is corrected before it runs, so it cannot be told to verify, link or count a file that is no longer there. If the step fails for any other reason, the supervisor re-plans. If the worker hits the per-agent Circuit breaker turn limit, the orchestrator stops it. When the plan finishes, the supervisor synthesizes, the Lessons service records what worked, and the response streams to the user through the real-time layer covered in §03 — System Architecture.

Every bolded term above is defined somewhere earlier in this section. If any of them felt unclear in the walkthrough, that is the signal to read its subsection again.

Where to go next