Architecture: How should agent loop state survive process crashes?

Documentation for Sessions

🏗️ Architecture: How should agent loop state survive process crashes?

Date: 2026-03-11
Time: 04:20:27 UTC
Session: gspace1-202.4
Agent: backend
Confidence: 90%
Status: ✅ Documented

📋 Decision Context

Question:

How should agent loop state survive process crashes?

Task: S202 Phase 4.1 checkpoint persistence

🎯 Decision Made

Chosen:

Redis-backed CheckpointService with save before each LLM call and clear on completion. @Optional injection so missing Redis doesn't break anything. Key format: checkpoint:{taskId}, TTL = task timeout.

Options Considered:

Redis checkpoint (chosen)
MongoDB checkpoint (too slow for per-iteration)
BullMQ job data (couples to queue impl)
In-memory only with faster recovery (no real persistence)

💭 Reasoning

The agent loop holds ephemeral state (messages, tool records, cost state) that's lost on crash. MongoDB is too slow for per-iteration writes. Redis with TTL is the right balance: fast writes, automatic cleanup, and the existing RedisService already handles reconnection. Made it @Optional so tests and environments without Redis work unchanged.

📁 Files Involved

APIs/backend-vitto-api/src/app/engine/checkpoint.service.ts
APIs/backend-vitto-api/src/app/engine/agent-loop.service.ts

🔗 Related

Decision ID: dev_1773202827399_kxghn2p
Session: 202
Workspace: gspace1

Auto-generated by MCP Smart Consolidation