feat: Add reminder agent example with proactive scheduler support

[Aditya (adityajha2005)]

Personal Reminder Agent (v1)

A production-ready reminder agent built with Flux that enables users to set reminders via iMessage with automatic proactive delivery.

Note: This is v1 of the reminder agent. If this gets merged, we plan to add more features in future iterations (recurring reminders, reminder management commands, better time parsing, etc.).

Features

Core Functionality

• Natural Language Parsing: Supports relative times ("in 30 seconds", "in 2 hours") and absolute times ("tomorrow at 5pm", "at 9pm")
• Proactive Delivery: Background scheduler automatically sends reminders when due (checks every 10 seconds)
• Multi-user Support: Handles reminders for multiple phone numbers
• Persistent Storage: Reminders saved to JSON file with mutex protection

System-Check

• Race Condition Protection: Mutex + in-memory cache prevents data loss from concurrent operations
• Input Validation: Validates reminder text length, future times, and max date range
• Error Handling: Helpful error messages when time parsing fails
• Signal Handler Guards: Prevents duplicate handlers on hot reload/restart
• Modular Code: Reusable functions for time parsing, text extraction, and message formatting
• Type Safety: Proper TypeScript types throughout
• Async/Await: All file operations properly async with mutex serialization
• Framework Extension: Added optional init method support to FluxAgent interface for proactive messaging

Screenshots

Example Usage

User: "Remind me to check scheduler in 10 seconds"
Agent: "Reminder created: 'check scheduler' at 12/29/2025, 7:51:00 AM
        ⏰ You'll receive this reminder in 10 seconds."

[10 seconds later - automatic]
Agent: "Reminders: ⏰ check scheduler"

Files Added

• examples/reminder-agent/agent.ts - Main agent implementation
• examples/reminder-agent/README.md - Documentation
• examples/reminder-agent/package.json - ES module configuration
• examples/reminder-agent/reminders.json - Reminder storage (auto-created)

Framework Changes

• src/index.ts - Added optional init method support for proactive messaging
• Enables agents to send messages proactively (not just in response to incoming messages)

Testing

# Validate agent
cd examples/reminder-agent
bun ../../src/index.ts validate

# Test locally
bun ../../src/index.ts run --local

# Run in production
bun ../../src/index.ts run --prod

Future Enhancements (v2+)

If this gets merged, potential future improvements:

• Recurring reminders (daily, weekly, etc.)
• Reminder management commands (list, delete, update)
• Better time parsing (more natural language support)
• Background service/daemon mode for always-on reminders
• Reminder categories/tags
• Integration with calendar systems

Notes

• Reminders are only sent proactively in production mode (requires init method support)
• In local mode, reminders are delivered when user sends next message
• Agent must be running for scheduler to work (no background service yet)