Spacebot Documentation

Spacebot is an agentic AI system designed to replace monolithic LLM sessions with specialized, delegated processes. Instead of a single large model handling everything, work is distributed across dedicated roles to improve reliability and focus.

Key abstractions include:

• Channels: Conversational agents that provide user-facing identity and personality.
• Branches: Non-blocking, forked thinking processes used for exploration.
• Workers: Specialized processes dedicated to specific tasks like research, code execution, or file operations.
• Cortex: The system-level layer responsible for observation and memory consolidation.
• Memory Graph: A structured system for storing memories with semantic associations, rather than relying on flat markdown files.

Spacebot is an opinionated agent harness designed for teams, communities, and companies. Unlike monolithic agent frameworks that run everything in a single LLM thread, Spacebot uses a specialized process-based architecture to handle concurrent multi-user conversations, shared memory, and true process-level concurrency.

Key characteristics:

• Structured State: State is stored in a typed SQLite memory graph rather than markdown files.
• Task-Driven Autonomy: Autonomy is managed via a task state machine linked to goals.
• Scalability: Designed to handle hundreds of simultaneous users in environments like Discord, Slack, or Telegram.
• Continuous Learning: The system captures reusable skills and synthesizes memories during idle periods.

Channel Attachment Persistence provides a mechanism for storing files and images sent within a channel (e.g., Discord, Slack, Telegram) on disk. This system ensures that attachments are not just transiently converted to base64 or inlined text for a single LLM turn, but are instead retained for long-term use.

Key capabilities include:

• Recall: Allows the channel to re-analyze files from previous conversation turns.
• Handoff: Enables delegating tasks involving files to workers by providing access to the actual file on disk.
• Persistence: Avoids reliance on expiring platform URLs (like Slack's url_private) by maintaining local copies.
• Identity: Provides stable identifiers linking history entries to on-disk files.

The Spacebot Control UI is a self-contained React web application located in the interface/ directory. It is served by the Spacebot Rust daemon via an embedded axum HTTP server.

Key architectural features include:

• UI System: It uses the Spacedrive UI component library and color system.
• Data Layer: It follows a spec-first approach using OpenAPI, with openapi-fetch and openapi-typescript for type-safe API interactions.
• State Management: Uses TanStack Query for data fetching and caching.
• Deployment: Frontend assets are baked into the single Rust binary using rust-embed from the interface/dist/ build output.

The project is built using Next.js and Fumadocs. Key files and routes include:

• lib/source.ts: Contains the code for the content source adapter. Use the loader() function to access your content.
• lib/layout.shared.tsx: Contains shared options for layouts.
• app/(home): Route group for the landing page and other primary pages.
• app/docs: The documentation layout and pages.
• app/api/search/route.ts: The Route Handler used for search functionality.

Spacebot can be deployed using three primary methods:

• spacebot.sh: One-click hosted deployment. Connect platforms and configure the agent via a web interface.
• Self-hosted: Run the single Rust binary. This requires no Docker, microservices, or server dependencies.
• Docker: Use a container image that includes all dependencies. Use a volume mount for persistent data storage.

The task system is distributed across several modules:

• tasks/store.rs (TaskStore): Handles core CRUD operations, status transitions, and the claim_next_ready logic.
• tools/: Provides LLM-accessible tools:
  • task_create: Used by branches and cortex chat to create tasks.
  • task_list: Used by branches and cortex chat to view tasks.
  • task_update: Used by branches and workers to modify tasks (scoped).
• api/tasks.rs: REST endpoints for list, get, create, update, delete, approve, and execute. These endpoints emit SSE (Server-Sent Events).
• agent/cortex.rs: Manages the execution loop via spawn_ready_task_loop, pickup_one_ready_task, and gather_active_tasks (integrated with the bulletin).

Supported

• Receive messages from channels and direct messages
• Send text replies (long messages are automatically split)
• Streaming replies with live edit-in-place updates and typing indicator
• Thread-aware replies (replies stay in the originating thread)
• File/image attachments (up to a configurable size limit)
• Emoji reactions
• Fetch channel history (for context window)
• Multiple named instances
• Per-team and per-channel allowlists
• DM allowlist (fail-closed: DMs are blocked unless the sender is explicitly listed)
• require_mention routing

Not supported

• Slash commands (use @-mentions instead)
• Ephemeral (private) messages
• Message threading via parent_id lookup (bot cannot independently look up thread context)
• User/channel autocomplete
• Presence or status events
• App marketplace / interactive components (buttons, modals)

Slash commands provide a power-user interface for session control, memory management, task execution, skill invocation, and agent state management. They are accessible across all supported platforms (Discord, Slack, Telegram, Portal, and text-based adapters) and are managed via a central registry to ensure consistency.

Commands are categorized into several functional areas:

• Session: Control the conversation lifecycle (e.g., /new, /retry, /stop).
• Memory: Interact with the agent's long-term memory (e.g., /memory, /remember).
• Tasks & Goals: Manage active objectives (e.g., /tasks, /goals, /approve).
• Skills: Invoke specific capabilities (e.g., /skills, /skill).
• Info: Retrieve system and conversation metadata (e.g., /help, /status, /usage).
• Config: Adjust conversation settings (e.g., /model, /voice).