Alerts (Event Handlers)
Event handlers are the automation engine behind Aegis AI. They let you define rules like "if someone walks up the driveway after midnight, send me a Telegram message" — using natural language, not code.
Every time the VLM analyzes a clip, the resulting description is evaluated against your active event handlers. When a match is found, Aegis fires the handler and sends you a notification.
Open via ⚙️ Settings → Persona → Memory (Alerts tab within the Agent Settings drawer).
How Alerts Work
- A camera records a clip (triggered by motion, schedule, or a skill)
- The VLM analyzes the clip and produces a text description (e.g. "Person walking up the driveway carrying a large brown box")
- Aegis compares the description against every enabled event handler
- The LLM evaluates whether the description matches the handler's condition using natural language understanding — not simple keyword matching
- If it matches, the handler fires:
- A notification is sent through your configured messaging channels
- The notification includes the AI description and a snapshot from the clip
- The trigger count increments and the timestamp updates
Why Natural Language Matching Matters
Traditional security camera alerts use crude triggers — any motion, any pixel change. This causes alert fatigue — dozens of false positives per day from tree branches, shadows, animals, and headlights.
Aegis uses the LLM to evaluate conditions semantically. This means:
| Traditional Motion Alert | Aegis Natural Language Alert |
|---|---|
| Fires when anything moves | Fires only when the description matches your condition |
| "Motion detected" — 50 alerts/day | "Person approaching front door" — 3 alerts/day |
| Can't distinguish people from animals | Understands the difference between a delivery driver and a stray cat |
| No context | Uses agent memory to know that "Mom's blue Honda" isn't a threat |
Creating an Event Handler
Click Add Handler and fill in the fields:
| Field | Description | Example |
|---|---|---|
| Event Type | The category of event to watch for | Motion Detected, Object Detected, Custom |
| Camera | Which camera this rule applies to. Select "All Cameras" for global rules. | Front Porch, Driveway, All Cameras |
| Condition | A natural-language description of what to look for. The LLM compares each VLM analysis against this text. | "Person at the front door" |
| Description | A label for the rule so you can identify it in the list | "Front door visitor alert" |
| Enabled | Toggle the rule on or off without deleting it | ✓ On |
Writing Effective Conditions
The condition text is matched by the LLM against the VLM's clip description. Natural language works best — the more specific and descriptive your condition, the fewer false positives you'll get.
Great Conditions (Specific and Effective)
| Condition | What It Catches |
|---|---|
"Person approaching the front door" | Visitors, delivery drivers, anyone walking to the entrance |
"Person at the front door with a package" | Deliveries specifically |
"Vehicle pulling into the driveway" | Cars arriving — ignores parked cars and pedestrians |
"Animal in the backyard" | Pets, wildlife, stray animals |
"No one visible in the baby's room" | Absence detection — alerts when the room is empty |
"Person I don't recognize near the garage after sunset" | Unknown visitors at night (works with agent memory) |
"Multiple people gathering on the sidewalk" | Group activity — distinguishes from a single passerby |
Poor Conditions (Will Fire Constantly)
| Condition | Problem |
|---|---|
"Something happening" | Too vague — matches almost every clip |
"Movement" | Same problem — everything "moves" |
"Person" | Fires for any person anywhere, regardless of context |
"Car" | Fires for parked cars, driving-by traffic, and intended arrivals |
Tips for Writing Conditions
- Include location context: "person at the front door" is better than just "person"
- Include action context: "person approaching" is better than "person present"
- Include time context: "after sunset" or "late at night" adds a useful filter
- Use negation for absence: "no one in the room" or "the porch is empty"
- Combine multiple criteria: "unknown vehicle in the driveway at night" narrows the scope effectively
Managing Handlers
| Action | Description |
|---|---|
| Enable / Disable | Toggle individual rules without removing them. Disabled handlers are grayed out and skipped during evaluation. |
| Delete | Permanently removes a handler. This cannot be undone. |
| Trigger Count | A running total of how many times this handler has fired since creation. Useful for identifying noisy rules — if a handler fires 200+ times per day, the condition is probably too broad. |
| Last Triggered | Timestamp of the most recent trigger. Shows "Never" if the handler hasn't fired yet. |
Alert Delivery
When a handler fires, the notification is sent through all connected messaging channels:
| Channel | What You Receive |
|---|---|
| Telegram | Text message with the AI description + camera snapshot image |
| Discord | Embedded message in the configured channel with description and image |
| Slack | Message with description and image attachment |
What an Alert Looks Like
A typical alert message contains:
- Agent name (from your Soul configuration)
- Camera name — which camera triggered the alert
- AI description — what the VLM saw in the clip
- Timestamp — when the event occurred
- Snapshot — a frame from the clip showing the event
If no messaging channels are configured, alerts still appear in the Aegis AI interface and are logged in the timeline. To set up messaging channels, see the Messaging guide.
Example Alert Workflow
Here's a complete example from rule creation to notification:
-
You create a handler:
- Camera: Front Porch
- Condition: "Person approaching the front door with a package"
- Description: "Package delivery alert"
-
A delivery happens:
- The front porch camera records a clip
- The VLM analyzes it: "Person in brown uniform walking up the steps carrying a large cardboard box. They place it next to the door and walk back to a brown delivery truck."
-
The LLM evaluates:
- It compares the VLM description against your condition
- "Person approaching the front door with a package" — match
-
You receive a Telegram message:
📦 Package delivery alert (Front Porch) Person in brown uniform walking up the steps carrying a large cardboard box. They place it next to the door and walk back to a brown delivery truck. [snapshot image attached]
Tips
- Start specific, broaden later — begin with narrow conditions and loosen them if you're missing events
- Use camera filters — assign handlers to specific cameras to reduce false positives. A "person detected" rule on an indoor camera will fire very differently than on an outdoor camera
- Check trigger counts — if a handler fires hundreds of times per day, the condition is probably too broad
- Combine with memory — the agent's Memory context helps it understand recurring patterns. Teach the agent who your family members and regular visitors are so it can distinguish between "expected" and "unexpected" visitors
- Review and refine — after the first few days, review which handlers are firing too often or too rarely, and adjust conditions
- Use time-based conditions — conditions like "after 10pm" or "before sunrise" dramatically reduce noise during predictable hours