Proactive Loop

Overview

The Proactive Loop is Yukkai's background intelligence system. Instead of waiting for you to ask, it continuously monitors your tasks, schedule, memory, and context to surface relevant alerts and recommendations at the right moment.

Think of it as a quiet assistant that watches everything going on — upcoming calendar events, overdue tasks, changing conditions — and nudges you when something deserves your attention. You can simply read the alert and dismiss it, or mark it as acted-on so Yukkai knows you've handled it.

Good to know: The Proactive Loop is separate from the WatchList. The WatchList monitors specific external data sources you define (stocks, weather, web pages). The Proactive Loop is broader — it analyzes your tasks, calendar, memory, and patterns to generate its own alerts.

How it works

The Proactive Loop runs on a configurable cycle. On each cycle, it performs the following steps:

1. Gather context — Pulls in your active tasks, calendar events, memory snapshots, and any pending WatchList triggers.
2. Analyze — An AI agent reviews the combined context to detect what needs attention: overdue tasks, schedule conflicts, forgotten follow-ups, or emerging patterns.
3. Generate alerts — If the agent finds something worth surfacing, it creates an alert with a priority level (low, medium, high).
4. Notify — New alerts are delivered to you as unread (pending) notifications.
5. Respect limits — A daily alert cap prevents spam. If you've already received the maximum for the day, lower-priority alerts are suppressed until the next day.

Key parameters

Parameter	Description	Default
morning_hour	Hour (0–23) when the morning briefing is generated	—
check_interval	Minutes between analysis cycles (min 5, max 1440)	—
max_alerts_per_day	Cap on alerts emitted per day (1–50)	—
enabled	Start or stop the loop	true

How to use it

Configuration

You can tune the Proactive Loop at any time. For example, to start the loop with a morning briefing at 8:00 AM, checking every 30 minutes, with a max of 10 alerts per day:

proactive(action: "configure", morning_hour: 8, check_interval: 30, max_alerts_per_day: 10, enabled: true)

To pause the loop entirely:

proactive(action: "configure", enabled: false)

Viewing alerts

• Pending alerts — Shows all unread alerts, sorted by priority:

proactive(action: "pending")

• History — Review the full alert log (most recent first):

proactive(action: "history", limit: 20)

Managing alerts

When you see an alert, you have two options:

• Dismiss — Mark it as seen. Use this when you've read it but no immediate action is needed:

proactive(action: "dismiss", alert_id: "a1b2c3d4")

• Act — Mark it as acted-on. Use this when you actually did something in response to the alert (completed the task, moved the meeting, etc.):

proactive(action: "act", alert_id: "a1b2c3d4")

Tip: Use act rather than dismiss whenever you took a concrete action. This helps Yukkai learn which alerts lead to real follow-through and improves relevance over time.

Triggering a manual cycle

If you don't want to wait for the next scheduled cycle, you can force an immediate analysis:

proactive(action: "run_cycle")

This runs the full analysis pipeline and returns only new alerts (ones not already surfaced).

Examples

Morning briefing

Configure the loop to deliver a morning briefing every day at 7:00 AM, with checks every 45 minutes and a generous daily cap:

proactive(action: "configure", morning_hour: 7, check_interval: 45, max_alerts_per_day: 15, enabled: true)

The morning briefing typically includes:

• Today's calendar overview
• Overdue and due-today tasks
• Any WatchList triggers that fired overnight
• Relevant memory-based reminders

Workday focus mode

Set a tighter loop during work hours — shorter intervals, lower alert cap to reduce noise:

proactive(action: "configure", morning_hour: 9, check_interval: 20, max_alerts_per_day: 5, enabled: true)

Weekend mode

Reduce frequency and alerts on weekends:

proactive(action: "configure", check_interval: 120, max_alerts_per_day: 3, enabled: true)

Tips

Don't set the interval too low

While the minimum is 5 minutes, extremely frequent cycles can generate repetitive alerts and consume resources. A good starting point is 30–60 minutes for most users.

Let the morning briefing do the heavy lifting

The morning briefing is the single most useful output of the Proactive Loop. It consolidates everything you need to know into one digest. Make sure morning_hour aligns with when you start your day.

Use act to improve relevance

Every time you mark an alert as act (rather than just dismiss), Yukkai learns that this type of alert leads to action. Over time, this feedback improves alert quality and reduces false positives.

Combine with WatchList for external monitoring

The Proactive Loop handles your internal context (tasks, calendar, memory). For external data — stock prices, weather changes, web page updates — set up WatchList entries. The Proactive Loop will incorporate WatchList triggers into its analysis, giving you a unified alert stream.

Check history to audit

Use history periodically to review past alerts. If you notice a pattern of low-value alerts, adjust max_alerts_per_day or consider whether your task/schedule data needs cleaning up.

Disable when you need quiet time

Running a focused work session? Temporarily disable the loop:

proactive(action: "configure", enabled: false)

Re-enable it when you're ready to receive alerts again. No alerts are lost — the loop will pick up where it left off on the next cycle.