Skip to main content

​
Scheduler

Background job processing for digests, reminder notifications, and content processing. The scheduling system is fully dynamic, storing cron patterns and job configurations in the SQLite database rather than using static environment variables.

​
Overview

The scheduler uses BullMQ with Redis to run periodic jobs. It is disabled by default and opt-in via the ENABLE_SCHEDULER=true environment variable. When disabled, the app starts normally without requiring Redis, and you can still manage schedules in the database for later use.

​
Prerequisites

  • Redis instance running (default: redis://localhost:6379)
  • ENABLE_SCHEDULER=true in your environment

​
Configuration

Scheduling relies on the database and dynamic APIs. Only the enablement and connection variables are maintained in .env:
VariableDescriptionDefaultExample
ENABLE_SCHEDULEREnable background job processingfalsetrue
REDIS_URLRedis connection URLredis://localhost:6379redis://myhost:6379

​
Managing Schedules

You can create, update, and delete schedules dynamically without restarting the application. EchOS provides two ways to do this:
  1. Agent Tool: The manage_schedule tool allows the AI assistant to manage background jobs on your behalf.
  2. Web API: The @echos/web plugin exposes RESTful CRUD endpoints under /api/schedules (requires WEB_API_KEY).
Every schedule contains a JSON config field designed to pass custom arguments to its plugin’s job processor (e.g., custom prompts or categorization rules).

​
Jobs

​
Daily Digest (digest)

The Digest Plugin generates summaries of your latest notes, memories, and upcoming reminders.
  • Type: digest
  • Config options: prompt (varies the tone), lookbackDays (how far back to summarize), categories (filters notes by tags).
  • Default behavior: Creates a temporary AI agent and sends the summary via Notification Service.

​
Reminder Check (reminder-check)

Queries the SQLite database for pending reminders with a due date in the past. Due reminders are sorted by priority (high first) and sent as a notification. Note: The system internally schedules a quick check every minute to dispatch due reminders, distinct from customizable user schedules.

​
Content Processing (process_article, process_youtube)

Processes long-form article and YouTube URLs queued by the agent during conversations. This runs automatically when URLs are submitted; no manual schedule creation is needed.

​
Architecture

src/index.ts
    │
    ├── Database (SQLite `job_schedules` table)
    ├── NotificationService (from @echos/telegram or log-only fallback)
    │
    └── @echos/scheduler
         ├── Queue (BullMQ)
         ├── ScheduleManager (Syncs Database ↔ BullMQ)
         └── Worker
              └── Job Router (Plugin-aware routing)
                   ├── digest     → DigestPlugin Processor
                   ├── reminder   → Built-in Reminder Processor
                   └── content    → Built-in Content Processor
The ScheduleManager listens for changes made through the tools and Web API, applying them instantly to the running BullMQ scheduler.

​
Graceful Shutdown

On SIGINT/SIGTERM, the worker and queue are closed before interfaces and storage. In-progress jobs will complete before the worker shuts down.

​
Example Usage

With the scheduler running, you can ask the agent:
“Create a daily digest at 8am that looks back 3 days and focuses on ‘business’ and ‘music’ categories, using a professional tone.”
The agent will use manage_schedule (action: upsert) to build and inject the exact JSON configuration and cron expression 0 8 * * *.