When you run AI agents day to day, there are moments when you want a short answer to questions like: what just happened, which checkpoint was updated, did the health check pass, or which task failed?
The risky version of that idea is to save everything: full logs, full conversations, draft text, URLs, tokens, and whatever else happened to pass through the process. That is exactly what I wanted to avoid. So I built agent-flight-recorder-mini.
What this project does
agent-flight-recorder-mini is a small Cloudflare Workers-based flight recorder for local agent tools. It stores short, redacted state events, not transcripts.
- heartbeat events
- checkpoint updates
- smoke test results
- manual state events
- task failure records
The goal is to keep enough operational context to understand the state of an agent run, while deliberately avoiding raw logs, conversation bodies, Discord message bodies, X draft text, article bodies, authentication URLs, raw session IDs, cookies, API keys, and other private material.
Architecture
The first deployment target is Cloudflare Workers. The architecture is intentionally small.
- Worker: JSON API
- D1: searchable metadata, body excerpt, and R2 object key
- R2: raw redacted JSON payloads
- ADMIN_TOKEN: project-specific Worker secret
- Public endpoint: only GET /health
The initial setup does not require DNS routes, Cloudflare Tunnel, Zero Trust, Cron, Workers AI, or production site changes. Those are separate decisions for later. The first version is only about recording safe state events.
API shape
The API is limited to health checks, event creation, and event lookup.
GET /health
POST /events
GET /events
GET /events/:id
GET /events/:id/rawGET /health is public and only reports whether the D1 and R2 bindings are present. The other endpoints require the admin token.
POST /events accepts fields such as source, event_type, severity, actor, task_id, summary, tags, and metadata. Searchable fields go into D1. The raw redacted JSON payload goes into R2.
Dedupe for retries
Agent integrations often retry after a timeout or temporary failure. Without idempotency, the same logical event can be written multiple times, which makes later inspection noisy.
To handle that, agent-flight-recorder-mini supports an optional dedupe_key. If the same agent, source, event_type, task, and dedupe_key already exist, the Worker returns the existing event instead of writing a new D1 row and R2 object.
That makes retry and spool replay safer: the same logical event remains a single record.
The most important feature is what it refuses to store
This project is not a general-purpose log dump. The core design rule is simple: send state, not content.
- Do not send ADMIN_TOKEN, API keys, cookies, or bearer tokens.
- Do not send .env or .dev.vars contents.
- Do not send authentication URLs, webhook URLs, or private URLs.
- Do not send raw session IDs.
- Do not send full conversations, full post bodies, or long logs.
- Do not send personal information or private profile URLs.
Before an event is sent, it should be reduced to a short summary and redacted. Events marked contains_secret: true are rejected by the client path. If redaction fails, the parent task should continue, and only the flight recorder send should be skipped.
Local client wrappers
The repository includes small shell wrappers for local use. They are thin by design.
- a generic flightlog-send.sh client
- a manual event wrapper
- a Codex checkpoint wrapper
- a Hermes heartbeat wrapper
- an OpenClaw heartbeat wrapper
- an operator wrapper for routine checks
The wrappers support dry runs, explicit staging confirmation, redaction checks, and secret-safe prompts. Automatic hooks are best effort: a recorder failure should not break the parent agent process.
Retry and local spool
Retry behavior is intentionally bounded. The initial policy uses three attempts with exponential backoff: 1 second, 2 seconds, and 4 seconds, plus small jitter.
If sending still fails, the client can write a redacted payload to a local spool directory. The spool is only for payloads that have already passed redaction. A payload that may still contain secrets should not be spooled.
Pre-publication checks
The project is being prepared as a possible public OSS release. Before making it public, the repository should pass the publication checklist and a human should explicitly approve the visibility change.
The publication check runs Worker syntax validation, the dedupe test, shell script syntax checks, and a publication marker scan. GitHub Actions can run the same checks without requiring Cloudflare credentials or local secrets.
Summary
agent-flight-recorder-mini is not meant to be a large observability platform. It is a small operational memory for AI agents.
The main idea is not to save everything. The main idea is to save only the small state records that are safe and useful. That constraint makes the resulting history easier to inspect, and it reduces the chance of accidentally collecting secrets or private content.
superdoccimo/agent-flight-recorder-mini
