Architecture

Crate Map

The workspace layout. core depends on nothing; agent ties llm, tools, memory and persistence together; server and tui are the two outer shells.

fathom/
├── crates/
│   ├── core/          # fundamental types & domain logic
│   ├── llm/           # LLM provider abstraction
│   ├── agent/         # agent runtime, coordination, control plane
│   ├── tools/         # 48 base tools plus up to 5 CDP browser tools and up to 6 computer tools + MCP/LSP tools
│   ├── memory/        # long-term semantic memory + entity graph
│   ├── mcp/           # Model Context Protocol (client and server)
│   ├── persistence/   # storage (SQLite, PostgreSQL, connection pool, jobs, vault)
│   ├── server/        # Axum HTTP/SSE API, AG-UI bridge, computer relay
│   ├── tui/           # ratatui terminal interface
│   ├── lsp/           # Language Server Protocol integration
│   ├── governance/    # policy engine & audit trail
│   ├── supervisor/    # Docker container supervisor
│   └── desktop/       # GPUI native desktop integration
├── Bot/               # Fathom Bot — local-first React 19 + Electron chat client & Node harness
└── src/main.rs        # CLI entry point

core  ←──  llm  ←──  agent  ←──  server
↑          ↑          ↑           ↑
└── tools ─┴── mcp ───┴── tui ────┘
     ↑          └── persistence ──┘
     └── memory ──┘  (depends on core + llm)

Agent Lifecycle

Every agent — top-level or spawned — runs the same eight-step loop. The loop is where caching, safety gates and budget discipline live.

Coordinator Flow & Goal Mode

A research run is the same loop one level up: the Coordinator plans, fans out, collects under budgets, lets an LLM judge check the result against the goal, then synthesizes and ships.

Multi-Process

By default all agents run in one process as tokio tasks. The hidden fathom worker … mode is reserved for coordinator-managed process isolation and is not a user-facing command.

Coordinator (process 1)
  │  Unix socket IPC (JSON lines)
  ├──spawn──► Worker (process 2)  ── agent_id_1
  ├──spawn──► Worker (process 3)  ── agent_id_2
  └──spawn──► Worker (process 4)  ── agent_id_3

events: progress · tool-call · completion

• kill_on_drop — worker handles are spawned with kill_on_drop(true): a dropped handle terminates the child, so no orphaned processes survive a cancelled run.
• 30 s startup timeout — a worker must open its socket within 30 seconds or it is reaped and reported.
• SQLite WAL mode — concurrent access from every process against one database, pool of 4 connections.
• Isolation — one agent crashing never takes down the fleet; resource limits apply per process.

Context Management

Five stages keep the context window honest. Compaction triggers when estimated_tokens ≥ context_window × compact_threshold (default 0.50). Long-term memory complements all of it: relevant facts arrive as a prompt digest instead of living in session context.

Error Handling

Failure modes are designed for, not patched onto the happy path:

Task Tree Ledger

A shared, durable, append-only JSONL journal for the whole task tree rooted at one session. The coordinator and every sub-agent read from and write to the same file. It serves two roles: (1) coordination records that keep a shared picture of swarm decisions, and (2) typed child-to-parent beacons (“letters home”) that carry high-signal, attention-worthy signals.

Ledger path: ~/.fathom/ledger/task_tree/<session_id>.jsonl. Text capped at 4,000 chars per row. Total file capped at 2 MiB. ⚡ = wakes parent immediately (attention kinds).

Self-Improvement Backlog

A durable Markdown ledger where agents record candidate improvements. Re-triggering the same issue bumps a recurrence count instead of creating a duplicate. An optional LLM pass performs semantic dedup so reformulated ideas fold into existing entries.

File path: ~/.fathom/ledger/improvement-backlog.md. Grooming cap: 30 items. Semantic dedup candidate cap: 20 items. Digest format: - [high] (x3 | verify_email) Fix MX fallback.

Verification Receipt Ledger

An append-only JSONL ledger of typed verification receipts. Each receipt is keyed by (kind, value) so a PASS on one kind can never silence a FAIL on a different kind. The latest receipt per typed key wins.

Verdict: PossiblyLaundered flags shell-piped checks (e.g. | tail) where exit codes may be masked. File path: ~/.fathom/ledger/verify_receipts.jsonl. The autosave module gates Verification::Verified on SMTP PASS, Partial on syntax+MX PASS.

Data Flow Diagram

This diagram shows how data moves through the system during a typical research run, from the initial user query to the final synthesized output.

User Query
  │
  ▼
┌─────────────┐
│ Coordinator  │  Plans sub-tasks, assigns roles, selects models
└──────┬──────┘
     │  Fan-out (JoinSet of tokio tasks or OS processes)
     ▼
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ Researcher│ │ Researcher│ │ Analyst  │ │ Verifier │
└────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘
   │            │            │            │
   ▼            ▼            ▼            ▼
┌─────────────────────────────────────────────────┐
│                  Tool Layer                      │
│  web_search · web_fetch · exec · memory_search  │
│  extract_contacts · verify_email · code_symbols │
└────────────────────────┬────────────────────────┘
                       │  Raw results (truncated)
                       ▼
┌─────────────────────────────────────────────────┐
│              Findings Budget                     │
│  Each sub-agent summarizes within its budget     │
│  (context_window × 0.1 per agent)                │
└────────────────────────┬────────────────────────┘
                       │  Budget-capped summaries
                       ▼
┌─────────────┐
│ Coordinator  │  Collects, runs Goal Mode judge
└──────┬──────┘
     │  Gap-filling rounds (replan_rounds)
     ▼
┌─────────────┐
│  Synthesis   │  LLM merges findings into report
└──────┬──────┘
     │
     ▼
┌──────────────────────────────────────────────────┐
│                   Output                          │
│  index.md · summary.md · findings/ · sources.md  │
│  + PDF / HTML / JSON / DOCX export               │
│  + Memory absorb (long-term)                     │
│  + Notifications (webhook / email / Telegram)     │
└──────────────────────────────────────────────────┘

Security Architecture

Fathom has 12 security layers that run at different points in the agent lifecycle. These are not optional features — they are always active and cannot be disabled.

All 12 security layers

SSRF guard

The SSRF guard intercepts every HTTP request before it leaves the process. It resolves the target hostname and checks the resulting IP against a blocklist: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 127.0.0.0/8, 169.254.0.0/16, ::1, fc00::/7. DNS rebinding is mitigated by resolving before connecting and verifying the resolved address before the TCP handshake completes.

Prompt injection defense

Twelve patterns detect prompt injection attempts in tool outputs and user inputs:

1.  "ignore previous instructions"
2.  "you are now a ..."
3.  "system: " or "[system]" prefix injection
4.  Base64-encoded instruction blocks
5.  "disregard all prior"
6.  Invisible Unicode direction overrides (BiDi)
7.  Markdown link injection with javascript: URIs
8.  Nested tool_call JSON in tool outputs
9.  "IMPORTANT:" overrides in scraped page content
10. Repeated newlines followed by instruction blocks
11. XML/CDATA wrapping to break output parsing
12. Unicode homoglyph substitution in keywords

When a pattern is detected, the output is sanitized and a warning is logged. The agent receives a cleaned version of the content.

Secret scanning

Every tool output passes through a secret scanner before entering the context window. Eight types are detected and redacted with a [REDACTED:type] marker:

Destructive command blocking

The exec tool has a pre-execution guard that blocks 8 categories of destructive commands:

1.  rm -rf /          — recursive root deletion
2.  mkfs / dd if=     — filesystem destruction
3.  :(){ :|:& };:    — fork bombs
4.  chmod -R 777 /    — permission escalation
5.  wget | sh / curl | sh — remote code execution
6.  > /dev/sda        — raw disk writes
7.  shutdown / reboot / halt — system control
8.  iptables -F       — firewall flush

Protected surfaces

These files and directories are read-only to agents — they can be read but never written or deleted by any tool call:

~/.fathom/config.toml      # main configuration
~/.fathom/memory.db        # long-term memory database
~/.fathom/profiles/        # profile definitions
/.research.db             # session database
/index.md                 # generated index

Context Window Management

The context window is the most constrained resource in any agent system. Fathom manages it through five stages, each progressively more aggressive. The goal: keep the agent productive without losing critical information.

The five stages in detail

Configuration

Window profiles

Two profiles are available depending on the model’s context window size:

Long-term memory complements all of it: relevant facts arrive as a prompt digest instead of living in session context. This means the agent can “remember” thousands of facts without consuming context window space.

Multi-Process Architecture

By default all agents run as tokio tasks within a single process. With use_multiprocess = true in config.toml, each sub-agent becomes its own OS process with full isolation.

How use_multiprocess works

Unix socket IPC protocol

→ Coordinator → Worker:   {"type":"start","task":"...","tools":[...]}
← Worker → Coordinator:   {"type":"progress","agent_id":"...","msg":"searching..."}
← Worker → Coordinator:   {"type":"tool_call","tool":"web_search","args":{...},"ms":342}
← Worker → Coordinator:   {"type":"completion","agent_id":"...","result":"..."}
← Worker → Coordinator:   {"type":"error","agent_id":"...","error":"timeout"}

kill_on_drop safety

Worker handles are wrapped in tokio::process::Command::kill_on_drop(true). This means:

• If the coordinator process crashes, all workers are killed automatically by the OS.
• If a worker handle is dropped (cancelled task), the child process is terminated immediately.
• No orphaned worker processes can survive a cancelled run or a panic.
• A 30-second startup timeout ensures dead workers are reaped quickly.

When to use multi-process vs single-process