# `reminder.rs` – Reminder Scheduling

## Purpose
Implements **time‑based reminders** that can trigger notifications or automatically create tasks. Reminders are stored under `~/.todozi/reminders/` and can be queried, scheduled, and persisted.

## Main Types
| Type | Description |
|------|-------------|
| `Reminder` | Struct with fields: `id` (UUID), `message` (text to display), `trigger_at: DateTime<Utc>`, optional `repeat_interval: Option<Duration>`, `created_at`. |
| `ReminderCollection` | In‑memory map of `Reminder`s with CRUD helpers and persistence to JSON files. |

## Public API
| Function / Method | Description |
|-------------------|-------------|
| `schedule_reminder(reminder: Reminder) -> Result<()>` | Persists a new reminder and registers it with the internal scheduler. |
| `list_due_reminders() -> Result<Vec<Reminder>>` | Returns all reminders whose `trigger_at` is ≤ now. |
| `run_reminder_service() -> impl Future<Output = ()>` | Async background task that periodically checks for due reminders, emits a notification (stdout/CLI), and optionally creates a linked Todozi task. |
| `cancel_reminder(id: &str) -> Result<()>` | Removes a pending reminder from storage and stops its scheduled execution. |

## Typical Usage
```rust
use todozi::reminder::{Reminder, schedule_reminder, run_reminder_service};
use chrono::{Utc, Duration};

#[tokio::main]
async fn main() -> todozi::error::Result<()> {
    // Create a reminder for 5 minutes from now
    let reminder = Reminder::new(
        "Check server health".into(),
        Utc::now() + Duration::minutes(5),
        None, // one‑off
    );

    // Schedule it
    schedule_reminder(reminder).await?;

    // Start the background service (runs until the program exits)
    tokio::spawn(run_reminder_service());

    // ... rest of your application ...
    Ok(())
}
```

## Integration Points
* **CLI (`cli.rs`)** – Exposes `todozi reminder` sub‑commands (`create`, `list`, `cancel`) that call the above API.
* **Server (`server.rs`)** – Provides `/reminders` REST endpoints for remote scheduling and querying.
* **Embedding (`emb.rs`)** – Reminders can be indexed for semantic search (`search_memories` includes them when `memory_type = Reminder`).
* **Task generation** – When a reminder fires, the service can auto‑create a Todozi task via `Done::create_task`.

## When to Use
- Schedule future actions (e.g., “run backup at 02:00”, “review daily report”).
- Provide user‑visible alerts for time‑sensitive tasks.
- Coordinate with the agent system (e.g., an AI agent can set a reminder after a planning step).

## Design Notes
- Reminders are stored as separate JSON files (`<id>.json`) to keep them lightweight and easily editable.
- The background service uses a simple `tokio::time::interval` loop; for high‑frequency reminders a more sophisticated scheduler (cron‑style) can be plugged in.
- Duplicate `id`s are prevented by generating a UUID for each new reminder.

---

*Generated by GPT‑OSS – documentation for `reminder.rs`.*
