Thalamus
Thalamus
Thalamus is the event routing and scheduling hub of QUI. Named after the brain structure that routes sensory signals to cortical areas, Thalamus routes triggers to their targets, manages scheduled tasks, and receives inbound messages from external platforms.
You don't interact with Thalamus directly — it works behind the scenes. But understanding what it does helps you design characters that respond to events, run on schedules, and receive messages from Telegram, Slack, and other channels.
What Thalamus Does
1. Trigger Routing
When a character has automated tasks configured in the Anima Sequencer, Thalamus handles the non-manual triggers:
| Trigger Type | How It Works |
|---|---|
| Timer | Runs on a cron schedule or interval. Thalamus fires at the configured time and routes to Anima to execute the task. |
| Webhook | Receives an HTTP POST from an external system and routes to Anima. |
| M2M | Receives a message from another character and routes to the target. |
| Manual | Handled directly by Anima (user clicks Run) — Thalamus not involved. |
Each trigger has a cooldown (default 60 seconds) to prevent rapid re-firing.
2. Scheduled Tasks
Thalamus manages all character schedules. When you set up a timer trigger in the Anima Sequencer — "run this task every 30 minutes" or "run at 2 AM daily" — Thalamus registers the schedule and fires it.
Common scheduling use cases:
- Daily memory consolidation (Cortex modes on a schedule)
- Periodic email polling (check inbox every 5 minutes)
- Scheduled reports (summarise activity every evening)
- Heartbeat monitoring (check service health every minute)
3. Channel Bridge (Inbound)
Thalamus receives inbound messages from external platforms and delivers them to Strings:
| Platform | How Messages Arrive |
|---|---|
| Telegram | Webhook — bot receives message, forwards to Thalamus |
| Slack | Event subscription — message events forwarded to Thalamus |
| Discord | Interaction endpoint — message events forwarded to Thalamus |
| GreenAPI webhook — incoming messages forwarded | |
| IMAP polling — Thalamus periodically checks inbox |
Each message is verified (platform signature), normalised, stored in memory, and broadcast to Strings via WebSocket. Messages appear in Strings with a channel badge showing their origin.
Important: Thalamus handles inbound only. Outbound messages (replying to Telegram, sending Slack messages) go through MCP triggers — not Thalamus.
Perception Triggers
Thalamus hosts 8 perception trigger types that let characters react to environmental events:
| Trigger | What It Monitors |
|---|---|
| File Watcher | File/directory changes on disk |
| URL Monitor | Web page content changes (polls and compares hash) |
| API Poller | API endpoint status (HTTP response codes) |
| System Monitor | CPU, RAM, disk thresholds |
| Process Check | Whether a specific process is running |
| Network Monitor | Network I/O thresholds |
| Microphone | Sound level detection |
| Webcam | Motion detection score |
When a perception trigger fires, it routes through Thalamus to the character's configured target (usually the Sequencer task runner).
Perception triggers require the Thalamus node on the character's canvas. They appear greyed out in the palette until Thalamus is added.
Custom Trigger Templates
You can create reusable schedule templates in the Thalamus configuration panel of the Visual Builder. Templates appear in the Sequencer's trigger dropdown with a pin icon, below the built-in presets.
This lets you define common schedules once ("Every weekday at 9 AM", "Every 15 minutes during business hours") and reuse them across multiple tasks.
Enabling Thalamus
- Add the Thalamus node to your character's canvas in the Visual Builder
- Perception triggers become available in the palette
- Timer and webhook triggers become available in the Sequencer
- Channel integration (Telegram, Slack, etc.) works through channel configuration in Strings
Thalamus runs as a lightweight service using Redis for state. All trigger configurations are synced from Anima at startup.
When You Need Thalamus
| Use Case | Why Thalamus |
|---|---|
| Scheduled tasks (cron, intervals) | Timer triggers managed by Thalamus scheduler |
| Receiving Telegram/Slack/Discord messages | Channel webhooks processed by Thalamus |
| Reacting to file changes or system metrics | Perception triggers routed through Thalamus |
| Webhook-triggered workflows | External HTTP POST → Thalamus → character task |
| Email monitoring | IMAP polling managed by Thalamus |
If your character only does direct chat (user types, character responds), you don't need Thalamus. Add it when you need scheduling, external channel integration, or environmental perception.
