Mastra Changelog 2026-02-04

We’ve been busy working on ways to help your agents scale, both in capability and in day-to-day ergonomics. You’ll find big improvements to memory, tool loading, and a much smoother skills workflow across the server, UI, and CLI.

Release: @mastra/core@1.2.0

Let’s dive in:

Observational Memory for long-running agents

Observational Memory (OM) is a new memory system that makes small context windows behave like large ones, while still preserving long-term memory. Instead of repeatedly stuffing old chat messages into your prompt, OM compresses conversation history into dense observation logs (often 5 to 40x smaller). As observations accumulate, they get condensed into higher-level reflections so your agent stays focused even after thousands of turns.

In practice, OM helps with the two classic failure modes of long-running agents: context rot (important details get drowned out) and token waste (you keep paying to resend the same history). OM is designed to keep prompts lean without throwing away what your agent learned.

Enabling it is straightforward:

 1import { Agent } from "@mastra/core";
 2import { Memory } from "@mastra/memory";
 3import { PostgresStore } from "@mastra/pg";
 4import { openai } from "@ai-sdk/openai";
 5
 6const memory = new Memory({
 7  storage: new PostgresStore({ connectionString: process.env.DATABASE_URL }),
 8  options: {
 9    observationalMemory: true,
10  },
11});
12
13const agent = new Agent({
14  name: "my-agent",
15  model: openai("gpt-4o"),
16  memory,
17});

A few things to know if you’re building deeper systems:

• OM supports thread-scoped memory (per conversation) and resource-scoped memory (shared across a user’s threads).
• Processor state and streaming got upgrades to support OM-powered loops, including processorStates, abort signal propagation to processors, and a ProcessorStreamWriter for custom stream events.
• The Playground UI now includes OM-aware UI, with observation and reflection markers inline in chat, plus an OM panel showing history, token usage, and config. This UI is safely gated behind a context provider that no-ops when OM is not configured.

This feature requires the latest versions of @mastra/core, @mastra/memory, mastra, and one of the updated adapters (@mastra/pg, @mastra/libsql, or @mastra/mongodb). (PR #12599)

Skills.sh ecosystem integration (server + UI + CLI)

Skills are one of the fastest ways to expand what your agents can do, and this release makes the skills workflow feel first-class across the stack.

On the server side, @mastra/server now includes skills.sh proxy endpoints for the full lifecycle: search, browse, preview, install, update, and remove. That means your app can interact with the skills ecosystem without custom glue code.

In the Studio UI, there’s a new “Add Skill” dialog that lets you:

• Search and browse popular skills from the skills.sh registry
• Preview skill content with rendered SKILL.md (tables, code blocks, and more)
• Install, update, and remove skills directly from the UI
• See installed status for skills already present in your workspace

On the CLI side, create-mastra can now optionally install Mastra skills during project creation. If you run the wizard interactively, it prompts you to install the official Mastra skill. If you’re scripting setup, you can do it non-interactively with --skills and a comma-separated list of agent names:

 1create-mastra --skills claude-code,codex

The wizard also pre-selects popular defaults (Claude Code, Codex, OpenCode, Cursor) when you opt into installing skills, and it can generate AGENTS.md (and optionally CLAUDE.md) to help document agent usage in your repo.

These changes make skills feel “built-in” whether you’re clicking around in the UI, provisioning a workspace in CI, or exposing skills operations via your own server. (PR #12492, PR #12582, PR #12626, PR #12658)

Dynamic tool discovery with ToolSearchProcessor

If you’ve ever tried to give an agent access to a huge tool library (MCP servers, integration-heavy setups, internal tool catalogs), you’ve probably hit the context wall. Tool definitions can be expensive, and including hundreds of tools up front can burn tokens fast.

ToolSearchProcessor introduces a new pattern: let the agent search for tools and load only what it needs, on demand. You attach the processor with a set of searchable tools, and it injects two meta-tools into the agent’s environment:

• search_tools, to search available tools by relevance
• load_tool, to load a specific tool into the conversation

Loaded tools become available immediately and persist within that conversation thread, so the agent does not need to reload them every step.

Here’s the core setup:

 1import { Agent } from "@mastra/core";
 2import { ToolSearchProcessor } from "@mastra/core/processors";
 3
 4// Create a processor with searchable tools
 5const toolSearch = new ToolSearchProcessor({
 6  tools: {
 7    createIssue: githubTools.createIssue,
 8    sendEmail: emailTools.send,
 9    // ... hundreds of tools
10  },
11  search: {
12    topK: 5, // default: 5
13    minScore: 0.1, // default: 0
14  },
15});
16
17// Attach processor to agent
18const agent = new Agent({
19  name: "my-agent",
20  inputProcessors: [toolSearch],
21  tools: {
22    // always-available tools live here
23  },
24});

This approach dramatically cuts context usage (the changelog notes about a 94% reduction in large tool setups) while still giving the agent flexibility. It’s a strong default when your tool catalog is big, frequently changing, or shared across many agents. (PR #12290)

New @mastra/editor: store, version, and resolve agents from a database

@mastra/editor is a new package that makes agent configuration something you can persist, version, and activate in a database, not just in code.

It’s built for teams that want to:

• Store complete agent configurations, including instructions, model settings, tools, workflows, nested agents, scorers, processors, and memory config
• Manage versions and activate a specific version of an agent
• Resolve and instantiate dependencies from the Mastra registry automatically (tools, workflows, sub-agents, etc.)
• Cache resolved agents for performance
• Keep everything type-safe with TypeScript-friendly serialization

A simple flow looks like this:

 1import { Mastra } from "@mastra/core";
 2import { MastraEditor } from "@mastra/editor";
 3
 4const mastra = new Mastra({
 5  /* config */
 6  editor: new MastraEditor(),
 7});
 8
 9// Store an agent configuration
10const agentId = await mastra.storage.stores?.agents?.createAgent({
11  name: "customer-support",
12  instructions: "Help customers with inquiries",
13  model: { provider: "openai", name: "gpt-4" },
14  tools: ["search-kb", "create-ticket"],
15  workflows: ["escalation-flow"],
16  memory: { vector: "pinecone-db" },
17});
18
19// Retrieve and use the stored agent
20const agent = await mastra.getEditor()?.getStoredAgentById(agentId);
21const response = await agent?.generate("How do I reset my password?");
22
23// List stored agents
24const agents = await mastra.getEditor()?.listStoredAgents({ pageSize: 10 });

This unlocks “dynamic agent management” patterns where product teams can iterate on prompts and capabilities without redeploying, and platform teams can enforce consistent dependency resolution via the registry.

Under the hood, the editor release also included storage improvements like better JSONB handling in LibSQL, PostgreSQL, and MongoDB adapters, and better resolution queries to properly merge version data. (PR #12631)

Breaking Changes

Elasticsearch vector document IDs now come from Elasticsearch _id (PR #11298): The Elasticsearch vector store no longer writes a separate id field into stored documents. If you previously relied on source.id, you should migrate to using Elasticsearch’s native _id instead.

This update also added authentication options (API key, basic, bearer) for Elasticsearch connections, aligning with common Elasticsearch auth best practices.

 1// After
 2const store = new ElasticSearchVector({
 3  url,
 4  id: "my-index",
 5  auth: { apiKey: process.env.ELASTICSEARCH_API_KEY! },
 6});

Other Notable Updates

• Processors can explicitly block tool calls: Fixed an issue where processors returning { tools: {}, toolChoice: "none" } were ignored, and toolChoice incorrectly defaulted to "auto". This enables patterns like forcing a final text response when maxSteps is reached. (PR #12601)
• Custom input processors no longer disable memory and skills: Custom processors now replace only the processors you configured, while memory and workspace skills remain available in .generate() and .stream(). (PR #12676)
• Workspace search index naming works across SQL vector stores: Index names now use underscores (avoiding hyphens that some SQL stores reject), and you can set searchIndexName explicitly. (PR #12673)
• Workspace filesystem and sandbox providers get consistent logging: Providers extending MastraFilesystem or MastraSandbox now automatically receive the Mastra logger. (PR #12606)
• Embedding token usage is now exposed in Memory APIs: saveMessages and recall now return usage: { tokens: number }, and abstract MastraMemory signatures were updated accordingly. (PR #12556)
• Observability safety fix: Prevented sensitive observability credentials (like Langfuse API keys) from being exposed in tool execution error logs by excluding tracingContext from logged data. (PR #12669)
• Moonshot (kimi-k2.5) tool calling fix and endpoint change: Moonshot providers now use Anthropic-compatible endpoints to correctly handle reasoning_content, fixing multi-step tool calling failures. (PR #12530)
• Agent network JSON robustness: Routing now uses parsePartialJson from AI SDK to recover from truncated or slightly malformed JSON instead of failing immediately and retrying. (PR #12526)
• Fastify streaming CORS headers preserved: Fixed missing cross-origin headers on streaming responses when using the Fastify adapter. (PR #12633)
• Cloudflare Workers deploy fix for observability snapshots: Avoided calling fileURLToPath at module init time so Workers do not crash when import.meta.url is undefined. (PR #12540)
• Higher default tracing serialization limits: Tracing now defaults to maxStringLength: 128KB and maxDepth: 8 to prevent prompt/response truncation. (PR #12579)
• Standard Schema support in @mastra/schema-compat: Added toStandardSchema() and related types to interoperate with any library implementing the Standard Schema spec. (PR #12527)
• Evented workflows parity improvements: Evented workflows were brought closer to the default execution engine behavior. (PR #12555)
• Inngest workflow stability: Fixed long running steps causing Inngest workflows to fail. (PR #12522)
• MCP Docs Server refocus: The MCP Docs Server was simplified to focus on documentation, switching local docs sources to generated llms.txt files for accuracy. (PR #12623)
• Convex adapter fix: Corrected the import path for storage constants in Convex server storage. (PR #12560)

That’s all for @mastra/core@1.2.0!

Happy building! 🚀