Overview

Relevant source files

• AGENTS.md
• Cargo.lock
• Cargo.toml
• README.md
• docs/content/docs/(configuration)/config.mdx/config.mdx)
• src/identity/files.rs

This page introduces Spacebot as a system: what problem it solves, what the repository contains, and how the major subsystems relate to each other. For precise descriptions of individual subsystems, follow the links to the relevant child pages throughout this document. For architectural diagrams showing how all components wire together at runtime, see Architecture Overview. For terminology definitions, see Core Concepts and Terminology.

---

Purpose

Standard LLM agent frameworks run everything in one session. A single thread handles conversation, reasoning, tool execution, memory retrieval, and context management sequentially. This means the agent is unavailable while it works, and any one slow step stalls the entire interaction.

Spacebot replaces this monolith with five specialized process types that run concurrently and communicate via events. Each type does exactly one job; anything outside that job is delegated. The result is a system where a user-facing conversation is never blocked by background work, background work is never interrupted by user messages, and memory management happens without any process being aware of it.

The repository is a single Rust binary (spacebot, defined in Cargo.toml1-6) with no external server dependencies. All persistent state lives in embedded databases in a local data directory.

---

Repository Structure

The codebase is organized as a single Cargo package. The top-level source tree maps cleanly onto the major subsystems:

src/
├── main.rs             — CLI entry, daemon mode, startup sequencing
├── config.rs           — config.toml parsing and hot-reload
├── llm/                — LlmManager, SpacebotModel, provider routing
├── agent/              — Channel, Branch, Worker, Compactor, Cortex
├── hooks/              — SpacebotHook, CortexHook (Rig PromptHook impls)
├── tools/              — all tool implementations
├── memory/             — MemoryStore, embeddings, hybrid search
├── messaging/          — platform adapters, MessagingManager
├── conversation/       — history persistence, context assembly
├── cron/               — scheduler, CronStore
├── identity/           — SOUL.md, IDENTITY.md, USER.md loading
├── secrets/            — AES-256-GCM credential store
├── settings/           — key-value runtime settings
└── db/                 — SQLite connection setup, migrations

Sources: AGENTS.md128-207

---

The Five Process Types

Every LLM process in Spacebot is a Rig Agent<SpacebotModel, SpacebotHook>. The five process types differ in system prompt, tool set, history access, and lifecycle:

Spacebot process topology

Sources: README.md263-365 AGENTS.md38-103

Process	Source File	Role	Blocks channel?
Channel	src/agent/channel.rs	User-facing conversation, delegates everything	Never
Branch	src/agent/branch.rs	Forked thinking context, returns a conclusion	No
Worker	src/agent/worker.rs	Executes tasks (shell, file, browser, etc.)	No
Compactor	src/agent/compactor.rs	Programmatic context monitor, triggers compaction workers	No
Cortex	src/agent/cortex.rs	System-level observer, generates memory bulletin	No

Sources: AGENTS.md38-103 README.md263-365

---

Three Embedded Databases

Spacebot uses three embedded databases — no external server processes required.

Database layer and module mapping

Sources: AGENTS.md213-223 Cargo.toml26-29

---

Messaging Platforms

Inbound messages from all platforms are merged into a single stream by MessagingManager (in src/messaging/manager.rs) and routed to the appropriate Channel instance via Binding rules.

Supported platforms and their adapters:

Platform	Adapter File	Notes
Discord	src/messaging/discord.rs	Gateway via serenity
Slack	src/messaging/slack.rs	Socket Mode via slack-morphism
Telegram	src/messaging/telegram.rs	Long-poll via teloxide
Twitch	src/messaging/twitch.rs	IRC via twitch-irc, trigger prefix
Email	src/messaging/email.rs	IMAP poll + SMTP send
Webhook	src/messaging/webhook.rs	HTTP POST/GET for programmatic use
Webchat	src/messaging/webchat.rs	Embeddable portal chat with SSE

Each adapter implements the Messaging trait (src/messaging/traits.rs). Bindings ([[bindings]] in config.toml) map platform/guild/channel identifiers to specific agent IDs. See Messaging Platforms and Bindings for full detail.

Sources: README.md93-104 Cargo.toml95-116

---

Memory System

Memory is not flat text files or unstructured vector blobs. Every memory is a typed, scored, graph-connected object stored as a SQLite row with a paired LanceDB embedding.

Memory system data flow

Eight memory types exist: Fact, Preference, Decision, Identity, Event, Observation, Goal, Todo. Graph edges (RelatedTo, Updates, Contradicts, CausedBy, PartOf) link related memories. Recall uses vector similarity + full-text search combined via Reciprocal Rank Fusion. See Memory System for detail.

Sources: README.md365-374 AGENTS.md226-238

---

Model Routing

Every LLM call goes through LlmManager (src/llm/manager.rs) via SpacebotModel (src/llm/model.rs). The routing system selects a model based on four levels of priority:

1. Process-type defaults — channel, branch, worker, compactor, cortex keys in [defaults.routing]
2. Task-type overrides — e.g., coding = "anthropic/claude-sonnet-4" in [defaults.routing.task_overrides]
3. Prompt complexity scoring — lightweight keyword classifier downgrades simple requests to cheaper models
4. Fallback chains — when a model returns 429 or 502, LlmManager tries the next model in the chain

Supported providers include Anthropic, OpenAI, OpenRouter, Kilo Gateway, Groq, Together, Fireworks, DeepSeek, xAI, Mistral, NVIDIA, MiniMax, Moonshot AI, Zhipu (GLM), OpenCode Zen/Go, and any OpenAI-compatible or Anthropic-compatible endpoint via custom provider config. See LLM Integration for detail.

Sources: README.md131-198 docs/content/docs/(configuration)/config.mdx68-83

---

LLM Framework Integration

Spacebot uses Rig (v0.30.0) as its agentic loop framework. Every LLM process is a rig::Agent<SpacebotModel, SpacebotHook>. Key integration points:

• SpacebotModel — custom CompletionModel implementation that routes calls through LlmManager instead of using Rig's built-in provider clients.
• SpacebotHook — PromptHook implementation attached to channels, branches, and workers. It sends ProcessEvents for status updates, usage tracking, and cancellation signals. Returns Continue, Terminate, or Skip.
• CortexHook — PromptHook implementation specific to the Cortex process.
• ToolServer — each process type gets its own ToolServer with a different set of registered tools. Tool assignments are configured in factory functions in src/tools.rs.
• History — conversation history is external to the agent and passed in on each call via .with_history(&mut history). Branching is a Vec<Message> clone.

Sources: AGENTS.md244-288

---

Identity and Persona

Each agent has three plain-text identity files in its workspace directory, loaded by Identity::load() in src/identity/files.rs17-23:

File	Purpose
SOUL.md	Personality, values, communication style
IDENTITY.md	Name and nature
USER.md	Information about the human this agent interacts with

These are injected into system prompts via Identity::render() (src/identity/files.rs27-52). They are not graph memories — they live on disk and are hot-reloaded when changed.

Sources: src/identity/files.rs1-91

---

Skills System

Skills extend agent behavior via SKILL.md files installed from GitHub repositories or the skills.sh registry. Skills are injected into worker system prompts. They can be scoped to the instance (~/.spacebot/skills/) or to a specific agent workspace (workspace/skills/). See Skills System for full detail.

---

Configuration

All configuration lives in config.toml, read from ~/.spacebot/config.toml by default. The config covers:

• [llm] — provider API keys and custom provider definitions
• [defaults] — instance-wide defaults (routing, compaction thresholds, cortex timing, warmup, browser)
• [[agents]] — per-agent overrides, sandbox config, and cron jobs
• [messaging.*] — platform adapter credentials and named instances
• [[bindings]] — routing rules from platform messages to agents

Most settings are hot-reloaded at runtime via arc-swap without a restart. The complete reference is in Configuration Reference.

Sources: docs/content/docs/(configuration)/config.mdx1-260

---

HTTP API and Web Interface

Spacebot exposes an Axum-based HTTP API (src/api/) serving a React web interface bundled with the binary. The API covers agents, channels, memory, workers, tasks, cron, settings, providers, and bindings. See HTTP API Reference and Web Interface for detail.

---

Deployment

Spacebot ships as:

• Single binary — build with cargo build --release, run directly
• Docker image — slim and full variants; mount a volume for persistent data
• NixOS flake — services.spacebot module with systemd hardening
• spacebot.sh — hosted one-click deployment

The binary starts as a background daemon by default. The CLI subcommands start, stop, restart, and status manage the daemon process. See Getting Started and Deployment for detail.

Sources: README.md70-75 README.md400-468