Alfred — a cloud personal agent

A single-user personal AI assistant that lives in the cloud. One agent identity with continuous, self-maintaining memory, reachable from an installed PWA on phone and desktop. Built on Claude Managed Agents: the platform runs the brain and holds all memory; this repo holds everything around it. Zero self-managed servers.

What it does

• Chat with memory — streaming conversations in named sessions. The agent reads and writes small memory files, so it knows the owner across every session. Sessions auto-title themselves after the first reply.
• Research with verifiable outputs — web search and fetch, full reports and SVG diagrams delivered to a session outputs panel. Derived numbers must come from scripts saved beside their results, never from in-head arithmetic.
• Task modes — Solo, Team (a coordinator delegating to researcher/analyst/writer specialists plus an Opus advisor, with a live task graph), and Verified (a grader loop re-runs the agent until a rubric passes).
• Voice — hold-to-record voice notes with spoken replies (long replies get a spoken summary), and talk mode: an open-mic conversation with realtime transcription, a WebGL orb, sentence-streamed speech, and barge-in.
• Email, calendar, Notion — Gmail search/read/draft, calendar read/create/respond, and Notion search/read/write via MCP. Reads run freely; anything outward-facing (sending email, answering invites, writing to Notion) pauses for an in-app Allow/Deny approval.
• Proactive — twice-daily heartbeats that check open tasks against the real calendar; agent-set reminders and future tasks that fire on time and resume the conversation they came from; push notifications for everything worth knowing.
• Self-maintaining — nightly memory backups to S3, weekly "Dreams" that consolidate memory into a fresh store, a kill switch that pauses all autonomous activity, and a cost dashboard with per-session breakdowns under hard per-session budget caps.

Architecture

The load-bearing decisions:

• The platform is the source of truth. Conversation history lives in platform session events; agent memory lives in platform memory stores. The app database (DynamoDB) holds only summaries, metering, reminders, push subscriptions, and small config — never memory content.
• One API surface. All Anthropic traffic goes through libs/anthropic. The beta-header split between managed-agents and memory-store endpoints lives there and nowhere else.
• Secrets never touch the repo, the browser, or Vercel env. Everything secret sits in one Secrets Manager secret (pa/app), loaded at boot; Vercel env vars are non-secret config; AWS access is OIDC federation with no static keys; MCP credentials live in a platform vault the sandbox can never read.
• Cost is governed, not observed. Every session — including heartbeats and dreams — carries a hard platform budget cap. Usage lands in DynamoDB from the first message and /costs shows the month by day and by session.
• Injection defense is layered. Standing instructions live in a store the agent cannot write; email/Notion/web content is treated as untrusted data by prompt rule; and outward actions require human approval regardless.
• Everything AWS is CDK. One stack (apps/infra) owns the table, backups bucket, cron delivery, IAM policies, and alerting. Platform resources (agents, stores, deployments, vault) are provisioned idempotently by tools/provision.ts from versioned prompt files in infra/.

How it works

Workspace layout (Nx, pnpm)

apps/web          Next.js 16 App Router PWA: Home, chat, memory screen, cost dashboard
apps/infra        CDK stack for every AWS resource (table, backups, cron, IAM, alarms)
libs/anthropic    THE Anthropic API surface — sessions, events, memory, vaults, outputs
libs/db           DynamoDB repos — registry, metering, reminders, push subs, config
libs/elevenlabs   STT (Scribe) and TTS wrappers
libs/shared       Cross-cutting types and day-key helpers
infra/            Declarative agent specs (agents/*.agent.yaml) + prompts + store seeds
tools/            provision.ts (platform), restore-memory.ts, smoke.ts, add-secret.sh
docs/             PRD, platform verification notes, these diagrams

Setup

Prerequisites: Node 22+, pnpm, AWS CLI (SSO login), an Anthropic API key, an ElevenLabs API key, a Google Cloud project with a Workspace-internal OAuth client.

pnpm install
cp .env.example .env.local          # fill in ANTHROPIC_API_KEY + config
pnpm provision                      # platform: environment, agents, stores, vault; writes IDs
pnpm nx deploy infra                # AWS: table, backups, cron delivery, IAM, alarms
pnpm smoke                          # optional: live end-to-end check (~a few cents)
pnpm nx dev web                     # app on localhost:3000

One-time connects (signed in, in the browser): /api/auth/google/connect grants Gmail/Calendar offline access; /api/auth/notion/connect runs Notion's OAuth into the platform vault. Secret values are added by the operator only, via ./tools/add-secret.sh KEY_NAME (hidden input — values never reach the AI assistant or the repo).

Commands

Command	Purpose
pnpm nx dev web	Dev server
pnpm nx run-many -t typecheck test build	Full verification
pnpm provision	Idempotent platform provisioning; re-run after editing any infra/*.md prompt
pnpm nx synth infra / nx diff infra / nx deploy infra	CDK for the AWS resources
pnpm smoke	Live platform round-trip test (budget-capped)
npx tsx tools/restore-memory.ts <s3-key> <store-id>	Restore a memory backup into any store

Deploys: pushes to main auto-deploy via the Vercel GitHub integration; vercel deploy --prod --yes is the manual fallback.

Operations notes

• Backups: DynamoDB has point-in-time recovery; both memory stores export nightly to a versioned S3 bucket. The restore path is a script, and it has been drilled.
• Alerting: a CloudWatch alarm emails on failed nightly-rule deliveries (the daily canary for the whole cron path); Vercel emails on failed deploys; everything else is push notifications.
• Kill switch: the pause control in the sidebar stops heartbeats and pending timers; resuming fires anything missed. Backups are exempt.
• Dreams: every Sunday 03:30 Sydney the memory store is consolidated into a fresh one behind a sanity gate; old stores are archived, never deleted.

Documents

• docs/product_requirements_document.md — the PRD (scope, phases, requirements)
• docs/platform-notes.md — verified Managed Agents platform behavior; overrides the PRD where they differ
• docs/architecture.svg / docs/flows.svg — the diagrams above
• CLAUDE.md — working notes for AI-assisted development; tasks/todo.md — build history