Architecture Decision Records

Persisted Q&A Context Resources and Human-Gated Improvement Loop

Gateway Priority Message Queue

Memory Yield Contract

Inngest Runtime SQLite Forensics and Stale-Run Sweep Contract

Mandatory Memory Participation Contract

Gateway Channel Muting and Known Issues

Channel-Aware Prompt Injection & Platform Formatting

Kubernetes Cluster Resilience Policy

Session-Scoped Webhook Subscriptions with NDJSON Streaming

NAS Degradation Local/Temp/Queue Fallback Contract

No-Op Inference Circuit Breakers

Task Triage Output Contract

Content Review Pipeline — Inline Feedback & Agent Update Loop

Seamless Agent Context

joelclaw has a capable memory infrastructure: Typesense hybrid search (keyword + vector) with 103+ observations, system knowledge collections (ADRs, skills, insights), a write pipeline (observe → c…

Agent Lifecycle CLI — `joelclaw agent`

Recall Rewrite Reliability Contract

ADR Priority Rubric and Daily Ranking

VIP Contextual Narrative Briefs

The VIP email pipeline (`vip-email-received.ts`) produces analytical briefs: thread stats, followed links, binary "needs attention: yes/no." Joel wants **narratives** — briefs that read like an exe…

Compaction Recovery Pipeline

Compaction is the single largest source of context loss in joelclaw sessions. When pi compacts, the LLM summarizes the conversation into ~2K tokens, discarding conversational nuance, debugging insi…

JoelClaw Web Auth & Dashboard — Better Auth + Convex

Discord Rich & Interactive Messaging via discordjs-react

Dynamic Inference Provider Scheduling

Voice Agent Interview Mode

Gateway Reactions, Replies & Social Channel Configuration

LiveKit Voice Worker Durability Contract

Scheduled Prompt Tasks

System-Wide Taxonomy + Concept Contract (No Tag Soup)

Mandatory Taxonomy Classification

Taxonomy-Aware Skill Retrieval

First-Class Media Handling from Connected Channels

Budget-Aware Memory Retrieval Policy

Agent-Secrets Lease Deduplication & OTEL Integration

Channel Message Triage Router

Video Content Pipeline Expansion — Clip Segmentation + Content Repurposing

joelclaw's video pipeline currently handles **ingest only**: download → transcribe → enrich vault note. The output is a single vault note with a wall-of-text transcript and an AI-generated summary.…

Multi-Language LSP Extension for pi-tools

The current `ts-check` extension in pi-tools is unreliable. It spawns a tsgo LSP process per project root but frequently fails to return useful diagnostics, hover info times out, and the JSON-RPC l…

pi-tools Enhancement Cycle — Commit Tool, Web Extractors, MCQ

After evaluating oh-my-pi (`can1357/oh-my-pi`) as a potential replacement for stock pi, we decided to stay on stock pi and cherry-pick patterns into pi-tools (see ADR-0059 for LSP, ADR-0060 for swa…

Heartbeat-Driven Task Triage

Memory Write Gate V1 (Soft, LLM-First, Three-State)

Typesense-Native Memory Categories (SKOS-Lite V1)

Forward Triggers for Time-Based Memory Preload

Memory Write Gate V2 Calibration and Governance

Memory Dual Search (Vector + Graph) Activation Plan

Unified Caching Layer

Discord Thread-Forked Sessions

Discovery Enrichment Pipeline

Documentation Gardener System

Secret Redaction & Network Intercept

AT Protocol Mail Adapter for Capability Port

joelclaw Native App — iPhone, Watch, CarPlay

Inngest-Backed Swarm/DAG Multi-Agent Orchestration

`ralph-loop` executes PRD stories **sequentially** — one codex session per story, linear chain. This works for implementation loops but can't express:

Memory Knowledge-Graph Substrate (Deferred, Activation-Gated)

Integrate 20-Year Twitter Archive as a Typesense-Backed Corpus

Dream Process — Agent Self-Reflection Loop

The system currently has two feedback mechanisms:

Adopt architecture decision records

Architecture decisions in this project are made implicitly — through code, conversations, and tribal knowledge. When a new contributor (human or AI agent) joins the codebase, there is no record of …

Build joelclaw instead of deploying OpenClaw

ADR-0002 assumed OpenClaw would be the orchestration layer for the personal assistant system. After 6 sessions of infrastructure work, the system has evolved beyond what OpenClaw provides in severa…

0004 — AT Protocol as Bedrock

Adopt Inngest multi-agent pipeline for durable autonomous coding loops

joelclaw needs the ability to execute long-running autonomous coding workloads — send an event, go AFK, wake up to stacked PRs with every iteration traceable. No durable autonomous coding loop exis…

Add post-loop retrospective for skill evolution and memory ingestion

ADR-0005 established the durable PLANNER → IMPLEMENTOR → REVIEWER → JUDGE loop. ADR-0007 improved loop execution quality (Docker isolation, duration tracking, stricter controls). The system can now…

9. Rename `igs` CLI to `joelclaw`

Redis-Backed PRD State for Agent Loops

The agent loop pipeline (ADR-0005) runs a PLANNER → IMPLEMENTOR → REVIEWER → JUDGE cycle across stories defined in a PRD. Originally, loop state — which stories have passed, which are being retried…

Planner generates PRD from goal

The agent loop requires a hand-crafted `prd.json` before it can start. Writing PRDs is the bottleneck — each one requires understanding the codebase, scoping stories to be small enough for a single…

Loop architecture: TDD flow with separated roles

The current agent loop (ADR-0005) has a backwards flow: implement → write tests → check results. This causes systemic failures:

Idempotency Guards for Loop Event Chain

The agent loop event chain (ADR-0015) has no protection against parallel execution. Duplicate `agent/loop.start` events — from accidental double-fires, CLI retries, or stale Inngest replays — creat…

Adopt pi-native gateway pattern with Redis event bridge for system orchestration

ADR-0010 established the need for a central system loop gateway — an autonomous orchestrator that runs SENSE→ORIENT→DECIDE→ACT→LEARN and chose a hybrid event-driven + cron heartbeat approach. It le…

Rename events from imperative commands to past-tense notifications

The system-bus event names are a mix of two styles:

Adopt comprehensive agent memory system

Agents on this system lose conversational nuance between sessions. Memory is the critical missing capability — without it, every session starts from zero, hard-won debugging insights evaporate, use…

Docker Sandbox for Agent Loops

Agent loop iterations (IMPLEMENTOR, TEST-WRITER) currently spawn `codex exec` and `claude -p` directly on the host machine via `Bun.spawn()`. This means:

Network architecture: start with what works, grow as needed

Align Inngest Rig with SDK Best Practices

Replace Docker Desktop with Colima + Talos for container runtime

`panda` (Mac Mini M4 Pro, 64 GB) runs 24/7 as a headless server managed via Tailscale SSH. The container runtime powers the k3d cluster (`joelclaw`), which runs Redis, Qdrant, and Inngest as Kubern…

Central + satellite session routing for gateway events

ADR-0018 established a Redis event bridge between Inngest functions and pi sessions. The initial implementation pushed every event to a single shared `joelclaw:events:main` list. This worked for on…

Layered watchdog for gateway heartbeat failure detection

The central gateway session (ADR-0036) receives heartbeats from an Inngest cron every 15 minutes. But if Inngest itself goes down — the server crashes, the worker dies, Redis becomes unreachable, o…

Embed pi as a library in a joelclaw gateway daemon

The current central gateway session (ADR-0036) runs pi inside tmux, managed by launchd. A gateway extension injects events via `sendUserMessage()`. This works for Redis-based notifications but has …

Self-host Convex as the real-time data layer for joelclaw.com

joelclaw.com is a statically-generated Next.js 16 site with MDX content. It has no database, no auth, no real-time features. Joel wants to add:

Google Workspace Access via gogcli

Telegram Rich Replies, Outbound Media, and Agent Voice

Agent Voice Conversations via Self-Hosted LiveKit

Private-First PDS with Bento Bridge

Task Management via Ports and Adapters

TypeScript Things CLI via joelclaw Tasks Subcommand

Todoist as Async Conversation Channel

Webhook Gateway for External Service Integration

Gateway TUI via WebSocket

Gateway session resume via fixed file path and codex model pinning

Two operational issues were discovered simultaneously:

Tailscale Funnel as Public Ingress for Webhooks

Email Port — Hexagonal Architecture with Dual Adapters

Event-emitter prompts and the Agency triage principle

The gateway extension delivers Inngest events to the pi session as user messages. Previously, ALL events were wrapped in a generic template:

Granola Meeting Intelligence Pipeline

Skill Pack Distribution — Install from Source

58. Streamed NDJSON Protocol for Agent-First CLIs

Client-Side Search with Pagefind

joelclaw.com has ~80 pages of content (10 articles, 63 ADRs, 7 discoveries) with no search. Users can only browse by section (Writing, Cool, ADRs, Network) or scroll through listings. As the site g…

Friction auto-fix — bias towards action

ADR-0021 Phase 4 (Friction) detects recurring friction patterns from Qdrant observations and creates Todoist tasks for Joel to review. The pipeline works — 10 patterns detected on first successful …

Inngest Monitor Pi Extension

Integrate Community Skill Patterns

Memory Proposal Auto-Triage Pipeline

Gateway Proactive Telegram Notifications

Telegram Rich Notifications with Inline Keyboards

Notification Triage Classes

Memory System — Next Phase

Opus Token Reduction Across joelclaw

Telnyx Voice & SMS Notification Channel

Vault File Access from Voice Mode

Vault CLI & Agent Tool Access

Typesense as Unified Search Layer for the JoelClaw Network

Unified Content Resource Schema (Convex)

Data-Driven Network Page via Convex

Telegram Slash Commands, Channel-Aware Formatting, and Rich Interactions

Full-Stack Observability + JoelClaw Design System

NAS-Backed Storage Tiering

Single-Source Inngest Worker Deployment (Retire Dual-Clone Sync)

Autonomous O11y Triage Loop

Gateway Model Fallback

Agent-Friendly Navigation Contract (AGENT-FIRST 30)

Gateway Session Isolation — No Background Work in the Pi Session

Next.js Best Practices Audit

Standardize page-level status indicator styling

X/Twitter CLI Integration

Discord Thread-Based Conversations

iMessage Channel via imsg-rpc FDA Sidecar on macOS

Request-Scoped Channel Routing

Discord Rich UI Component Library

Feed Subscriptions & Resource Monitoring

Automated X Posting Strategy

Slack Channel Integration

Unified Channel Intelligence Pipeline

Contact Enrichment Pipeline

System Sleep Mode

Codex Prompting Skill Router for Intent-to-Tool Delegation

Self-Healing NAS Backup Orchestrator

One place to pick and trace LLM models

joelclaw currently routes LLM calls through multiple incompatible paths:

Gateway context overflow auto-recovery with compression summary

On 2026-02-25, the gateway daemon became completely unresponsive via Telegram for hours. Every inbound message was received, persisted to the Redis stream, and "resolved" (acked) — but the actual A…

AST-Based Message Formatting via unified/remark

Gateway Hexagonal Architecture (Ports & Adapters)

Inference Cost Monitoring and Control

Named Agent Profiles for Specialized Inference

Docs REST HTTP API for Agent Access (Typesense-backed)

Three-Stage Story Pipeline: Implement → Prove → Judge

Talon — Infrastructure Watchdog Daemon

Telegram Streaming UX

Adaptive Prompt Architecture

Codex Sandbox + CWD Policy

Convex-Canonical Content Lifecycle (No Repo MDX Sources)

CLI Capability Interface Contracts

Agent Role System (ROLE.md)

Custom System Prompt Architecture

Agent Mail via MCP Agent Mail

ADR Number Collision Remediation

Vault Command Tree + ADR Audit CLI

JoelClaw Design System — Responsive Layout & Component Architecture

Transcript Indexing in Typesense

Automated Skill Gardening

Configurable Sub-Agent Roster

Node-0 Fleet Contract and Localhost Resilience

Gateway Guardrails

Cancel-on-New-Message for Gateway

Sub-Agent Delegation via step.invoke()

Adaptive Heartbeat — Check Cheaply, Act Rarely

Close the Loop — Reflect Brain, Failed Targets, and Mise Brief

joelclaw has extensive infrastructure for agent loops (Inngest, Redis, OTEL, Typesense) and well-specified designs for post-loop learning (ADR-0008), memory (ADR-0021), and friction auto-fix (ADR-0…

Force/Enforce/Verify (F/E/V) — Standard Pattern for Cross-Cutting Concerns

Workflow Runtime Deployment Strategy + Runtime Alternatives Research Plan

Turn-Level Mandatory Knowledge Writes (Force/Enforce/Verify)

Cloud-Native Agent Execution Vision

joelclaw currently runs on a single Mac Mini (M4 Pro, 64GB). Agent execution (Codex, Claude, and pi sessions) happens as local host processes with broad machine access. ADR-0060 introduces a swarm …

Hot Image Agent Development Environments

ADR-0205 defines the cloud-native direction for agent execution: isolated, durable, and fast-starting agent runtimes that map local k8s to AWS primitives.

Restate Durable Execution Engine

joelclaw currently runs 110+ durable functions on self-hosted Inngest (k8s StatefulSet). It works, but reliability has felt flaky and operational confidence is lower than desired for increasingly c…

S3-First Storage Migration

Channel Intelligence Pipeline

Joel's inbound channels — email, Slack, Discord, iMessage, Telegram — are all signal sources with the same problem: important messages get buried, replies slip, relationships suffer. The system cur…

Gateway Behavior Control Plane

Gateway behavior quality is currently inconsistent in how it is preserved and applied. When behavior is good (tight check-ins, low-noise heartbeats, good delegation cadence), there is no determinis…

AIStor as Local S3 Runtime

ADR-0208 selected MinIO OSS as the local S3-compatible runtime. Upstream MinIO OSS moved to source-only maintenance mode and then no-longer-maintained + archived state. Relying on an archived runti…

Gateway Session Lifecycle Guards

Gateway Redis-Degraded Operation Mode

Telegram Callback Routing via Gateway

Dkron Distributed Scheduler for Restate DAG Pipelines

The joelclaw system currently uses self-hosted Inngest for both scheduling (cron triggers, event triggers) and durable execution (step functions, retries). Operational data from 20 days of slog ent…

Agent-First Event-Driven Workflows

Gateway Availability, Lifecycle, and Operator QoL Improvements

The gateway has improved quickly, but the last week of actual usage showed the same ugly failure classes repeating:

Restate Agent Runtime with Flue-Inspired Proxy Policies

pi-mono Artifacts Corpus via Restate + Typesense

We keep learning the same upstream lesson with `badlogic/pi-mono`: maintainer voice, review heuristics, issue-first contributor gate, common rejection patterns, release velocity, and package-bounda…

Local Sandbox Isolation Primitives

joelclaw already proved the **local host-worker sandbox runner** is a viable phase-1 isolation surface, but the current substrate is still thinner than it should be for serious local parallel work.

Prompt-Layer Role Matrix and Session Handles

Multi-Venue Publishing Lifecycle and Canonical Ownership

joelclaw grew up with one obvious public venue: `joelclaw.com`.

Site-Aware Content Routing and Sync Contract

ADR-0223 made venue selection explicit at the operator layer.

Conversation Annotation Pipeline