System Architecture

A bird's-eye view of how the Ghost Agent runtime fits together.

Top-level diagram

Figure 1 — Ghost Agent runtime topology. Panels group subsystems; coloured card borders trace the ownership family.

Process & thread model

The Ghost Agent process is a single FastAPI / uvicorn instance running on port 8000. All work happens inside one Python interpreter; concurrency comes from asyncio for I/O and threads for blocking operations:

Subsystem	Concurrency	Notes
FastAPI request handlers	asyncio	Streaming responses use Server-Sent Events.
LLM calls (foreground & pools)	asyncio + httpx.AsyncClient	Per-pool round-robin with circuit breakers.
Memory writes	thread-locked, atomic temp-file replace	Each store guards itself with `threading.RLock`.
Memory bus fan-out	asyncio.gather + asyncio.to_thread	Per-tier writes run in parallel.
Docker sandbox	blocking docker SDK in worker thread	Container reused across calls; `execute()` wraps in `timeout`.
Biological watchdog	asyncio daemon task	Idle dream + skill graduation; cancelled at shutdown.
APScheduler	internal AsyncIO scheduler	Cron / interval triggers for user-defined tasks.

Data flow on a chat request

Detailed walkthrough lives in Request lifecycle. The short version:

Client posts /api/chat with OpenAI-format messages and X-Ghost-Key.
routes.py validates the key, picks streaming vs JSON, and hands the payload to GhostAgent.handle_chat.
MemoryBus.hydrate_context fans out to vector / graph / skill / episodic stores and fuses results with Reciprocal Rank Fusion.
The combined system prompt + history + hydration is forwarded to the upstream LLM via LLMClient.chat_completion.
The agent streams chunks back, parses any <tool_call> XML, executes the tool inside the Docker sandbox, and re-injects results.
Verifier / uncertainty modules optionally adjudicate before the final SSE chunk reaches the client.

Repository layout

Agent/
├── src/ghost_agent/
│   ├── main.py             CLI + FastAPI lifespan
│   ├── api/                routes.py, projects_routes.py, app.py
│   ├── core/               agent, llm, planning, dream, mcts, hypothesis,
│   │                       verifier, prompts, bus, context_manager, …
│   ├── memory/             vector, graph, profile, skills, journal,
│   │                       scratchpad, episodes, frontier, projects,
│   │                       adaptive_threshold, contradiction_log
│   ├── tools/              registry + 16 tool modules + qwen_bridge
│   ├── sandbox/docker.py
│   └── utils/              helpers, logging, sanitizer, token_counter
├── interface/
│   ├── server.py           Web UI proxy (port 8080)
│   ├── slack_project_commands.py
│   └── externals/
│       ├── slack_bot/
│       ├── tts_stt/
│       ├── image_generation/
│       └── clockwork_ghost/
└── Documentation/          (this set)