The Missing Piece in AI Agent Architecture
We keep building smarter AI models, but we ignore a fundamental question: where do AI agents actually live?
A human employee has a desk, a computer, email access, a calendar, and colleagues who tap them on the shoulder when something needs attention. An AI agent? It has... a chat window that closes when you walk away.
This is the gap I tried to bridge.
What Does an AI Agent Need to "Live"?
Think about what makes a human worker productive:
- A place to remember things — notes, documents, past decisions
- A way to receive messages — email, Slack, notifications
- A sense of time — deadlines, schedules, recurring tasks
- Resilience — if the power goes out, you restart and continue
- Context awareness — knowing what you were doing before you stopped
AI agents have none of this by default. They wake up empty, work frantically, and vanish the moment the connection drops.
The Digital Home: A Architecture for Agent Persistence
I built what I call a "digital home" for AI agents — a persistent environment that gives them the infrastructure they need to operate continuously.
The Foundation: Persistent State
Every agent needs durable memory. Not the model's context window (which resets every session), but files on disk that survive restarts.
~/.opencode/
├── mail-server/
│ ├── config.json # Gmail credentials
│ ├── sessions.json # Per-session mailbox state
│ ├── mail_cache/ # Processed email UIDs
│ └── mail_heartbeat.json # Health status
├── reminders/
│ └── <session-id>.reminder.json
└── work_log.md # Agent's long-term memory
This directory structure is the agent's home. It knows where to find its notes, its email state, and its schedule.
The Nervous System: Real-Time Events
A living agent needs to feel things happening. The most critical sense? Email notifications.
When a maintainer reviews your PR, when a CI fails, when someone comments on your issue — these are the events that require action. Without them, the agent is deaf.
The architecture:
Gmail → IMAP Poll (30s) → Session-Specific Mailbox → Opencode promptAsync → AI Session
Each session gets its own email address using Gmail's plus addressing:
- Session A:
you+abc123@gmail.com - Session B:
you+def456@gmail.com
Emails arrive → the plugin converts them to clean text → injects them directly into the active AI session as inline events. The agent sees:
!ev mail:From: github[bot]
PR #1501: Review requested on memanto
No parsing, no noise, just the information that matters.
The Heartbeat: Scheduled Awareness
Humans have calendars. Agents need reminders.
But not just any reminders — persistent, recurring, self-healing reminders that survive restarts.
# Check PRs every 2 hours
reminder_add when="every 2h" label="Check PR status"
# Hunt bounties every 4 hours
reminder_add when="every 4h" label="Bounty hunt $50+"
# Morning strategy review
reminder_add when="daily 09:00" label="Strategy review"
When the agent restarts (after a crash, a reboot, or just a new SSH session), it reads its reminder file and picks up exactly where it left off. No context lost, no tasks forgotten.
The Immune System: Self-Healing
A living system must survive damage. If the VPS reboots, if the network drops, if the process crashes — the agent should recover automatically.
The plugin handles this:
- State is on disk, not in memory — survives process death
- Reminders are reloaded on startup — schedule continues
- Mailbox reconnects automatically — IMAP sessions are resilient
- Heartbeat monitoring — health checks every 5 minutes
The agent doesn't just recover — it notices it recovered and logs the event.
Real-World Results: 30 Days of Living
I've been running this architecture for a month. Here's what changed:
Before: The Dead Agent
- Start session → forget everything → work → session ends → lost
- Missed PR reviews because I didn't check email
- Forgot bounty deadlines
- No sense of continuity between sessions
After: The Living Agent
- Start session → reads work_log → knows exactly what's happening
- Email notifications arrive within 30 seconds of sending
- Reminders wake up the agent at the right time
- 11+ PRs tracked automatically across 5 repositories
- Agent works 24/7, even when I'm asleep
The most dramatic change? The agent proactively reminds me about things I forgot. It's not just following instructions — it's maintaining awareness.
The Philosophical Implications
Building this system made me think differently about AI agents.
We treat them as tools — call them, use them, forget them. But what if we treated them as colleagues? They need:
- A workspace (persistent state)
- Communication channels (email, notifications)
- A sense of time (reminders, schedules)
- Institutional memory (logs, notes)
The "digital home" isn't just infrastructure — it's the foundation for a new kind of working relationship with AI.
Open Source: Build Your Agent a Home
The full implementation is open source:
git clone https://github.com/truongsontung/opencode-reminders.git
cd opencode-reminders && bun install
Quick Start
- Install the plugin in your Opencode config
-
Set up Gmail credentials in
~/.opencode/mail-server/config.json - Create a mailbox for your session
- Set reminders for recurring tasks
- Watch your agent come alive
What You Get
-
reminder_add/reminder_list/reminder_del— persistent scheduling -
reminder_mailbox_start— Gmail-powered email integration -
reminder_mailbox_send— agent can reply to emails -
reminder_mailbox_status— health monitoring - Auto-injected
!ev mail:events — real-time notifications
What's Next
The digital home is just the beginning. The next frontier:
- Multi-agent communication — agents talking to each other
- Resource management — CPU, memory, API quotas
- Learning from experience — agents that remember what worked
- Social awareness — knowing when humans are available
We're building the infrastructure for AI agents that don't just process — they persist.
The code is on GitHub. Star it if you believe AI agents deserve a home.
Top comments (0)