---
title: Architecture
description: "The mental model behind the codebase: lattice, actors, supervisors, memory tiers, isolation."
---

# Axocoatl Architecture

A practical overview of how Axocoatl runs and coordinates agents.

## The big picture

```
            ┌─────────────────────────── axocoatl daemon ───────────────────────────┐
 CLI / HTTP │  ProviderRegistry   AgentRegistry   EventLattice   McpToolRegistry     │
   clients ─┼─▶ (per-agent LLMs)  (ractor actors)  (pheromones)   (MCP tools)         │
   (IPC)    │        │                 │                │                            │
            │        └──────── DefaultAgentBehavior ─────┘                            │
            │            session mem → budget → LLM → tools → checkpoint              │
            └────────────────────────────────────────────────────────────────────────┘
```

The **daemon** (`axocoatl-daemon`) bootstraps everything: providers, agents
(spawned as `ractor` actors), the event lattice, MCP connections, and the
activation loop. `axocoatl dev` adds a Unix-socket IPC server; `axocoatl serve`
exposes the HTTP API.

## Agents

Each agent is a `ractor` actor running `DefaultAgentBehavior`. On every turn:

1. Append input to **session memory** (Tier 1).
2. Build the request, injecting **long-term memory** (Tier 3) facts.
3. **Token budget** pre-flight check (`abort` / `warn` / `summarize`).
4. Call the agent's **provider** (Ollama, OpenAI, Anthropic, …).
5. Run any **tool calls** (built-in or MCP) with hooks, up to 10 iterations.
6. **Checkpoint** the session to disk (Tier 2) for crash recovery.

On shutdown, agents distill the session into long-term memory facts.

## Token budgets

Per-agent `token_budget` with `per_call`, `per_execution`, and an
`overflow_policy`:

- `abort` — refuse the call and terminate the agent (no wasted tokens)
- `warn` — log and continue
- `summarize` — (compaction hook)

Budgets are checked **before** the LLM call, so an over-budget request never
costs tokens.

## Stigmergic coordination

The differentiator. Agents declare `depends_on`; the daemon registers each in
an `EventLattice` with a pheromone threshold:

- **Entry agents** (`depends_on: []`) — activated directly by
  `execute_workflow` with the user input.
- **Downstream agents** — threshold = `N × 0.5` where N = number of
  dependencies. Each upstream `TaskCompleted` event emits a signal of strength
  `0.5`; when accumulated signal crosses the threshold, the agent activates and
  receives its upstream outputs as context.

There is **no scheduler**. Coordination emerges from events:

```
execute_workflow → activate entry agent
   → agent completes → publish TaskCompleted
       → lattice raises downstream pheromone signals
           → threshold crossed → downstream agent activates
               → … → all expected agents done → workflow returns
```

A cycle guard (`max_activations = agents × 3`) and acyclic-DAG validation make
runaway activation impossible.

This stigmergic event lattice is the **shipped** coordination layer. There is
no scheduler and no central orchestrator — coordination is entirely emergent
from `depends_on` declarations and `TaskCompleted` signal strength.

### Planned layers (roadmap)

Two further primitives are **built but not yet integrated** into the running
system. They live in `axocoatl-coordination` (sub-microsecond, fully
unit-tested), but the daemon does not invoke them today. Both are planned to
sit *on top of* the shipped lattice:

- **HTN planner** (roadmap) — symbolic task decomposition without LLM calls.
  Would sit *above* the lattice: decompose a goal into subtasks that publish
  into the lattice, which then fans them out as usual.
- **Auction** (roadmap) — deterministic agent selection by tool capability,
  load, and remaining token budget. Would refine *dispatch*: when several
  agents contend for the same activation, pick one instead of fanning out to
  all.

## Memory tiers

| Tier | What | Persistence |
|---|---|---|
| 1 — Session | conversation transcript | in-memory |
| 2 — Checkpoint | agent state snapshots | disk (pruned to 3) |
| 3 — Long-term | distilled facts | disk (bincode) |
| 4 — Neural | semantic vector recall (Candle + all-MiniLM-L6-v2, 384-dim embeddings, ~90 MB model, hash fallback) | disk |

## Protocols

- **MCP** — the daemon connects to configured `mcp_servers` (stdio or
  streamable-http) at bootstrap and exposes their tools to agents; agents can
  also be exposed *as* MCP tools.
- **A2A** — agent-to-agent interop for cross-framework workflows.

## Sandbox isolation

Directory sessions run inside a **hardened rootless podman container** — this
is the shipped isolation tier. Additional tiers (a Wasmtime/WASM tier and
OCI/Firecracker-class microVM isolation) are **roadmap**, not shipped today.

## Crate map

`axocoatl-core` (types) · `axocoatl-token` (budgets) · `axocoatl-llm*`
(providers) · `axocoatl-config` · `axocoatl-actor` (runtime) ·
`axocoatl-memory` · `axocoatl-coordination` (shipped lattice; HTN/auction
primitives built, not yet integrated) · `axocoatl-graph` · `axocoatl-mcp` ·
`axocoatl-a2a` · `axocoatl-tools` · `axocoatl-isolation` (rootless podman
sandbox; WASM tier roadmap) · `axocoatl-daemon` · `axocoatl-server` ·
`axocoatl-cli`.
