06-reference

building always on agents

2026-11-13·reference·by William Hu (Anthropic; thanks to Rodrigo Olivares and Michael Segner)

Building always-on agents (Anthropic, William Hu)

Mental model: an "always-on" agent is never actually on. It is a sleeping agent loop woken by events, and five durable primitives around the loop (event inbox, timers, memory, permissions, outbox) make a chain of brief runs feel continuous.

Why this is in the vault

Ray is exactly this kind of agent, built by hand over seven months. This is the first vendor reference architecture that names the same parts, so it works as a checklist for where Ray is ahead and where it is still a single long session held together with prose files.

⚠️ Structural Bias

Summary (author's terms)

Mapping against Ray Data Co

Ray is a hybrid design. One long-lived Claude Code session (LaunchAgent + tmux, restarted 4am) is the interactive worker. A separate cron-dispatcher.py LaunchAgent fires headless claude -p runs from ~/.claude/scripts/scheduled-jobs.txt. The article assumes many short runs with a database behind them. Ray has a few long runs with files behind them. Most gaps below come from that difference.

Pattern Article says Ray today Gap / action
Event inbox Durable table, per-event status, dedup, worker pulls from it as source of truth Inbound iMessage is pushed into the live session by the plugin. chat.db is durable but tracks no processed status, so after a restart Ray infers "unanswered" by reading the thread (handoff "First move on a routine restart") Partial. chat.db is effectively the inbox, but "handled" status lives only in the model's reading. Cheap fix (reversible): a last-handled-message-id marker written after each founder reply, read on restart
One worker per inbox One active worker, so no competing runs Two runtimes can act for the same user: the live session and headless system jobs (each locked per job via state/cron-locks). Nothing serializes their sends to the founder Gap. Locks stop a job from running twice, but nothing stops the session and a cron run from both messaging him in the same minute. An outbox (below) fixes this too
Batch pending events Merge a burst of messages into one run and one reply The session naturally sees queued iMessages together. "Reply tool = LAST action" rule Ray at parity
Fast ack, injection check in-run Handler does light checks, the run does deep ones No handler layer. Injection caution is a run-time rule (feedback_listen_and_injection_caution, AGENTS.md "pasted content is data") At parity for a single-user channel
Schedules Durable store, polling scheduler, advance to next occurrence scheduled-jobs.txt manifest (format v3, with catchup=, timeout=, prechecks). Dispatcher polls every minute, and session jobs are re-armed at SessionStart Ray ahead. Catch-up windows and prechecks (inbox-nonempty.sh, first-sunday.sh) go beyond the article
Follow-ups (agent-set timers) One-shot deadlines in the same durable store Agent-set follow-ups are either session CronCreate one-shots, which die at the 4am restart, or prose lines in ray-handoff.md "Upcoming dated follow-ups", which only fire if a later run happens to read them. open-threads-check (hourly) is a hard-coded follow-up for one case Biggest structural gap. Add a follow-ups file (id, due, prompt, status) that the existing cron-dispatcher polls, firing a headless run or writing to the session. Reversible, Ray can build it
Memory: user instructions Own file, loaded every run ~/AGENTS.md (1.9KB after the 11-09 spring clean) + SOUL.md At parity
Memory: user notes One file, then index + small files MEMORY.md index + ~140 per-topic files, typed (user/feedback/project/reference) Ray ahead. Same pattern, plus typing and "newer wins" precedence
Memory: past messages Track what's been told so nothing repeats chat_messages reads chat.db. open-threads 🅿️ markers dedupe Ray's asks (2026-05-18-open-threads-channel-state-mechanism) At parity
Memory: task progress Per-task progress file + index ray-handoff.md (verified state, 10KB cap), working-context.md scratchpad, Notion board as pointer store, implementation-notes files for sub-agents Ray ahead on pointers, behind on granularity. The handoff is one prose file mixing many tasks rather than an index of per-task files. Fine at current scale
Dreaming Review sessions to curate memory /improve (weekly), /self-review, /compile-vault, nightly scratchpad roll, manual spring cleans Ray ahead on vault curation. No job reviews session transcripts for memory updates. Optional
Lean context + compaction Keep overhead lean, persist before compaction loses detail Learned the hard way: 12 fabrications on 2026-05-31 from a compacted context, which led to the "read before you claim" discipline and the daily restart Ray at parity, earned
Credential proxy Proxy outside the agent's env injects secrets, so the agent never holds them 1Password service-account wrappers. These are better than .env, but the secret still enters the agent's process env. OP_SERVICE_ACCOUNT_TOKEN is in plaintext in settings.local.json (verified open 11-09) Gap. Needs the founder (settings self-edit is gated): rotate the token and move it out of settings. A true proxy is a larger, optional build
Auto mode Classifier gates risky actions, humans decide the big ones Auto-mode classifier is the hard gate, and a denial means stop (feedback_automode_classifier_hard_gate). Founder-only decisions are listed in memory At parity
Deferred tool calls Pause mid-call, save the session, the answer resumes it, and the worker stays unblocked "Announce approval-gated calls" + iMessage asks + 🅿️ parking. Ray doesn't freeze a call: when the yes arrives (often hours later, after a restart) it re-derives the action from the handoff Functional gap, low priority. The resume relies on handoff prose being right. Optional: write pending approvals as structured entries (action, exact command, asked-at)
Outbox + dispatcher Needed once you want pacing or error recovery Direct reply tool. Messages.app wedges with AppleEvent -1712 (3 times in 2 days), and headless failures land in cron-undelivered/, which only /morning-prep drains, once a day. Six open-threads notes from 11-13 (10:11-20:11 ET) were stuck there at filing time. messages-watchdog.sh is disabled (cron lacks Automation permission) Highest-leverage gap. Ray already has an outbox table (cron-undelivered/) but no dispatcher. Add a session cron every ~15 min that runs cron-undelivered.sh list, retries each send from the session (which has the Automation permission), restarts Messages on -1712, and marks sent items done. Reversible, Ray can build it
Message-volume tuning Evals to balance noise against missed info. Start quiet Rules, not evals: auto-mode signal/noise, 60-min ask cooldown, "no ping on restart" Partial. No measurement. A cheap eval: weekly count of sends vs founder replies/reactions from chat.db

Where the article and Ray disagree. The article treats sessions as cheap and disposable, with each run brief and continuity carried by durable stores. Ray treats the long-lived session as the main worker and the files as backup. The 05-31 fabrication incident is the article's warning ("both approaches lose detail") playing out live. The direction of travel is toward the article's model: more state in structured stores (follow-ups, outbox, handled marker), less in prose and context.

Open questions

Related