The Open Framework for Building Agents
Personal Agent Template — Architecture
Back to README | See also: Environment, Customization
This document describes the technical architecture of Personal Agent Template — a durable personal AI assistant built with Eve, Nuxt 4, and Better Auth.
System overview
The app runs as two cooperating services on Vercel:
flowchart TB
subgraph surfaces [User surfaces]
web[Web chat — Nuxt]
slack[Slack DMs and mentions]
imessage[iMessage — Sendblue]
end
subgraph eve [Eve agent — agent/]
channels[Channels: eve · slack · sendblue]
tools[Tools: weather · save_memory]
skills[Skills and connections: Linear MCP]
end
subgraph nuxt [Nuxt app — apps/web/]
api["/api/* — public API"]
internal["/api/internal — agent-only"]
auth[Better Auth]
db[(NuxtHub SQLite — Drizzle)]
end
connect[Vercel Connect — Linear · Slack]
surfaces --> eve
eve -->|"HTTP + Bearer INTERNAL_API_SECRET"| nuxt
api --> db
internal --> db
auth --> db
nuxt --> connect
| Vercel service | Entry | Role |
|---|---|---|
web |
/ |
Nuxt UI + Nitro API |
eve |
/_eve_internal/eve |
Eve agent runtime |
vercel.ts composes the peer Nuxt and eve services during the Vercel build.
Project structure
personal-agent-template/
├── agent/ # Eve agent
│ ├── agent.ts # Model and agent config
│ ├── channels/ # eve (web), slack, sendblue
│ ├── tools/ # weather, save_memory
│ ├── skills/ # e.g. daily-summary.md
│ ├── connections/ # Linear MCP
│ ├── lib/ # base-instructions, memory-internal, slack-internal
│ └── instructions.ts # session.started hooks (memory injection)
├── apps/web/ # Nuxt frontend, Nitro API, and shared code
│ ├── app/ # pages, components, composables
│ ├── server/ # API, database, and server utilities
│ └── shared/ # cross-layer types and helpers
├── vercel.ts # Peer Vercel service composition
└── docs/ # Documentation
Request flows
Web chat
- User opens
/chat/[id]— Nuxt loads thread via/api/threads - Chat streams through the peer eve service routed by Vercel
- Tool calls render in
MessageContentEve.vue save_memoryshows approval UI (ToolSaveMemory.vue)
Session memory injection
- Eve fires
session.started(agent/instructions.ts) - Agent calls
GET /api/internal/memory?userId=...with bearer token agent/lib/memory-internal.tsbuilds prompt section- Appended to agent instructions for the session
Start a new chat after importing memory so injection picks up changes.
Slack
- Slack events hit Eve's slack channel (
agent/channels/slack.ts) - Linked users map Slack ID → app user via
slack_linkstable - Unlinked users get instructions to generate a link code in the web app
- Link flow: web generates code → user DMs
link <code>→ agent consumes via internal API
Sendblue (iMessage)
- Sendblue delivers inbound messages to Eve's sendblue channel (
agent/channels/sendblue.ts) - The sender's E.164 number maps to an app user via
phone_links(set in Settings → Profile) - Unlinked senders receive instructions to add their number in the web app
- Replies go back through Sendblue; tool approvals link to the web chat
Integrations (Linear)
- User connects Linear in Settings → Integrations
- Vercel Connect provisions MCP credentials
- Eve connection (
agent/connections/linear.ts) exposes Linear tools to the agent
Internal API
Routes under /api/internal/* require:
Authorization: Bearer <INTERNAL_API_SECRET>
Validated in server/utils/internal-api.ts.
| Route | Purpose |
|---|---|
GET /api/internal/memory |
Fetch user memory for session injection |
POST /api/internal/memory |
Save memory from agent tool |
GET /api/internal/phone/link |
Resolve phone number → app user |
GET /api/internal/slack/link/member |
Resolve Slack user → app user |
POST /api/internal/slack/link/consume |
Consume link code |
Agent-side clients live in agent/lib/*-internal.ts.
Database
SQLite via NuxtHub. Schema in server/db/schema/.
Key tables:
| Table | Purpose |
|---|---|
user / session / account |
Better Auth |
threads |
Chat threads |
user_profile |
Name, timezone, phone |
user_memory |
Long-term memory by category |
phone_links |
Phone ↔ app user mapping (Sendblue/iMessage) |
slack_links |
Slack ↔ app user mapping |
slack_link_codes |
Temporary link codes |
Migrations: pnpm db:generate → pnpm db:migrate.
Memory model
- Categories — fixed set in
lib/types/memory.ts - One block per category —
setMemoryForCategoryreplaces all rows for a category - Sources —
import,agent,manual - Import — Raycast-style paste parser (
server/utils/memory-import.ts)
Auth
Better Auth with email/password. Config: server/utils/auth.ts, route: server/api/auth/[...all].ts.
Global middleware: apps/web/app/middleware/auth.global.ts.
Eve docs
For channels, tools, connections, and deployment details, read Eve guides in node_modules/eve/dist/docs/public/.