Overview

Relevant source files

• interface/src/api/client.ts
• interface/src/components/ModelSelect.tsx
• interface/src/lib/providerIcons.tsx
• interface/src/routes/Settings.tsx
• src/agent/channel.rs
• src/api/agents.rs
• src/api/models.rs
• src/api/providers.rs
• src/api/server.rs
• src/api/state.rs
• src/config.rs
• src/lib.rs
• src/llm/manager.rs
• src/llm/model.rs
• src/llm/providers.rs
• src/llm/routing.rs
• src/main.rs
• src/messaging/discord.rs
• src/messaging/slack.rs
• src/messaging/telegram.rs
• src/messaging/twitch.rs
• src/messaging/webhook.rs
• src/openai_auth.rs
• src/tools/reply.rs

Spacebot is a multi-platform conversational AI agent system implemented in Rust. It provides a complete framework for building AI agents that can interact with users across messaging platforms (Discord, Slack, Telegram, Twitch, Email), execute tasks with shell/file/browser access, maintain long-term memory, and supervise their own operation.

The system is designed around a process model where each major activity (conversation management, reasoning, task execution, system observation) runs in a dedicated process with role-specific tool access. This architecture enables fine-grained supervision, resource isolation, and parallel execution of complex workflows.

Scope: This page provides a high-level introduction to Spacebot's architecture, process types, and major subsystems. For detailed information about specific components:

• Process lifecycle and event flow: see Process Lifecycle and Event Flow
• LLM provider configuration and routing: see LLM Integration
• Memory system internals: see Memory System
• Messaging platform integration: see Messaging Platforms

---

System Architecture

The following diagram maps Spacebot's major subsystems to their implementation in the codebase:

Sources: src/main.rs331-421 src/lib.rs380-404 src/api/server.rs31-329 src/api/state.rs48-141 src/agent/channel.rs478-595 src/llm/manager.rs33-60 src/messaging/manager.rs1-50

Key Subsystems

Subsystem	Purpose	Primary Implementation
Entry Point	CLI parsing, daemon lifecycle, onboarding	src/main.rs
HTTP API	REST endpoints, SSE event stream, web dashboard backend	src/api/server.rs src/api/state.rs
Agent Runtime	Hot-reloadable configuration, event bus, dependency injection	src/config/runtime.rs src/lib.rs380-404
Process Types	Channel, Branch, Worker, Cortex (see below)	src/agent/
Intelligence Layer	LLM provider routing, memory search, prompt assembly	src/llm/ src/memory/ src/prompts/
Tool System	Process-specific tool servers, 40+ built-in tools	src/tools/
Messaging Adapters	Platform normalization (Discord, Slack, Telegram, etc.)	src/messaging/
Persistence	SQLite (structured), LanceDB (vectors), REDB (secrets)	Database initialization in src/db.rs

Sources: src/main.rs1-1400 src/lib.rs1-404 src/api/server.rs1-472 src/config/runtime.rs1-350

---

Process Model

Spacebot implements a hierarchical process model with four distinct process types. Each type runs in its own tokio task with isolated tool access and specific responsibilities.

Sources: src/lib.rs80-101 src/lib.rs63-78 src/agent/channel.rs394-456 src/agent/branch.rs1-50 src/agent/worker.rs1-100 src/agent/cortex.rs1-100

Process Type Responsibilities

Channel (ProcessType::Channel)

• Role: Top-level conversation manager
• Lifecycle: Long-lived (one per conversation)
• Tools: Dynamic per-turn (reply, branch, spawn_worker, route, cancel, skip, react)
• Capabilities: Routes messages, coordinates branches/workers, sends replies
• Restrictions: No memory/file/shell access (delegates to branches/workers)
• Implementation: src/agent/channel.rs394-456

Branch (ProcessType::Branch)

• Role: Isolated reasoning fork for memory/task operations
• Lifecycle: Short-lived (spawned per reasoning need, auto-terminates)
• Tools: memory_save, memory_recall, memory_delete, task_create, task_list, task_update
• Capabilities: Can search memory, create tasks, spawn workers
• Restrictions: No shell/file/browser access
• Implementation: src/agent/branch.rs

Worker (ProcessType::Worker)

• Role: Task executor with privileged access
• Lifecycle: Variable (task completion or interactive session)
• Tools: shell, file_read, file_write, file_edit, browser, set_status, task_update (scoped)
• Capabilities: Execute shell commands, manipulate files, browse web
• Restrictions: No memory persistence tools (uses branch for that)
• Implementation: src/agent/worker.rs

Cortex (ProcessType::Cortex)

• Role: System-level observer and maintainer
• Lifecycle: Long-lived singleton per agent
• Tools: memory_save (consolidation only)
• Capabilities: Memory decay/pruning/merging, health supervision, bulletin generation
• Restrictions: Read-only observation of other processes
• Implementation: src/agent/cortex.rs

Sources: src/lib.rs80-101 src/agent/channel.rs1-2100 src/agent/branch.rs1-800 src/agent/worker.rs1-1500 src/agent/cortex.rs1-1000

---

Message Flow

The following diagram shows how messages flow through Spacebot from external platforms to the agent runtime and back:

Sources: src/messaging/discord.rs1-100 src/messaging/slack.rs1-150 src/main.rs310-329 src/agent/channel.rs940-1500 src/llm/model.rs245-490 src/tools/reply.rs1-240

Message Normalization

All messaging adapters implement the Messaging trait (src/messaging/traits.rs1-50) which requires:

1. start(): Launch platform connection, return InboundStream
2. respond(): Send OutboundResponse to platform
3. send_status(): Update typing indicator or similar

Each adapter normalizes platform events into InboundMessage:

Sources: src/lib.rs426-470 src/messaging/traits.rs1-100 src/messaging/discord.rs100-200 src/messaging/slack.rs150-250

Response Routing

Outbound responses are paired with the originating InboundMessage via RoutedResponse (src/lib.rs472-478):

The target.metadata map contains platform-specific fields (e.g., discord_channel_id, slack_thread_ts) that adapters use to route replies to the correct thread/channel.

Sources: src/lib.rs472-478 src/main.rs310-329 src/messaging/discord.rs140-300 src/messaging/slack.rs500-700

---

Core Subsystems

LLM Provider System

Spacebot supports multiple LLM providers through a unified routing layer:

• LlmManager (src/llm/manager.rs33-250): Provider registry, HTTP client, OAuth credential management
• SpacebotModel (src/llm/model.rs42-56): Implements rig::completion::CompletionModel with retry + fallback logic
• RoutingConfig (src/llm/routing.rs10-60): Per-process-type model selection, task overrides, fallback chains

The system supports 20+ providers including Anthropic, OpenAI, OpenRouter, Google Gemini, DeepSeek, and local Ollama instances. Provider credentials are hot-reloadable via ArcSwap.

Sources: src/llm/manager.rs1-250 src/llm/model.rs1-550 src/llm/routing.rs1-150 src/config/providers.rs1-300

Memory System

A hybrid graph + vector memory system:

• MemorySearch (src/memory/search.rs): Combines vector similarity, graph traversal, keyword search
• MemoryStore (SQLite memories table): Typed memories (identity, fact, decision, event, etc.)
• EmbeddingTable (LanceDB): Fastembed-generated vectors for similarity search
• Association (SQLite associations table): Directed graph edges (RelatedTo, Updates, Contradicts, etc.)

Cortex maintains memory health through periodic decay, pruning, and merging operations.

Sources: src/memory/search.rs1-400 src/memory/store.rs1-500 src/agent/cortex.rs200-600

Tool System

Tools are registered per-process-type with isolated ToolServer instances:

• Channel tools: reply, branch, spawn_worker, route, cancel, skip, react, send_message, send_file
• Branch tools: memory_save, memory_recall, task_create, task_list, task_update, spacebot_docs
• Worker tools: shell, file_read, file_write, file_edit, file_list, browser, set_status, secret_set

Tools implement rig::tool::Tool and use JSON Schema for argument validation.

Sources: src/tools/reply.rs1-240 src/tools/spawn_worker.rs1-400 src/tools/memory_tools.rs1-300 src/tools/shell.rs1-200 src/agent/channel.rs538-540

Persistence Layer

Three database backends:

Database	Purpose	Schema	Access Pattern
SQLite	Conversations, process runs, tasks, cron jobs, memories	src/db.rs1-500	sqlx::SqlitePool via AgentDeps
LanceDB	Embedding vectors for memory search	src/memory/embedding.rs	Per-agent lancedb::Connection
REDB	Encrypted secret storage (AES-GCM + Argon2)	src/secrets/store.rs	Singleton SecretsStore

Sources: src/db.rs1-500 src/memory/embedding.rs1-300 src/secrets/store.rs1-800 src/conversation/logger.rs1-200

---

Configuration and Runtime

Spacebot configuration is managed through a layered system:

1. config.toml: Primary configuration file (src/config/toml_schema.rs1-500)
2. Environment variables: Override via env:VARIABLE_NAME syntax (src/config/load.rs1-400)
3. Secret references: Resolve via secret:SECRET_NAME syntax (src/config/load.rs14-20)
4. RuntimeConfig: Hot-reloadable wrapper using ArcSwap (src/config/runtime.rs1-350)

Configuration changes are detected by a file watcher (src/config/watcher.rs1-150) and propagate to running processes without restart.

Sources: src/config.rs1-900 src/config/load.rs1-600 src/config/runtime.rs1-350 src/config/watcher.rs1-150

---

Deployment Options

Spacebot supports three deployment modes:

Mode	Entry Point	Configuration	Use Case
Native	cargo run or Homebrew binary	~/.spacebot/config.toml	Development, local use
Docker	Dockerfile multi-stage build	/data/config.toml (volume mount)	Containerized deployment
Hosted	Fly.io or similar	Platform secrets + volume	Cloud hosting

The Docker image includes self-update capability (src/update/docker.rs1-300) where the container can pull a new image, create a replacement container, and atomically swap before terminating.

Sources: src/main.rs331-421 src/daemon.rs1-400 src/update/docker.rs1-300 Dockerfile1-100

---

Event System

All process lifecycle and tool execution events flow through a per-agent broadcast channel:

Events are:

• Broadcast via tokio::sync::broadcast::Sender<ProcessEvent> (src/lib.rs319-344)
• Consumed by channels for retrigger logic (src/agent/channel.rs946-1100)
• Consumed by Cortex for health supervision (src/agent/cortex.rs100-400)
• Forwarded to API layer for SSE streaming (src/api/state.rs52-53)

Sources: src/lib.rs148-311 src/lib.rs319-344 src/agent/channel.rs946-1100 src/agent/cortex.rs100-400 src/api/system.rs1-200