<!-- Markdown mirror. Canonical: https://empryo.com/docs/concepts/architecture -->

# How it works

> How Empryo works: a live ranked code graph, an agent loop with parallel sub-agents, and embedded Neovim with layered LSP, AST, and tree-sitter intelligence.

Empryo is three things talking to each other:

1. **A live code graph** - every file, symbol, and import, ranked by importance. Updated as you work.
2. **An agent loop** - reads, edits, tests, commits. Can dispatch parallel sub-agents.
3. **Your Neovim** - embedded. The agent edits through the same editor you use.

## The agents

| Agent | Runs | Model |
|-------|------|-------|
| **Forge** | The one talking to you. Orchestrates everything. | Your active model |
| **⚡ Spark** | Read-only research (grep, read, analyze). | `taskRouter.spark` |
| **🔥 Ember** | Code edits and refactors. Own context window. | `taskRouter.ember` |
| **WebSearch** | Multi-step web research with citations. | `taskRouter.webSearch` |

Configure which model each one uses in [the task router](/docs/recipes/task-router).

The WebSearch agent is the fallback, not the only path. When your model's provider can
search server-side, the model searches itself in a single step and no sub-agent is spawned.
That is enabled only on measured lanes: Claude first-party, Claude and GPT through
the proxy, and OpenRouter's native-search generations. Everywhere else, gateways, local
models, unproven lanes, no key at all. The agent above runs and searches through
Empryo's own backends.

Citations vary by model, not by provider: Claude returns a full source list, while GPT names
its sources in prose and reports none structurally. See
[`nativeSearch`](/docs/reference/configuration) to turn provider-side search off.

## What the agents share

When Forge dispatches multiple sub-agents in parallel, they coordinate through a shared bus:

- **File cache** - first reader caches, others reuse.
- **Tool cache** - read-only tool results shared across agents and dispatches.
- **Edit lock** - concurrent writes to the same file are serialized.
- **Findings** - one agent's discovery reaches the others at their next step.

Result: N agents don't re-read the same files N times.

## Code intelligence, layered

Operations (go-to-definition, rename, diagnostics…) try the best backend first, fall back if it fails:

| Tier | Backend | Used for |
|------|---------|----------|
| 1 | LSP | precise types, workspace rename, diagnostics |
| 2 | ts-morph | TypeScript/JavaScript AST ops |
| 2 | tree-sitter | 37 languages - outlines, imports |
| 3 | regex | universal fallback |

LSP runs via Neovim when the editor is open, via standalone servers otherwise. The agent always has it.

## System prompt

Every turn, the prompt is assembled from: mode, project info, git context, the Genome, your memory, forbidden files, active skills. The Genome (built by the Genome engine) is personalized per-turn - files you just edited or referenced get boosted.

See [the Genome](/docs/concepts/genome) for ranking details, [memory](/docs/tools/memory) for cross-session knowledge, [compound tools](/docs/concepts/compound-tools) for the one-call tools, [code intelligence](/docs/concepts/intelligence) for the backend router.
