Mastra Codebase — Monorepo AI Framework

⚠️ HISTORICAL / PARTIALLY STALE (flagged 2026-07-02). The bulk of this shard describes a vendored ddx-mastra-codebase/ monorepo checkout and a standalone ddx-tucan-engine service — both are gone. ddx-tucan-engine was parked to _claude-archive/parked-2026-06-14/dead-code-twins/ddx-tucan-engine (its runtime folded into ddx-api/src/ai/tucan), and no ddx-mastra-codebase/ tree exists on disk. Treat the version-matrix, path index, and "refresh script" sections below as a snapshot of an earlier layout — the authoritative facts are in the corrected header immediately below. Do NOT cite the line-referenced paths (ddx-mastra-codebase/…, ddx-tucan-engine/…, ddx-livekit-flowagent-ts/…) as live.

Mastra is consumed as an npm dependency, not a vendored source tree. The runtime version production uses is @mastra/core@^1.37.1 (ddx-api, resolved at 1.37.1) and 1.20.0 (the FlowAgent voice worker at ddx-livekit-agents-ts/agents/flowagent). ddx-web pins its own copy (1.24.1) for the Phoenix agent. The mastra docs/migration MCP (mcp__mastra__*) is the version-accurate reference surface — there is no ddx-mastra-codebase/ monorepo checkout on disk anymore.

Drift note (2026-07): an earlier revision of this shard claimed a vendored ddx-mastra-codebase/ reference tree and @mastra/core@^1.28.0; both are stale. Verify the live version from ddx-api/node_modules/@mastra/core/package.json before trusting any version claim — ddx-api/CLAUDE.md still says "Mastra 1.5.0" and is wrong.

Business Purpose

TUCAN's reliability depends on understanding Mastra primitives in depth — Agent, Workflow, createStep, suspend/resume, RuntimeContext, extractReasoningMiddleware, generateText vs streamText, the network agent shape, memory, tool registration. When something behaves unexpectedly (e.g. extractReasoningMiddleware({tagName:'think'}) not parsing a Gemma "Thinking process:\n" prefix — [[ddx-mastra-specialist_memory.md]]), the answer is in the Mastra source, not in the npm docs.

Having the full Mastra monorepo on disk:

1. Makes rag-sidecar / rg searches authoritative — we read the actual code that ships in node_modules.
2. Lets us patch Mastra locally via patches/ if a release blocker needs a fix before upstream merges it.
3. Documents the alignment between ddx-api's Mastra version and the reference monorepo (which moves faster than our pinned version).

It is not a fork we deploy from — node_modules/@mastra/* resolves to npm, not to this directory.

Audiences

• Developer / partner: Reading ddx-mastra-codebase/packages/core/src/agent/index.ts is the fastest way to understand what new Agent({...}) actually does. Same for packages/core/src/workflows/workflow.ts.
• Internal: This is the upgrade-readiness check. When we plan to bump @mastra/core@1.28.0 → 1.x, we diff this tree against the latest tag to spot breaking changes early.
• Investor (only relevant if asked): We use the framework we're literate in. We have the source on disk so we never black-box critical infrastructure.

Architecture

The tree under ddx-mastra-codebase/ is the upstream Mastra monorepo, pulled by PULL_LATEST.sh. Top-level subdirectories present on disk (verified 2026-05-18):

ddx-mastra-codebase/
├── auth/                   Auth examples / integrations
├── browser/                Browser SDK
├── client-sdks/            Per-language client SDKs
├── communications/         Email / chat / phone integrations
├── deployers/              Cloud deploy adapters (Vercel, Cloudflare, …)
├── docs/                   Mastra docs source
├── e2e-tests/              End-to-end test harness
├── ee/                     Enterprise edition packages
├── examples/               Reference examples (THE most useful folder)
├── explorations/           Experimental research
├── integrations/           First-party integrations (LiveKit, Slack, …)
├── mastracode/             Code-generation tooling
├── observability/          OTel / Datadog / etc. adapters
├── packages/               THE CORE PACKAGES — @mastra/core, /memory, /pg, /evals, …
├── patches/                Local patches
├── pubsub/                 Pub/sub utilities
├── AGENTS.md               Mastra's own AI-rules file
├── CLAUDE.md               Pointer to AGENTS.md
├── PULL_LATEST.sh          Refresh script
├── package.json, pnpm-workspace.yaml

The packages/ directory is the practical surface for TUCAN — it holds @mastra/core (Agent, Workflow, createStep), @mastra/memory (thread + resource memory), @mastra/pg (Postgres-backed memory), @mastra/evals (eval harness), @mastra/observability (OTel wiring).

Pinned Mastra versions across the platform

(All values verified 2026-05-18 against the on-disk package.json files.)

Drift note: Project memory shard MEMORY_TUCAN_AI (last updated 2026-04-24) records "@mastra/core@1.13.0"; the on-disk truth is 1.28.0 on ddx-api/ddx-tucan-engine and 1.20.0 on the LiveKit FlowAgent service. The memory is stale; verify against package.json before quoting a version externally.

Tech Stack & Choices

Alternatives rejected:

• Reading Mastra docs only — docs lag the code; we found multiple cases where the README didn't match 1.13 shipped behavior. The vendored source is truth.
• Forking Mastra — overhead of maintaining a fork; we want upstream's bug fixes for free.
• Pinning all three services to the same Mastra version — forces lockstep upgrades. The current split lets us de-risk per service.

Data Flow

Business outcome: Developer hits a "step suspend() is not resuming with the new payload" bug. Within 5 minutes they have a root cause from reading ddx-mastra-codebase/packages/core/src/workflows/run.ts.

Technical mechanism:

1. Run rag_code_search (semantic) or rg -n 'resumeData' over ddx-mastra-codebase/packages/core/src/workflows/.
2. Read the actual run.resume({ step, resumeData }) impl; confirm it calls step.execute({ resumeData }) and the step's inputSchema parses the payload.
3. Cross-check against our chat-orchestrator.service.ts:267 site; spot that we pass the full ResumeDecision instead of the step's input shape.
4. Fix our side; no patch to Mastra needed.

Implicated Code

• ddx-mastra-codebase/package.json:1 — workspace root.
• ddx-mastra-codebase/pnpm-workspace.yaml — pnpm workspace declaration.
• ddx-mastra-codebase/PULL_LATEST.sh:1 — refresh script.
• ddx-mastra-codebase/packages/ — @mastra/core, @mastra/memory, @mastra/pg, @mastra/evals, @mastra/observability packages.
• ddx-mastra-codebase/examples/ — reference implementations.
• ddx-mastra-codebase/integrations/ — first-party integrations.
• ddx-mastra-codebase/observability/ — OTel adapters.
• ddx-mastra-codebase/patches/ — local patches.
• ddx-mastra-codebase/AGENTS.md:1 — Mastra's own AI rules.
• ddx-mastra-codebase/CLAUDE.md:1 — pointer to AGENTS.md.
• ddx-api/package.json:81 — @mastra/core@^1.28.0.
• ddx-api/package.json:82 — @mastra/evals@^1.2.1.
• ddx-api/package.json:83 — @mastra/memory@^1.17.1.
• ddx-api/package.json:84 — @mastra/observability@^1.10.0.
• ddx-api/package.json:85 — @mastra/pg@^1.9.2.
• ddx-tucan-engine/package.json:50 — @mastra/core@^1.28.0.
• ddx-tucan-engine/package.json:51 — @mastra/memory@^1.17.1.
• ddx-livekit-flowagent-ts/package.json:16 — @mastra/core@1.20.0 (pinned).
• ddx-livekit-flowagent-ts/package.json:17 — @mastra/libsql@^1.8.0.
• ddx-livekit-flowagent-ts/package.json:18 — @mastra/memory@1.12.1 (pinned).
• ddx-api/src/ai/tucan/registry/agent-factory.ts:253 — production new Agent({...}) site (Mastra primitive).
• ddx-api/src/ai/tucan/orchestrator/orchestrated-dispatch.workflow.ts:30 — Mastra createStep / createWorkflow imports.
• docs/claude-context/CLAUDE_MASTRA_CODEBASE_USAGE.md — Mastra primitives in-depth (the canonical link target).

Operational Notes

• The vendored monorepo is NOT what runs in production. node_modules/@mastra/* resolves to npm packages of the versions pinned in each package.json. The on-disk monorepo is a reference; production runs the npm-installed builds.
• Refreshing is manual. Run ddx-mastra-codebase/PULL_LATEST.sh when a new Mastra release lands AND we want to read its source. Production version bumps are separate.
• Version drift across services is real. ddx-api / ddx-tucan-engine at 1.28.0, ddx-livekit-flowagent-ts at 1.20.0. When sharing Mastra patterns across these services, verify the relevant primitive exists in the pinned version.
• Memory shard MEMORY_TUCAN_AI lists 1.13.0 (2026-04-24 snapshot) — that is stale. Update both this page AND the memory shard when the pinned version moves again.
• AGENTS.md is Mastra's own AI-rules file. When using AI-assisted Mastra changes, the Mastra team's own conventions apply on their tree (ddx-mastra-codebase/AGENTS.md).
• Patches live in patches/. Document any patch with a comment explaining the upstream issue / PR; remove the patch when the upstream fix lands.
• The Mastra repo is large. Don't Read the whole tree; prefer rag_code_search (semantic) or rg -n + targeted Read of single files.
• Examples folder is the most underrated. When designing a new workflow, search examples first; Mastra ships working scenarios for most common shapes.

Related Topics

• [[tucan-assistant]] — production consumer of Mastra Agent + Workflow primitives.
• [[agent-templates]] — YAML templates rendered into Mastra new Agent({...}) constructions.
• [[ai-medical-tools]] — createTucanTool factory built on top of Mastra Tool.
• [[tucan-orchestrator]] — Mastra createWorkflow / createStep consumer.
• [[tucan-rag-tools]] — uses Qdrant directly; Mastra-side RAG not used.
• [[tucan-engine-standalone]] — sandbox sibling of this reference tree.
• docs/claude-context/CLAUDE_MASTRA_CODEBASE_USAGE.md — Mastra reference (do not duplicate here, link).