Envoy is an email-native, stateless-LLM agent with structured persistent memory. It uses IMAP as a conversational workspace and GData (GDBM-backed notes) as its durable cognitive store.
Envoy is composed of four clearly separated layers:
| Layer | Responsibility |
|---|---|
| GPT (LLM) | Stateless reasoning; produces structured JSON responses |
| Python Orchestrator | Control logic, context gathering, validation, side-effects |
| IMAP Mailbox | Conversation workspace, task coordination, short/medium-term context |
| GData Notes | Durable long-term memory and structured state |
GPT has no persistent memory. All durable knowledge lives in Notes. Context is reconstructed on each call.
- Explicit state > implicit memory- Small context > large history- Inspectable systems > hidden magic- Structured data > free text- Deterministic behaviour > heuristics- Email is not truth storage; Notes are the durable source of truth
Layered retrieval is used to minimise token usage:
- Layer 0: Current email (always loaded)- Layer 1: Thread summary (short orientation)- Layer 2: Recent messages (optional)- Layer 3: Historical messages (only if required)
Thread summaries and structured metadata are stored in Notes under /threads/*.
Processing is iterative with a 9-phase state machine: triage → gathering → summarising → working → coding → composing → complete (or waiting/escalate). The LLM sets the phase each iteration.
Each LLM call returns structured JSON including status, memory reads/writes, actions, and reasoning.
Action dispatch is split by phase type:- Immediate actions (every non-terminal phase): write_notes, delete_notes, send_emails — executed by dispatch_immediate_actions() each iteration- Terminal actions (complete phase only): move_emails, delete_emails, confirmation reply — executed by execute_actions()Self-email checkpoints (continuation emails) enable crash recovery, pause/resume, and visible progress.
Email serves as both user interface and audit trail.
Envoy sends completion or summary replies describing what it did and why. Users may override behaviour by replying.
Inbox/
Active/
Tasks/
Agents/
Archive/
Done/Folder meanings:- Inbox – new mail- Active – ongoing threads- Tasks – machine-style actions- Agents – inter-agent/internal traffic- Archive – dormant but retained history- Done – completed items safe to purge
- Active threads remain in Active/ until summarised or dormant.- Dormant threads move to Archive/.- Completed threads are summarised, archived, and optionally deleted.- Task mail is deleted after successful processing.
The design supports iteration limits, cost tracking, idempotency, explicit recipients, escalation paths, and confirmation emails.
Model tiering is used: cheaper models for triage/gathering, full models for coding/reasoning. The LLM hints the next model via the next_model field; defaults are set per state in envoy/states/* notes.