Documentation

Architecture

Understanding how Vigil is built helps clarify what it can and cannot do with your data. The system is designed around a single constraint: it must be able to process email intelligently without ever storing the email itself.

Every architectural decision flows from that requirement
Privacy is structural, not promised — the system is incapable of exposing data it doesn't have

The data flow

An email's journey through Vigil follows a clear sequence:

An email arrives in your inbox and your forwarding rule sends a copy to your watcher address
Vigil's email routing infrastructure receives the raw message and passes it to the backend processing server
The backend parses the email, identifies which watcher it belongs to based on the address token, and hands it off to the agent engine
The agent engine loads context from the database — memories, thread state, watcher configuration — and calls an AI language model to produce analysis and decisions
Based on those decisions, it may update a thread, store a new memory, fire a webhook, or trigger an alert email
After all of that, the email body is discarded

The rest of the processing record is written to storage and the body is gone.

What is stored

Vigil stores four categories of data per email:

Metadata — who sent it, who it was addressed to, the subject line, and three timestamps tracking when it was sent, delivered, and processed
Analysis — a machine-generated summary, intent classification, urgency assessment, and key entities mentioned; produced by the AI model, never copied from the raw email
Thread state — updated to reflect the new message and current conversation status
Memories — any atomic facts the agent decided to retain

A complete action log entry is also created for every invocation, recording what the agent decided, what tools it used, its reasoning, and what the operation cost in compute time and AI usage. A one-way fingerprint of the email body is stored as proof of receipt — but not the content itself, and not anything that could be reversed to recover it.

What is not stored

Several things Vigil explicitly never holds:

Email bodies — never written to disk, at any point in the pipeline
Attachments — not processed or stored
Inbox credentials — Vigil never requests OAuth access to your email account and never holds credentials for any external service on your behalf

The only way data enters the system is through emails you explicitly forward — there is no background sync, no crawling, no polling of any account.

How the pieces connect

The frontend — what you see in your browser — is a read-only view into the data the backend has accumulated. It displays threads, memories, action logs, and alerts, but contains no business logic and cannot communicate directly with the database.

All changes go through the backend API
AI model calls are made entirely server-side
Your watcher's prompt, your memories, and your email metadata never touch the browser beyond what the UI needs to display them

Infrastructure

The service runs on a small set of components:

An email routing layer that receives incoming mail and passes it to the processing backend
A secure backend server that runs the agent logic and owns the database
A frontend application served over HTTPS
A transactional email service that delivers alert notifications

Each watcher address is just an alias — email arrives, gets processed, and the routing infrastructure does not retain a copy. The backend stores only what the agent produced from it.