> ## Documentation Index
> Fetch the complete documentation index at: https://internal.september.wtf/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture overview

> How the Engine is built — the one-page mental model every engineer should hold in their head.

The Engine is a headless, single-tenant agentic runtime. It exposes an HTTP
API, runs an agent loop against a configurable LLM provider, executes tools
inside a hardened sandbox, and remembers what happened in a per-user SQLite
brain. Everything else — the UI, the user accounts, the billing, the routing
across users — lives upstream of the Engine, not inside it.

This page is the C4 Level 1 view: the Engine as a black box and what's
around it. For Level 2 (containers and the boundaries between them), see
[Containers](./containers).

## The one-paragraph version

A client (a chat product, a CLI, a backend service) sends an HTTP request
with a user message, an agent definition, and a session identifier. The
Engine streams back a server-sent event stream of reasoning, tool calls,
permission prompts, and final output. While that stream is flowing, the
Engine talks to an LLM provider, possibly invokes external tools through the
Asset Directory (MCP), reads and writes the user's memory, and runs sandboxed
commands. When the conversation ends, an asynchronous Learning Centre batch
distills the trajectory into episodes and knowledge facts that make the next
conversation cheaper and smarter.

## System context

```mermaid theme={null}
flowchart TB
    Client["Client / Product<br/>(chat UI, CLI, backend service)"]
    Engine["Engine"]
    LLM["LLM provider<br/>(Anthropic / OpenAI / Gemini)"]
    Brain["Per-user brain<br/>(SQLite + sqlite-vec)"]
    Sandbox["Sandboxed tools<br/>(bwrap + seccomp + landlock)"]
    MCP["External MCP servers<br/>(via Asset Directory)"]

    Client -->|HTTP + SSE| Engine
    Engine -->|talks to| LLM
    Engine -->|reads/writes| Brain
    Engine -->|invokes| Sandbox
    Engine -->|invokes| MCP

    classDef external fill:#f4f4f5,stroke:#71717a,stroke-width:1px
    classDef core fill:#0F172A,stroke:#0F172A,color:#fff,stroke-width:2px
    classDef store fill:#fef3c7,stroke:#a16207,stroke-width:1px
    class Client,LLM,MCP external
    class Engine,Sandbox core
    class Brain store
```

## The four primitives

The Engine is organized around four primitives. If you understand these,
everything else is detail.

### 1. The agent loop

The core loop. It receives a message, sends it to the LLM, receives a
response (with possible tool calls), executes the tools, feeds the results
back, and repeats until the model decides it's done or asks for human input.
The loop is implemented in `engine_core/coordinator.py` and
`engine_core/agent_loop.py`. Everything else exists to feed this loop
better, faster, or cheaper.

### 2. Memory

Three memory stores, all persisted in a per-user SQLite brain database, all
queried through the same hybrid search (vector + keyword):

* **Episodes** — what happened (events, conversations, outcomes).
* **Knowledge** — what's true (facts, rules, heuristics, with confidence and
  validity windows).
* **Social graph** — who's who (people, relationships).

Plus working memory for transient context inside one execution, plus a
"soul" — the user's core identity and learned patterns.

### 3. Tools

Tools come from three places:

* **Platform tools** — built-in operations (read file, write file, bash,
  etc.) registered in the Utility Directory.
* **Asset Directory connectors** — external services reached via MCP (Slack,
  Gmail, Notion, etc.), with per-user OAuth and encrypted credential
  storage.
* **Skills** — composed prompts and small scripts that wrap a recurring task
  (summarize, fact-check, format).

All three execute through the same dispatch interface. The agent loop
doesn't know or care which kind of tool it's calling.

### 4. The sandbox

Every tool that touches the system runs inside a sandbox. The sandbox
combines `bwrap` (filesystem isolation), `seccomp` (syscall filtering),
`landlock` (filesystem ACLs), and a permission prompt layer that can ask the
user before doing anything dangerous. The sandbox is implemented under
`src/sandbox/` and is the difference between "AI agent that helps" and "AI
agent that wrecks your machine."

## The execution lifecycle

A single user turn moves through these phases:

1. **Receive.** `POST /execute` arrives with a message and a `task_id`. The
   server validates the API key, finds or creates the channel state for
   this task, and starts the SSE stream.
2. **Plan.** If the request needs planning, the Engine runs a planner
   sub-agent against a charter — the user's request expanded into a set of
   sub-goals.
3. **Loop.** The coordinator drives the agent loop: build context, call the
   LLM, parse tool calls, execute tools (in sandbox or MCP), append results,
   repeat.
4. **Compact.** When context grows past safe limits, the
   compaction orchestrator collapses older turns into summaries while
   preserving structured artifacts (file contents, tool results worth
   keeping).
5. **Stream.** Throughout, the server emits SSE events — text deltas,
   thinking blocks, tool calls, tool results, HITL prompts.
6. **Persist.** Working memory updates as the loop runs. Channel state
   snapshots periodically so the stream can be resumed if the client
   reconnects.
7. **Close.** When the model stops or the user pauses, the Engine writes a
   trajectory record. The Learning Centre will pick it up on its next batch
   to consolidate into long-term memory.

## What the Engine is not

It helps to be explicit about boundaries.

* **Not multi-tenant.** The Engine runs against one brain at a time. Multi-
  user isolation happens upstream — each user gets their own Engine instance
  (or their own data directory).
* **Not a UI.** No HTML, no web interface, no admin panel. The HTTP API is
  the entire surface.
* **Not a model.** The Engine runs against external LLM providers. It does
  not host weights.
* **Not a chat app.** Conversation threading state is exposed, but the
  Engine doesn't render chats, manage rooms, or handle user accounts.
* **Not a job scheduler.** The Engine doesn't queue background work for
  arbitrary callers. It does run a Learning Centre batch on its own
  schedule.

If you're building something that wants those things, build it on top of
the Engine. Don't add it to the Engine.

## Where to go next

* [Containers](./containers) — the C4 L2 view: services, queues, databases,
  the boundaries between them.
* [Components](./components) — module-level structure inside each
  container.
* [Data flow](./data-flow) — what calls what, end to end, for a single
  request.
* [Shared types](./types) — the contracts between modules.