Архитектура

Карта крейтов

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)

Жизненный цикл агента

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

Поток координатора и 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.

Мультипроцессность

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.

Управление контекстом

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.

Обработка ошибок

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

Журнал дерева задач

Общий долговременный append-only JSONL-журнал для всего дерева задач сессии. Координатор и субагенты синхронизируются через единый журнал: (1) координационные записи для единой картины решений роя, (2) типизированные маяки от дочерних агентов родительскому ("письма домой"), передающие ключевые сигналы, требующие приоритетного внимания.

Путь журнала: ~/.fathom/ledger/task_tree/<session_id>.jsonl. Текст ограничен 4 000 символов на строку. Файл ограничен 2 МиБ. ⚡ = будит родителя немедленно (внимание-типы).

Бэклог самоулучшения

Durable Markdown-журнал, где агенты записывают кандидатов на улучшение. Повторное срабатывание увеличивает счётчик рецидивов вместо создания дубликата. Опциональный LLM-проход выполняет семантическую дедупликацию.

Путь: ~/.fathom/ledger/improvement-backlog.md. Лимит: 30 записей. Лимит кандидатов для семантического дедупа: 20. Формат дайджеста: - [high] (x3 | verify_email) Fix MX fallback.

Журнал чеков верификации

Append-only JSONL-журнал типизированных чеков верификации. Каждый чек ключуется по (тип, значение) — PASS по одному типу никогда не заглушит FAIL по другому. Последний чек по ключу побеждает.

Вердикт: PossiblyLaundered помечает shell-пайп проверки (напр. | tail), где коды возврата могут быть замаскированы. Путь: ~/.fathom/ledger/verify_receipts.jsonl. Автосейв ставит Verification::Verified при SMTP PASS, Partial при 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