mastra-system-check: Instructions file for Codex

Mastra System Check - Comprehensive Guide

This document contains all 66 rules for validating Mastra AI agent projects. Rules are organized by category and priority level.

Priority Levels

Level	Impact	Action
CRITICAL	System won't function	Must fix immediately
HIGH	Major functionality issues	Fix before deployment
MEDIUM	Quality/maintainability	Fix when possible
LOW	Performance/cost optimization	Nice to have

---

Section 1: Configuration & Setup (CRITICAL)

Core configuration checks that prevent system failures.

1.1 Storage Provider Required

Impact: CRITICAL (Memory, workflows, and traces won't persist)

Mastra requires a storage provider for memory persistence, workflow state, suspended tool calls, and observability traces. Without storage, conversations lose context between requests and workflows cannot suspend/resume.

What to Check

• Storage provider is configured in Mastra instance
• Storage URL is valid (not empty or undefined)
• Storage is accessible at runtime

Incorrect Configuration

// Missing storage - memory and workflows will fail
import { Mastra } from "@mastra/core";

export const mastra = new Mastra({
  agents: { myAgent },
  // No storage configured!
});

Correct Configuration

import { Mastra } from "@mastra/core";
import { LibSQLStore } from "@mastra/libsql";

export const mastra = new Mastra({
  storage: new LibSQLStore({
    id: "mastra-storage",
    url: process.env.DATABASE_URL || "file:./mastra.db",
  }),
  agents: { myAgent },
});

How to Fix

1. Install a storage package: pnpm add @mastra/libsql@latest
2. Import and configure the storage provider
3. Set DATABASE_URL in your .env file for production
4. For development, use file:./mastra.db or :memory:

---

1.2 Environment Variables Required

Impact: CRITICAL (API calls fail, system non-functional)

Mastra agents require API keys for LLM providers. Missing environment variables cause runtime failures when agents try to generate responses.