Memory

note

The Agent Builder is part of the Mastra Enterprise Edition. Production deployments require a valid EE license. Contact sales for more information.

The Agent Builder pins a default memory shape onto every new agent through builder.configuration.agent.memory. The default applies when an end user creates a new agent and doesn't override it.

Quickstart

src/mastra/index.ts

import { MastraEditor } from '@mastra/editor'

new MastraEditor({
  builder: {
    enabled: true,
    configuration: {
      agent: {
        memory: { observationalMemory: true },
      },
    },
  },
})

Observational memory lets the agent learn long-lived facts from past conversations. Storage on the Mastra instance is required — see the Memory overview for the prerequisites.

Observational memory model

Observational memory runs an Observer and Reflector model on top of every conversation. For Agent Builder agents, the default model is openai/gpt-5-mini, which requires an OPENAI_API_KEY environment variable in any environment where the Builder agent will run.

note

This default applies only to agents created through the Agent Builder. Core (non-builder) agents configured with observationalMemory: true keep the framework default google/gemini-2.5-flash (which uses GOOGLE_API_KEY, falling back to GOOGLE_GENERATIVE_AI_API_KEY).

To use a different model, set observationalMemory.model to any model ID supported by the Mastra model router (and provide the matching provider credentials). An explicit model always wins over the Builder default:

src/mastra/index.ts

new MastraEditor({
  builder: {
    enabled: true,
    configuration: {
      agent: {
        memory: {
          observationalMemory: {
            model: 'openai/gpt-5.5',
          },
        },
      },
    },
  },
})

The model field applies to both the Observer and Reflector. You can also override each one independently via observation.model and reflection.model. See the SerializedMemoryConfig reference for the full shape.

Storage and vector requirements

Memory features layer on top of Mastra.storage:

• Message history (options.lastMessages) requires storage.
• Observational memory (observationalMemory: true) requires storage.
• Semantic recall (options.semanticRecall) requires storage plus a registered vector adapter (vector) and an embedder (embedder).

If a required adapter is missing, Mastra throws a descriptive error at agent run time. See Semantic recall for the full list of supported vector stores and embedders.

Related

• Memory overview: Concepts and core configuration.
• BuilderAgentDefaults reference: The full memory field schema.
• Configuration: Wire memory alongside the rest of the Builder config.