Mastra

Mastra AI Framework Guide

Build AI applications with Mastra. This skill teaches you how to find current documentation and build agents and workflows.

⚠️ Critical: Do Not Trust Internal Knowledge

Everything you know about Mastra is likely outdated or wrong.

Your training data contains obsolete APIs, deprecated patterns, and incorrect usage. Mastra evolves rapidly - APIs change between versions, constructor signatures shift, and patterns get refactored.

Never rely on memory. Always verify against current documentation.

Prerequisites

Before writing any Mastra code, check if packages are installed:

ls node_modules/@mastra/

• If packages exist: Use embedded docs first (most reliable)
• If no packages: Install first or use remote docs

Documentation Lookup Guide

Quick Reference

Priority Order for Writing Code

1. Embedded Docs First (if packages installed) ⭐

# Check what's available
cat node_modules/@mastra/core/dist/docs/SOURCE_MAP.json | grep '"Agent"'

# Read the actual type definition
cat node_modules/@mastra/core/dist/[path-from-source-map]

• Why: Matches your EXACT installed version
• Most reliable source of truth
• See: references/embedded-docs.md

2. Remote Docs Second (if packages not installed)

# Fetch latest docs
# https://mastra.ai/llms.txt

• Why: Latest published docs (may be ahead of installed version)
• Use when: Packages not installed or exploring new features
• See: references/remote-docs.md

⚠️ Never write code without checking current docs first

Core Concepts

Agents vs Workflows

Agent = Autonomous, makes decisions, uses tools Use for: Open-ended tasks (support, research, analysis)

Workflow = Structured sequence of steps Use for: Defined processes (pipelines, approvals, ETL)

Key Components

• Tools: Extend agent capabilities (APIs, databases, external services)
• Memory: Maintain context (message history, working memory, semantic recall)
• RAG: Query external knowledge (vector stores, graph relationships)
• Storage: Persist data (Postgres, LibSQL, MongoDB)

Critical Requirements

TypeScript Config

Mastra requires ES2022 modules. CommonJS will fail.

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler"
  }
}

Model Format

Always use "provider/model-name":

• "openai/gpt-4o"
• "anthropic/claude-3-5-sonnet-20241022"
• "google/gemini-2.5-pro"

When You See Errors

Type errors often mean your knowledge is outdated.

Common signs of outdated knowledge:

• Property X does not exist on type Y
• Cannot find module
• Type mismatch errors
• Constructor parameter errors

What to do:

1. Check references/common-errors.md
2. Verify current API in embedded docs
3. Don't assume the error is a user mistake - it might be your outdated knowledge

Development Workflow

Always verify before writing code:

1. Check packages installed

   ls node_modules/@mastra/
   

2. Look up current API

   • If installed → Use embedded docs references/embedded-docs.md
   • If not → Use remote docs references/remote-docs.md

3. Write code based on current docs

4. Test in Studio

   npm run dev  # http://localhost:4111
   

Resources

• Setup: references/create-mastra.md
• Embedded docs lookup: references/embedded-docs.md ⭐ Start here
• Remote docs lookup: references/remote-docs.md
• Common errors: references/common-errors.md
• Migrations: references/migration-guide.md
• Official site: https://mastra.ai (verify against embedded docs first)
• Examples: https://github.com/mastra-ai/mastra/tree/main/examples (may be outdated)