MYND Agent Replay

Black Box Flight Recorder for AI Agents — Replay Any Decision, Any Action, Any Moment

Overview • Features • Tech Stack • Architecture • Quick Start • MYND Ecosystem • Deployment

Overview

MYND Agent Replay is the world's first full-fidelity recording, replay, and time-travel debugging platform for AI agent execution traces. Like a black box flight recorder for aircraft, Agent Replay captures every LLM call, tool invocation, state mutation, and decision point with nanosecond-precision timestamps — enabling developers to replay, inspect, and debug any agent session frame by frame.

Built on SvelteKit, Fastify, PostgreSQL with TimescaleDB time-series optimization, and Redis-backed job queues (BullMQ), Agent Replay is production-ready infrastructure for teams building and operating autonomous AI agents at scale.

Features

Full Fidelity Recording

• Capture every LLM call, tool invocation, and state change with complete context preservation
• Automatic buffering and batching for high-throughput agent sessions
• Structured event logging with typed schemas via Zod
• Nanosecond-precision timestamps for accurate replay ordering

Time-Travel Debugging

• Frame-by-frame inspection of agent execution
• Jump to any point in time within a session
• State diff visualization between execution steps
• Variable inspection at every decision point

Session Analytics

• Chart.js + svelte-chartjs visualizations for token usage, latency, error rates
• Session timeline with bottleneck identification
• Error clustering and failure pattern detection
• Export sessions for offline analysis

Enterprise Infrastructure

• BullMQ job queue for async event processing
• Redis caching for fast session retrieval
• PostgreSQL with TimescaleDB for time-series optimization
• Stripe integration for metered billing
• Fastify Swagger/OpenAPI documentation
• Rate limiting and OAuth2 authentication

Tech Stack

Layer	Technology	Purpose
Frontend	SvelteKit 2, Svelte 5, TypeScript	Reactive debugger UI with SSR
Charts	Chart.js, svelte-chartjs	Interactive session visualizations
Icons	Lucide Svelte	Consistent icon system
Styling	Tailwind CSS, PostCSS, Autoprefixer	Utility-first design
Build Tool	Vite	Fast HMR and production builds
Backend	Node.js, Fastify 4, TypeScript	High-performance API server
API Docs	@fastify/swagger, @fastify/swagger-ui	Auto-generated OpenAPI docs
Auth	@fastify/jwt, @fastify/oauth2	Enterprise authentication
Queue	BullMQ	Async event processing jobs
Database	PostgreSQL 16, pg	Primary relational store
Time-Series	TimescaleDB	Optimized time-series queries
Query Builder	Kysely	Type-safe SQL query builder
Cache	Redis (ioredis)	Session cache and queue backend
Payments	Stripe	Usage-based billing integration
Testing	Jest, ESLint, Prettier	Code quality and testing
Monorepo	npm workspaces (packages/)	Shared types between frontend/backend

Architecture

┌─────────────────────────────────────────────────────────┐
│            SvelteKit Frontend (Debugger UI)              │
│  Timeline │ Frame Inspector │ State Diff │ Charts       │
│  ─────────────────────────────────────────────────────  │
│              WebSocket for live replay streaming         │
└──────────────────────────┬──────────────────────────────┘
                           │ REST + WebSocket
┌──────────────────────────▼──────────────────────────────┐
│             Fastify Backend (Replay Engine)              │
│  Session API │ Event Ingest │ Replay Controller        │
│  Swagger Docs │ Auth │ Rate Limit │ Queue Producer     │
└───────┬──────────────────────┬──────────────────────────┘
        │                      │
   ┌────▼────┐           ┌─────▼──────┐
   │ BullMQ  │           │  Redis     │
   │ Queue   │           │  Cache     │
   └────┬────┘           └────────────┘
        │ Async processing
┌───────▼─────────────────────────────────────────────────┐
│           PostgreSQL + TimescaleDB                       │
│  sessions │ events │ frames │ state_snapshots │ llm_calls│
│  ─────────────────────────────────────────────────────  │
│        Hypertable partitioning for time-series queries   │
└─────────────────────────────────────────────────────────┘

Quick Start

Prerequisites

• Node.js 20+
• PostgreSQL 16+ with TimescaleDB extension
• Redis 7+

Installation

# Clone the repository
git clone https://github.com/yethikrishna/mynd-agent-replay.git
cd mynd-agent-replay

# Install all dependencies
npm install

# Configure environment
cp .env.example .env
# Configure DATABASE_URL, REDIS_URL, JWT_SECRET, etc.

# Start development (frontend + backend)
npm run dev

# Frontend: http://localhost:5173
# Backend:  http://localhost:3000

# Run tests
npm test

# Lint
npm run lint

Docker

# Start PostgreSQL, Redis, and application
npm run docker:up

# Build all containers
npm run docker:build

Project Structure

mynd-agent-replay/
├── packages/
│   ├── backend/            # Fastify API server
│   │   ├── src/
│   │   │   ├── routes/    # REST API (sessions, events, replay)
│   │   │   ├── queues/    # BullMQ job definitions
│   │   │   ├── services/  # Replay engine, event processing
│   │   │   └── index.ts
│   │   └── package.json
│   ├── frontend/           # SvelteKit debugger application
│   │   ├── src/
│   │   │   ├── routes/    # SvelteKit file-based routing
│   │   │   ├── lib/       # Components, stores, utilities
│   │   │   └── app.html
│   │   └── package.json
│   └── shared/            # Shared TypeScript types and Zod schemas
│       └── src/
├── docker/                # Docker configuration files
├── docker-compose.yml
├── tsconfig.json          # Root TypeScript config
└── package.json

Environment Variables

# Server
NODE_ENV=development
PORT=3000
API_URL=http://localhost:3000
APP_URL=http://localhost:5173
CORS_ORIGINS=http://localhost:5173,http://localhost:3000

# JWT Authentication
JWT_SECRET=your-super-secret-jwt-key-change-in-production
JWT_EXPIRES_IN=7d

# Database (PostgreSQL with TimescaleDB)
DATABASE_URL=postgresql://mynd:mynd_password@localhost:5432/mynd_replay

# Redis
REDIS_URL=redis://localhost:6379

# Stripe (optional, for billing)
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

MYND Ecosystem

MYND Agent Replay is part of the MYND AI Agent Platform:

Project	Purpose
mynd-platform	Core platform: GUI automation, memory, multi-agent orchestration
mynd-synchron	Cross-application context synchronizer
mynd-agent-replay	Black box flight recorder (this repo)
mynd-model-arena	LLM evolutionary benchmarking platform
mynd-plan	AI product-navigator agent
mynd-skill-forge	AI skill creation platform

Deployment

# Production Docker deployment
npm run docker:build
npm run docker:up

For production, we recommend:

• Managed PostgreSQL with TimescaleDB (Timescale Cloud, AWS RDS + extension)
• Managed Redis (Upstash, AWS ElastiCache)
• Reverse proxy with Nginx/Caddy for TLS termination
• Separate BullMQ workers for high-volume event ingestion

Contributing

1. Fork and create a feature branch
2. Ensure npm run lint and npm test pass
3. Submit a PR with detailed description

License

MIT License.

---

_{Every decision recorded. Every action replayable. Every bug traceable.}