Mastra Changelog 2026-03-17

We’ve been busy tightening up the agentic loop and the developer experience around memory and integrations. If you’re running tools through providers, replaying threads, or wiring up MCP servers, this one should feel immediately smoother.

Release: @mastra/core@1.14.0

Let's dive in:

AI Gateway Tool Support in the Agentic Loop

Mastra agents can now treat AI Gateway tools (for example, gateway.tools.perplexitySearch()) as first-class, provider-executed tools inside the agentic loop. That means Mastra will infer providerExecuted, preserve the right metadata, merge streamed provider results back into the originating tool call, and skip local execution when the provider has already produced a result.

This closes a frustrating gap where Gateway tools behaved a bit like provider tools, but without the provider persisting results server-side. In practice, that could lead to dropped tool results, out-of-order tool call persistence, or confusing memory replays where the tool call existed but its result did not.

If you are using streamed generation plus provider-executed tools, these fixes help ensure your tool call timeline stays consistent and replayable.

Related fixes included in this release:

• Tool call parts are persisted in stream order, even when providers defer tool execution.
• Deferred tool results are merged back into the original message correctly.
• Updates that transition a tool call into its result state now preserve providerExecuted and providerMetadata, instead of accidentally stripping them.

(PR #14016, PR #14282, PR #14431, PR #13860)

More Reliable Observational Memory (Cache Stability + “As Of” Retrieval)

Observational memory got a reliability upgrade focused on long-running threads, replay, and debugging.

First, persisted observations are now chunked more predictably using dated message boundary delimiters. This makes the observation cache more stable and reduces the chance that small ordering shifts or buffering differences cause large prompt diffs later.

Second, @mastra/memory now exposes getObservationsAsOf(), which lets you retrieve the exact set of observations that were active at a specific message timestamp. That is especially useful when you need consistent prompting for replays, want to debug “what did the agent know at the time?”, or you are running evaluation workflows that depend on time-accurate context.

 1import { getObservationsAsOf } from "@mastra/memory";
 2
 3// Get observations that existed when a specific message was created
 4const observations = getObservationsAsOf(record.activeObservations, message.createdAt);

There are also a few practical guardrails bundled in:

• Observational memory no longer triggers an observation while provider-executed tool calls are still pending (avoids message splitting and follow-up turn errors).
• Oversized tool results are limited before they hit the observer prompt, stripping large encryptedContent blobs and truncating payloads so token estimates better match what the model actually sees.

(PR #14367, PR #14282, PR #14344)

MCP Client Diagnostics & Per-Server Control

@mastra/mcp now includes per-server operational controls and diagnostics, designed for the real-world messiness of stdio servers and multi-server toolchains.

You can now:

• Reconnect a single MCP server without restarting everything (reconnectServer(serverName)).
• List toolsets alongside per-server errors (listToolsetsWithErrors()).
• Inspect the captured stderr stream for a specific server (getServerStderr(serverName)).

That makes it much easier to build robust “self-healing” MCP integrations, and to debug issues when one server is misconfigured, flaky, or emitting useful diagnostics on stderr.

 1const { toolsets, errors } = await mcpClient.listToolsetsWithErrors();
 2
 3await mcpClient.reconnectServer("slack");
 4
 5const stderr = mcpClient.getServerStderr("slack");

(PR #14377)

Breaking Changes

None called out in this changelog.

Other Notable Updates

• Tracing identifiers now include spanId: Execution results that return tracing identifiers (including agent .stream(), .generate(), and workflow run results) now include spanId alongside traceId, making it easier to query your observability vendor by the run’s root span. (PR #14327)
• Working memory schema generation improvements: generateEmptyFromSchema now accepts JSON schema as either a string or pre-parsed object, recursively initializes nested objects, and respects default values. WorkingMemoryTemplate is now a discriminated union that supports Record<string, unknown> content for JSON format templates, and duplicate schema generation logic was removed in favor of a shared utility. (PR #14310)
• Working memory schema typing fixes: workingMemory.schema now correctly accepts supported schemas such as Zod and JSON Schema, and request context schema inference works properly with Zod v3 and v4 (and other StandardSchema-compatible schemas). (PR #14363)
• Skills refresh no longer wipes workspace search: Calling skills.refresh() (or triggering re-discovery via maybeRefresh()) no longer clears the entire BM25 index, preserving auto-indexed workspace content while still updating skill entries. (PR #14287)
• replaceString now escapes $ correctly: Replacement strings containing $ (like $&) are no longer treated as regex backreferences when you intended literal text. (PR #14434)
• Provider registry and model docs updated: The provider registry and model documentation were refreshed to reflect the latest models and providers. (commit 51970b3)

That's all for @mastra/core@1.14.0!

Happy building! 🚀