@mastra/core/dist/docs/references/docs-agent-builder-memory.md

> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# Memory

> **Note:** The Agent Builder is part of the Mastra Enterprise Edition. Production deployments require a valid EE license. [Contact sales](https://mastra.ai/contact) 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

```typescript
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](https://mastra.ai/docs/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:

```typescript
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](https://mastra.ai/reference/memory/serialized-memory-config) 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](https://mastra.ai/docs/memory/semantic-recall) for the full list of supported vector stores and embedders.

## Related

- [Memory overview](https://mastra.ai/docs/memory/overview): Concepts and core configuration.
- [BuilderAgentDefaults reference](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults): The full `memory` field schema.
- [Configuration](https://mastra.ai/docs/agent-builder/configuration): Wire `memory` alongside the rest of the Builder config.