Mastra Engine

The Mastra Engine provides PostgreSQL-based storage for two core AI application needs:

Agent Memory - Persistent storage for conversation history and agent state
Vector Operations - Storage and similarity search for RAG applications

Mastra Engine is not required to run Mastra, but provides a “batteries-included” local development experience and a production-ready data layer.

Setting up for local development

The Mastra CLI includes commands to manage your engine and database:

mastra engine add: Sets up your dev environment, starts Docker containers for Postgres, and configures .env.
mastra engine up: Starts your Docker containers as defined in your docker config file.
mastra engine migrate: Runs database migrations.
mastra engine generate: Generates TypeScript types from your database schema.
mastra engine down: Stops your Docker containers.

The engine will run by default on port 5432 of localhost.

Configuring for Agent Memory

Configure your agent to use PostgreSQL for memory storage:

import { Mastra } from "@mastra/core";
import { PgMemory } from "@mastra/memory";
 
const pgMemory = new PgMemory({
  connectionString: process.env.POSTGRES_CONNECTION_STRING!,
});
 
export const mastra = new Mastra({
  memory: pgMemory,
  agents: { myAgent },
});

Now, agent memory operations like saveMemory, getContextWindow, and getMemory are available to your agent. See the Memory reference for more details.

Vector Operations (RAG)

For RAG applications, you can set up vector storage and reranking:

import { PgVector } from "@mastra/rag";
import { Reranker } from "@mastra/rerank";
 
// Initialize vector store and reranker
const vectorStore = new PgVector({
  connectionString: process.env.POSTGRES_CONNECTION_STRING!
});

Deploying to Production

To deploy to production, you’ll need to set up a production Postgres database and configure your Mastra application to use it.

You can run DB_URL=your_prod_db_url mastra engine migrate to create a schema in a production database.

Mocking for Tests

For testing or development, you can use the MockMastraEngine:

import { MockMastraEngine } from "@mastra/core";
 
const mockEngine = new MockMastraEngine({ url: "mock://localhost" });
 
// Create an entity
const entity = await mockEngine.createEntity({
  name: "Contacts",
  connectionId: "user_123",
});
 
// Insert records
await mockEngine.upsertRecords({
  entityId: entity.id,
  records: [
    { externalId: "c1", data: { name: "Alice" }, entityType: "Contacts" },
    { externalId: "c2", data: { name: "Bob" }, entityType: "Contacts" },
  ],
});
 
// Query the records
const records = await mockEngine.getRecordsByEntityId({ entityId: entity.id });
console.log(records);

This mock engine mimics the behavior of the real engine without requiring a real database connection, making it ideal for unit tests.

Using the Engine for Sync Operations

The engine also supports keeping external data sources up to date through sync operations:

 
await engine.syncRecords({
  name: "external_docs",
  connectionId: "sync_123", 
  records: updatedRecords,
  lastSyncId: "sync_20240315"
});

More details:

Entities represent a conceptual data model (like “Contacts”, “Orders”, or “Tickets”) in your application.
Records are individual data entries within an entity.
Syncs are async functions that manage data synchronization between external systems and Mastra. For example, you can use a sync to import records from a third-party API into your local database.

You can create, read, update, and delete entities and their records using the engine’s methods.

Engine Sync Operations APIs

Entity Management:

createEntity({ name, connectionId }): Create a new entity
getEntityById({ id }): Get an entity by ID
getEntity({ name, connectionId }): Get entity by name and/or connectionId
deleteEntityById({ id }): Delete an entity and its associated records

Record Management:

upsertRecords({ entityId, records }): Insert or update records for an entity
getRecordsByEntityId({ entityId }): Retrieve all records for an entity
getRecordsByEntityName({ name, connectionId }): Retrieve all records for an entity by name and connectionId
getRecords({ entityName, connectionId, options }): Query records with filtering, sorting, and pagination

Sync Operations:

syncRecords({ name, connectionId, records, lastSyncId }): Sync incoming data to an entity

Vector Search (Future)

Integrate with vector stores for RAG workflows.

Summary

The Mastra Engine is a PostgreSQL instance that stores agent memory and vector embeddings. You can spin it up locally with Docker for development and deploy it to a production instance. It’s a helpful starting spot for handling agent memory and vector operations — start with Postgres + pgvector, then adapt individual components based on your needs.

Mastra Dev Syncs