Task Scheduler

The task scheduler runs background jobs on cron-based schedules. It handles periodic maintenance like memory consolidation and conversation cleanup, and supports custom task definitions.

Configuration

The scheduler is configured in config.toml under the [scheduler] section.

config.toml toml

[scheduler]
enabled = true
check_interval_secs = 60

[[scheduler.tasks]]
name = "memory-consolidation"
cron_expression = "0 0 3 * * *"    # Daily at 3 AM
handler_type = "memory_consolidation"
enabled = true

[[scheduler.tasks]]
name = "conversation-cleanup"
cron_expression = "0 0 4 * * 0"    # Weekly on Sunday at 4 AM
handler_type = "conversation_cleanup"
config_json = '{"max_age_days": 30}'
enabled = true

Field	Default	Description
`enabled`	`true`	Whether the scheduler is active
`check_interval_secs`	`60`	How often (in seconds) the scheduler checks for due tasks
`tasks`	`[]`	Pre-configured scheduled tasks

Task Definition

Each scheduled task is defined by the following fields:

Field	Type	Required	Description
`name`	string	Yes	Unique task identifier
`cron_expression`	string	Yes	6-field cron expression (sec min hour day month weekday)
`handler_type`	string	Yes	Handler to execute (see built-in handlers below)
`config_json`	string	No	JSON configuration passed to the handler
`enabled`	bool	No	Whether the task is active. Defaults to `true`

Cron Expression Format

The scheduler uses 6-field cron expressions:

Format text

┌──────── second (0-59)
│ ┌────── minute (0-59)
│ │ ┌──── hour (0-23)
│ │ │ ┌── day of month (1-31)
│ │ │ │ ┌ month (1-12)
│ │ │ │ │ ┌ day of week (0-6, 0=Sunday)
│ │ │ │ │ │
* * * * * *

Built-in Handlers

Handler Type	Purpose	Config
`memory_consolidation`	Merges related memories, updates confidence levels, prunes low-value entries	None
`conversation_cleanup`	Removes old conversation data past the retention period	`max_age_days` (number)

Execution Logging

Every task execution is recorded with timing and status information:

Field	Type	Description
`task_id`	string	Reference to the scheduled task
`started_at`	i64	Unix timestamp when execution began
`completed_at`	i64	Unix timestamp when execution finished
`success`	bool	Whether the execution completed without error
`error`	string?	Error message if the execution failed

Execution history is stored in ~/.local/share/ultrasushitron/scheduler.db.

Admin Controls

The mobile app's Tasks tab and the Admin API provide:

List tasks — view all scheduled tasks with cron expression, next run time, and enabled state
Toggle tasks — enable or disable individual tasks at runtime
Trigger immediate — execute a task now regardless of its cron schedule
View history — browse execution logs with success/failure status and timing