Mastra class

The Mastra class has been restructured to restrict top-level imports and replace direct property access with getter methods.

Changed

Top-level imports to subpath imports

The main @mastra/core index file now only exports Mastra and Config. All other exports have been moved to subpath imports. This change improves tree-shaking and reduces bundle size by allowing bundlers to eliminate unused code.

To migrate, update all imports from @mastra/core to use the appropriate subpath.

- import { Mastra, Agent, Workflow, createTool } from '@mastra/core';
+ import { Mastra, type Config } from '@mastra/core';
+ import { Agent } from '@mastra/core/agent';
+ import { Workflow } from '@mastra/core/workflows';
+ import { createTool } from '@mastra/core/tools';

Codemod

You can use Mastra's codemod CLI to update your code automatically:

npx @mastra/codemod@latest v1/mastra-core-imports .

experimental_auth to auth

The experimental auth configuration has been promoted to stable. This change reflects that the auth API is now stable and production-ready.

To migrate, rename the experimental_auth key to auth in your Mastra configuration.

  const mastra = new Mastra({
-   experimental_auth: {
+   auth: {
      provider: workos,
    },
  });

Codemod

You can use Mastra's codemod CLI to update your code automatically:

npx @mastra/codemod@latest v1/experimental-auth .

Required id parameter for all mastra primitives

All storages, vector stores, agents, workflows, mcpServers, processors, scorers, and tools now require an id parameter during initialization. Required IDs standardize the Mastra API and prevent ID conflicts.

All these primitives also now have get, list, and add functions.

To migrate, add an id parameter to all storage and vector store instantiations. When using the same storage/vector class multiple times, ensure each instance has a unique ID.

- const storage = new LibSQLStore({
-   url: ':memory:',
- });
+ const storage = new LibSQLStore({
+   id: 'my-app-storage',
+   url: ':memory:',
+ });

- const vector = new PgVector({
-   connectionString: process.env.DATABASE_URL,
- });
+ const vector = new PgVector({
+   id: 'my-app-vector',
+   connectionString: process.env.DATABASE_URL,
+ });

When using separate instances for different purposes, use descriptive unique IDs:

  const agentMemory = new Memory({
    storage: new LibSQLStore({
-     url: 'file:./agent.db',
+     id: 'weather-agent-memory-storage',
+     url: 'file:./agent.db',
    }),
  });

  const mastra = new Mastra({
    storage: new LibSQLStore({
+     id: 'mastra-storage',
      url: ':memory:',
    }),
  });

Primitive plural APIs changes from get<primitives> to list<primitive>

get* functions that returned all instances of a primitive have been renamed to list* to better reflect their purpose.

- const agents = mastra.getAgents();
+ const agents = mastra.listAgents();
- const vectors = mastra.getVectors();
+ const vectors = mastra.listVectors();
- const workflows = mastra.getWorkflows();
+ const workflows = mastra.listWorkflows();
- const scorers = mastra.getScorers();
+ const scorers = mastra.listScorers();
- const mcpServers = mastra.getMCPServers();
+ const mcpServers = mastra.listMCPServers();
- const logsByRunId = await mastra.getLogsByRunId({ runId: 'id', transportId: 'id' });
+ const logsByRunId = await mastra.listLogsByRunId({ runId: 'id', transportId: 'id' });
- const logs = await mastra.getLogs('transportId');
+ const logs = await mastra.listLogs('transportId');

Codemod

You can use Mastra's codemod CLI to update your code automatically:

npx @mastra/codemod@latest v1/mastra-plural-apis .

Each primitive has a getById and a get function

mastra.getMCPServer('myServer') // Works (registry key)
mastra.getMCPServerById('my-mcp-server') // Works (intrinsic ID)

Tool registration now uses intrinsic IDs

When tools are auto-registered from agents or MCP servers to the Mastra instance, they now use the tool's intrinsic id instead of the configuration object key. This prevents collisions when multiple agents/MCP servers have tools with the same configuration key.

To migrate, update any code that references tools by their configuration keys to use the tool's intrinsic ID instead.

  const agent = new Agent({
    id: 'agent1',
    tools: {
      searchTool: weatherSearchTool,
    },
  });

- mastra.getTool('searchTool');
+ mastra.getTool(weatherSearchTool.id);