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. The default model is google/gemini-2.5-flash, which requires a GOOGLE_GENERATIVE_AI_API_KEY environment variable in any environment where the Builder agent will run.

To use a different model, set observationalMemory.model to any model ID supported by the Mastra model router (and provide the matching provider credentials):

src/mastra/index.ts

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

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.