Skip to main content
Spacebot includes a built-in task management system for tracking work, priorities, and subtasks. Tasks are stored in SQLite and accessible via LLM tools.

​
Why Tasks?

Memories are for knowledge. Tasks are for work:
  • Backlog management: Track planned features, bugs, and research
  • Worker coordination: Assign tasks to workers, track progress
  • Context continuity: Remember what you’re working on across sessions
  • Structured workflow: Prioritize, organize, and check off subtasks

​
Task Structure

​
task_number
integer
Auto-incrementing ID unique to the agent
​
title
string
Short description (e.g., “Fix authentication bug”)
​
description
string
Detailed notes, context, or acceptance criteria
​
status
string
One of: backlog, todo, in_progress, done, cancelled
​
priority
string
One of: low, medium, high, urgent
​
subtasks
array
Checklist items with {title: string, completed: bool}
​
metadata
object
Arbitrary JSON for custom fields
​
source_memory_id
string
Optional link to the memory that created this task
​
created_by
string
Process ID that created the task (e.g., channel:discord:123, branch:abc-def)

​
Creating Tasks

Branches and channels can create tasks via the task_create tool: 
{
  "title": "Add rate limiting to API",
  "priority": "high"
}
The tool returns the task number: 
{
  "success": true,
  "task_number": 42,
  "status": "backlog",
  "message": "Created task #42: Add rate limiting to API"
}

​
Listing Tasks

Query tasks with filters: 
{}
Returns task summaries: 
{
  "success": true,
  "tasks": [
    {
      "task_number": 42,
      "title": "Add rate limiting to API",
      "status": "in_progress",
      "priority": "high",
      "subtasks_completed": 2,
      "subtasks_total": 5,
      "created_at": "2026-02-28T10:00:00Z",
      "updated_at": "2026-02-28T14:30:00Z"
    }
  ],
  "count": 1
}

​
Updating Tasks

Workers and branches can update task status, priority, and subtasks: 
{
  "task_number": 42,
  "status": "done"
}

​
Worker Assignment Pattern

You can assign tasks to workers by storing the worker ID in metadata:
1

Create Task

{
  "title": "Fix authentication bug",
  "status": "in_progress",
  "metadata": {"assigned_worker": "worker-abc-123"}
}
2

Worker Updates Progress

The worker calls task_update as it works:
{
  "task_number": 42,
  "subtask_updates": [
    {"title": "Reproduce issue", "completed": true}
  ]
}
3

Mark Complete

{
  "task_number": 42,
  "status": "done"
}
Workers have access to task_update in their tool set. You can scope it to only allow updating tasks assigned to that worker.

​
Status Workflow

Tasks flow through these states:
Initial state. Tasks waiting to be prioritized.
Ready to work on. Prioritized and clarified.
Actively being worked on. Typically only a few tasks should be in this state at once.
Completed. Stays in the database for reference.
Abandoned or deprioritized. No longer relevant.

​
Storage

Tasks live in the tasks table: 
CREATE TABLE tasks (
    id TEXT PRIMARY KEY,
    agent_id TEXT NOT NULL,
    task_number INTEGER NOT NULL,
    title TEXT NOT NULL,
    description TEXT,
    status TEXT NOT NULL,
    priority TEXT NOT NULL,
    subtasks TEXT NOT NULL,  -- JSON array
    metadata TEXT NOT NULL,  -- JSON object
    source_memory_id TEXT,
    created_by TEXT NOT NULL,
    created_at TEXT NOT NULL,
    updated_at TEXT NOT NULL,
    UNIQUE(agent_id, task_number)
);
Task numbers auto-increment per agent. Each agent has its own task sequence starting from 1.

​
API Access

You can also manage tasks via the HTTP API: 
curl -X POST http://localhost:3000/api/agents/spacebot/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Add rate limiting",
    "priority": "high"
  }'

​
Integration with Memory

Tasks can link to memories:
  1. Memory → Task: When a branch identifies work to do, it can save a memory and create a task, linking them via source_memory_id.
  2. Task → Memory: When a task is completed, the worker can save a decision memory summarizing what was done, referencing the task number in metadata.
This creates a bidirectional trail between knowledge and execution.

​
Best Practices

Use Subtasks

Break complex tasks into checkable steps. Helps workers report progress and the LLM understand what’s left.

Metadata for Context

Store component names, issue IDs, user reports, or other structured data in metadata for rich filtering.

Status Discipline

Keep in_progress limited. If a task stalls, move it back to todo or backlog.

Priority Hygiene

Only mark truly time-sensitive work as urgent. Use high for important but not blocking.
Don’t use tasks for knowledge. If it’s a fact, preference, or decision, use a memory. Tasks are ephemeral work items. Memories are long-term knowledge.

Build docs developers (and LLMs) love

Get started for freeTalk to us