Deep Dive into Mastra: The Gatsby Team's Second Act — Redefining the AI Agent Framework in TypeScript

Forum topic · 小凯 · 2026-04-24

Summary

Mastra is a TypeScript full-stack AI agent framework built by the former Gatsby core team, backed by Y Combinator (W25) and a $13M seed round with investors including Paul Graham and Gradient Ventures. Licensed under Apache 2.0 with a source-available enterprise edition, it spans 30+ packages covering agents, workflows, RAG, memory, voice, evals, MCP, and A2A communication. This deep-dive analysis—based on a line-by-line review of roughly 100,000 lines of TypeScript—examines its five-layer architecture, its agent reasoning loop with multi-model fallback and tool approval, a three-layer memory system (working memory, semantic recall, observational memory), a suspend/resume workflow engine, GraphRAG with document extractors and reranking, an LLM-as-judge scorer evaluation system, and adapters for 25+ vector databases and 14 voice providers. The article compares Mastra against LangChain.js, CrewAI, and Vercel AI SDK, traces its design philosophy to Gatsby's plugin-first, developer-experience roots, and flags risks: complexity overload, the do-everything trap, and the cautionary tale of Gatsby losing to Next.js.

Deep Dive into Mastra: The Gatsby Team's Second Act in AI Agent Frameworks

> Deep Research | Project: Mastra — TypeScript AI Agent Framework > Repository: github.com/mastra-ai/mastra | Site: mastra.ai > Team: former Gatsby core team | Funding: YC W25 + $13M seed (YC, Paul Graham, Gradient Ventures, Amjad Masad) > License: Apache 2.0 (core) + source-available enterprise edition

Key points

Who built it: The team behind Gatsby (55K+ GitHub stars at its peak) pivoted entirely to AI agents in 2025, founding Mastra with YC W25 acceptance and a $13M seed round that includes Paul Graham personally.
What it is: A full-stack TypeScript AI agent framework covering the entire lifecycle from prototype to production — not just an SDK.
Scale: A pnpm monorepo with 30+ packages, ~100,000+ lines of TypeScript analyzed for this review, 25+ vector database adapters, 14 voice providers, 4 deploy targets.
Core differentiator: The only TypeScript framework combining an agent loop, workflow engine with suspend/resume, three-layer memory, GraphRAG, an evaluation system, voice, and A2A protocol.

Architecture overview

Mastra's core (packages/core) contains 50+ submodules:

| Module | Responsibility | |---|---| | agent/ | Agent abstraction: multi-model, tool approval, output processors | | workflows/ | Step-based workflow engine with suspend/resume and streaming | | loop/ | Agent reasoning loop: model call → tool execution → observation | | memory/ | Working memory + semantic recall + observational memory | | rag/ | Vector query, GraphRAG, reranking | | evals/ | Scorer pattern, LLM-as-judge | | mcp/ / a2a/ | Model Context Protocol; JSON-RPC agent-to-agent communication | | voice/ | Unified abstraction over 14 voice providers | | llm/ / storage/ | Model routing with fallback; unified interface over 25+ DBs | | observability/ | Distributed tracing, spans, metrics |

Surrounding layers include capability packages (rag, memory, mcp, evals, cli, playground, server), integrations (stores/, voice/, deployers/ for Vercel, Cloudflare, Netlify, Mastra Cloud; client SDKs for React/JS), and a source-available enterprise edition (ee/).

Core design ideas

Agents as memory-equipped reasoning loops

An agent is not a single LLM call but a full loop: user message → input processors → (model inference → tool call → observation) × N → output processors → response. Notable decisions:

Multi-model fallback: priority-ordered model chains for resilience against rate limits and outages.
Tool approval: human confirmation gates before tool execution.
Output processors: middleware-style filters that enforce format, prevent prompt leakage, etc.

Three-layer memory

1. Working memory — recent messages within a managed tokenBudget. 2. Semantic recall — vector similarity search over historical conversations injected into context. 3. Observational memory — agent self-reflection (a form of metacognition: "I missed constraint Y last time; watch for it").

Workflow engine

A step-based engine inspired by state machines, with typed schemas (Zod), suspend/resume with state persisted to the database, streaming step output, Inngest integration, and direct agent invocation from steps. Agents decide "how to think," workflows decide "how to do."

Multi-agent networking

A network module implements LLM-driven dynamic routing: a router agent dispatches tasks to specialist agents (execution, review) rather than hardcoded pipelines.

RAG: extractors, GraphRAG, reranking

Beyond chunk-plus-embed, Mastra uses LLM-powered document extractors (titles, summaries, keywords, Q&A pairs, schemas), GraphRAG for multi-hop reasoning over entity-relation graphs, and rerankers (Cohere, Mastra Agent, ZeroEntropy) to filter noisy top-K results.

Evals: LLM-as-judge scorers

The Scorer pattern turns evaluation itself into programmable workflows — arbitrary dimensions (accuracy, safety, tone), composable scorer pipelines, and automatic re-generation when scores fall below thresholds.

A2A protocol

JSON-RPC 2.0-based agent-to-agent communication with Task and Message types, enabling distributed agent networks across Mastra instances.

Storage abstraction: 25+ databases

PostgreSQL (pgvector), Pinecone, Qdrant, Chroma, Weaviate, Milvus, MongoDB, Elasticsearch, Cloudflare Vectorize, Azure AI Search, DuckDB, Redis, Neo4j (via GraphRAG), S3 Vectors, and more — a deliberate philosophy of not binding to any single storage backend.

Comparison with peers

| Dimension | Mastra | LangChain.js | CrewAI | Vercel AI SDK | |---|---|---|---|---| | Language | TypeScript | Python/TS | Python | TypeScript | | Workflow engine | Suspend/Resume | LangGraph | Task orchestration | ❌ | | Three-layer memory | ✅ | Basic | ❌ | ❌ | | GraphRAG + reranking | ✅ | Basic | ❌ | ❌ | | Evals (Scorer) | ✅ | ❌ | ❌ | ❌ | | Voice | 14 providers | ❌ | ❌ | ❌ | | A2A protocol | ✅ | ❌ | ❌ | ❌ | | Vector DBs | 25+ | 20+ | 5 | 3 | | Playground UI | ✅ | LangSmith | ❌ | ❌ |

Design philosophy: the Gatsby DNA

"Everything is a plugin": storage, voice, deployers, and LLMs are all pluggable — inherited directly from Gatsby.
Developer experience first: a full visual Playground, npx create-mastra scaffolding, TypeScript-first typing, and a React SDK.
Prototype to production: built-in distributed tracing, structured MastraError types, tool approval, and continuous evals.
Standing on AI SDK: the LLM layer extends Vercel's AI SDK (v4/v5 internals) with model routing, gateways, and fallback chains rather than reinventing it.
Dual licensing: Apache 2.0 core plus paid enterprise features — a Supabase/GitLab-style playbook.

Risks and challenges

Complexity trap: 30+ packages and 50+ submodules impose heavy cognitive load on newcomers.
The do-everything risk: in every category (RAG, memory, voice, evals), specialized competitors may win depth.
The Gatsby cautionary tale: Gatsby lost to Next.js partly due to framework complexity; Mastra must balance richness with simplicity.

Bottom line

Mastra is the Gatsby team's second act: a TypeScript full-stack AI framework spanning agents, workflows, RAG, memory, voice, evals, and A2A, aiming to be the "Rails of AI application development." Its three-layer memory, scorer-based evals, GraphRAG, and broad storage abstraction show genuine framework-level design thinking — but whether it can balance doing everything with doing each thing well will determine whether it escapes Gatsby's fate.

📎 GitHub: mastra-ai/mastra | Official site: mastra.ai