How it works

Architecture

A Go core that orchestrates and does no tensor math, five memory systems behind one retrieval layer, three modes that fence what the model can reach, and a boot sequence where every degraded tier is still usable. This page is the whole design.

Source This page follows the architecture map maintained in the repository — twenty-three subsystems, ninety-nine components. Where a number appears here it was measured, and where a limit is stated it is stated because it is real.

The Go core

Orchestration only. No tensor math. A single static binary. The core runs the agent loop, dispatches tools, manages context and holds state. It never spawns or supervises a model server — it pings endpoints.

Only one layer coordinates. That is what keeps a mechanism replaceable without touching the loop that calls it.

Core Skills

A procedural spine baked into the binary: how to tool-call, how to answer without filler, how to work and research. Not learned, not editable. It is the invariant system prefix, which matters for more than tone — keeping it stable is what lets the engine's prefix cache survive across turns.

The cycle

Observe, think, act, repeat.

Observe

Builds the window: pinned zone, memory pulls, episodic tail. Enforces the token budget before the call, not after.

Think

One OpenAI API call per iteration. A per-mode GBNF grammar constrains output to tool calls or a final answer. The mode module is appended at the end of the system prompt so the Core Skills prefix stays cacheable across mode switches.

Act

Parses and executes. Arguments pass the dispatch guard first. Every call and result is appended to the episodic log.

Iteration guard

Max iterations, token and time budgets, and detection of repeated identical calls. Trips to a forced stop with state preserved.

Stop conditions

Final answer, guard tripped, error threshold, user interrupt, or plan drift in Autopilot. Every exit is logged so resume is clean.

Two details in Act worth knowing Bash runs each command in its own process group and kills the whole tree on timeout, so a backgrounded child cannot leak and hang the tool. And on failure the command's real stdout and stderr are kept and returned to the model rather than replaced by a bare exit status 1 — a model cannot self-correct from an exit code.

The five memories

All five live behind one retrieval layer, and one Typesense instance holds every type, tagged by memory_type.

Turn close runs after the answer has already reached you, so a failure in note-taking costs nothing.

1 · Working — the recall layer

System-owned, never model-invoked. It fires automatically at turn start and on context shifts: a steer, a plan-step change, an error (which pulls similar past errors and their fixes). The query is built from current context, ranked by hybrid vector plus keyword, deduped by document id, and budget-capped into memory pulls.

It merges the Typesense index with the live tail of events.jsonl, so async indexing lag can never hide a recent event.

2 · Episodic — the session log

Append-only and immutable: messages, tool calls and results, decisions, plan state, timestamped events. One JSONL per session — replayable, crash-safe, git-friendly. Read directly by the core and not searched; searching is Typesense's job.

A write-behind indexer keeps a cursor on the last indexed event. If Typesense goes down the cursor stalls while events keep appending; when it returns, indexing replays from the cursor. Self-healing, because the file is the source of truth.

3 · Semantic — curated, cross-session

Facts, decisions and preferences. Written by the remember tool and by promotion from episodic. Four properties matter:

Single writer. The curator serialises all writes — no races.
Never deletes. Corrections supersede, through a superseded_by chain.
Provenance on every document — the source episodic event ids, so "why do you think this?" is always auditable.
Degrades without losing writes. If Typesense is down, candidates park as pending_semantic episodic events and drain through the dedup gate on recovery.

The dedup gate embeds each candidate and runs k-NN against existing documents:

Similarity	Action
> 0.9	Merge into the existing document: bump confidence and `last_seen`, add a source reference.
0.7 – 0.9	Create, and link `related_to`. Surfaced in the panel for review.
< 0.7	A new document.

4 · Codebase — the structural graph

Pure-Go extraction: go/ast for Go, tuned regex for eleven other languages. No tree-sitter and no cgo, which is a core reason the project is in Go at all — it keeps the single static binary. Definitions and call edges, re-indexed incrementally on mtime.

Stored in SQLite rather than Typesense, because the repository is the source of truth and the graph rebuilds from it in seconds. Measured against read plus grep: about 10× lower token cost and 2.1× fewer calls.

5 · Procedural — skills

A folder of markdown skills the user adds. Progressively loaded only when relevant, so the window stays lean. Prose playbooks stay documentation; executable capability migrates to RFX.

Window management

Memory is the state; the window is a projection. Nothing is destroyed when the window shrinks — the stores still hold it.

Append-mostly

Each iteration appends at the tail so the engine's prefix cache survives. A full re-render happens only on resume or a mode switch.

Pinned zone

Core Skills, the mode module, active plan state, and the latest user steer. Never dropped.

Memory pulls

Ranked recall, semantic facts, skill docs, code outlines. The first zone to shrink, because the raw data is still in the stores and can be pulled again.

Episodic tail

The last K events. Raw tool outputs age out to event-id pointers.

Ingress caps

Tool results are capped at dispatch, before they ever touch the window. Full fidelity lands in episodic; the window sees the capped head plus a pointer.

The watermark policy decides when to act, counted with the real tokenizer rather than estimated:

Zone	At	Action
Green	< 60%	Append freely.
Yellow	80%	Batch-demote the oldest raw content to pointers — one cache invalidation, not churn. The pinned zone is untouchable.
Red	95%	Forced handback or a hard tail trim.

Per-mode budget profiles differ: Discussion runs a small tail with capped prose, Brainstorming a large pulls budget with research externalised to notes, Autopilot a fresh window of plan payload plus step-scoped pulls. Implementation detail is on Context window.

The tool registry

Single source of truth for tools, grammars and guards. Each entry carries name, argument schema, mode matrix, risk tier, ingress cap, retry class and executor.

GBNF is generated, never hand-written The grammar is derived from the tool schemas. A registry change rebuilds it before the next Think — no restart, and no possibility of a grammar drifting out of sync with the tools it constrains.

Thirteen default tools are baked into the binary. Recall is deliberately absent from the mode matrix — it is system-owned and always on. See Tools.

Boot and degradation

Data-first: load config, open the session store, connect Typesense if reachable, panel live. No model is needed to browse. Opening a past session replays its events.jsonl into a read-only window — full history, reports and decisions, with zero components running.

Tier	Needs	You get
T0	files only	Browse and replay every past session.
T1	+ Typesense	Keyword recall.
T2	+ embedder	Vector recall.
T3	+ model endpoint	The full agent, all modes.

Only T3 hard-requires a model. Missing components degrade; nothing crashes. A readiness gate runs parallel checks before anything enters the loop and blocks only what the requested tier actually needs, with a per-component status card and one-tap fix hints.

Turn-boundary hooks

Zero extra inference, zero user wait. Everything below runs after the answer has already been delivered.

turn_close

Turn metadata is distilled by a small async background call after delivery, off the critical path.

Checkpoint

An episodic event at every boundary: plan state, step status, diffs, tool log. This is what makes crash-resume and the final report trivial.

Async promotion

The curator dedups candidates and upserts. Failures are logged and never block the next turn. The panel shows a "n memories saved" badge, not a spinner.

Window reclaim

This turn's raw results demote to pointers; the episodic tail shrinks. The next turn starts lean.

Report render

The final Autopilot report is a render of checkpoint events. Zero extra work at plan end — the hooks did the bookkeeping along the way.

Control flow

Steer

Cancels in-flight work now, appends the message, re-thinks immediately.

Pause

Finishes the current Act, then parks.

Kill

Aborts everything and hands back.

A real steer is flagged before it cancels Every Think and Act runs under a cancellable context. A genuine user steer sets an explicit flag before cancelling, so the loop can tell it apart from an incidental cancellation — a flaky endpoint, a dropped connection. Without that distinction an incidental abort reads as a steer and silently spins the loop to its iteration cap.

The prefix cache survives all three; aborted partials are logged but not kept in the window; and all of them resume through episodic replay.

The verification loop

Three tools exist so the model can check its own work rather than assert it:

serve

bash runs every command in its own process group and kills the tree on return, so a backgrounded server dies instantly — bash structurally cannot host one. serve runs an in-process file server in a goroutine that outlives the tool call, jailed to the workspace, binding synchronously so a port clash is a real error.

check_page

Headless Chromium reporting console errors, uncaught exceptions and whether an element rendered. Software WebGL is deliberate: --disable-gpu made every Three.js page report a false "no WebGL context".

check_page eval

Runs JavaScript in the page and returns the value. The capability whose absence cost a whole run — the model made 26 bash calls hunting for a browser driver because it could not read runtime state.

The guidebook

The core's book of mechanical self-fixes, consulted when a tool call fails: a busy port becomes the next port, an invalid regex becomes a literal search. The registry repairs the arguments and retries, bounded at eight, prefixing the result with [auto-fixed] naming what changed. Real errors — missing files, failed matches, guard denials — fall through untouched.

The rules live in code, not in the prompt. Prompt advice is a suggestion a small model may ignore; a guidebook entry always runs. New rules must be mechanical (no judgment call), loss-free (adjust the how, never the what) and always disclosed.

Everything else

The agent loopThe circuit breaker, churn detection, retry taxonomy and resume briefings. Brain CoresSwappable runtimes, the measured trade between them, and what a swap costs. RFXDeclarative capability: recipes, capability cards, fuzz contracts, the chat dock. Phone accessKeystore identity, the auth gate, the doorbell and the loopback bridge.

PreviousCLI NextThe agent loop