Storage

Storage 是 Mastra 运行时的持久化层。它让 memory、workflow 状态、可观测性数据、eval 结果、调度和长时运行的 Agent 状态在进程重启后仍然可用。

Storage 为以下功能提供支持：

• Memory：消息历史、线程、资源和工作记忆。
• Workflows：用于挂起和恢复 workflow 运行的持久化快照。
• 可观测性：traces、spans、指标、日志和反馈。
• Evals：分数、datasets、实验和评估结果。
• 长时运行的 agents：后台任务、调度、目标和线程状态。

何时配置 storage

当状态需要在重启后保留或在多个进程间共享时，配置持久化存储适配器。持久化存储还能让状态在 Studio 中跨会话可见。默认的内存存储适用于测试和短期本地实验，但进程退出时会丢失数据。

当应用需要以下任一行为时，请使用 storage：

• Agents 记住过去的消息或用户事实。
• Workflows 在重启后挂起并恢复。
• Traces、指标、日志、分数或反馈保留以供分析。
• 调度和后台任务跨部署继续运行。
• 多个运行时进程读写同一份状态。

Storage 如何工作

Mastra 存储按 domains 组织。一个 domain 负责一种运行时数据，一个存储适配器实现一个或多个 domains。

Domain	存储内容
memory	线程、消息、资源、工作记忆及其他 Agent 记忆状态。
workflows	用于挂起和恢复运行的 workflow 快照。
observability	Traces、spans、指标、日志和反馈。
scores	Eval 分数记录。
datasets	Evals 和实验使用的 dataset 记录及 dataset items。
experiments	实验运行及逐项实验结果。
backgroundTasks	后台任务记录及执行状态。
schedules	调度定义及触发历史。
threadState	持久化任务、目标和线程状态。

不同 domain 的适配器支持情况不同。完整 domain 列表和内置 schemas 参见存储概览参考。

按数据形态选择后端

不同 domains 写入和查询的数据类型不同。根据 domain 的访问模式选择后端：

• memory：每次带记忆的 Agent 调用都会读写行。请使用 libSQL、PostgreSQL 或 MongoDB 等事务型数据库。
• observability：写入高吞吐量遥测数据，且经常查询聚合结果。请使用专用的可观测性存储或 ClickHouse、DuckDB 等在线分析处理（OLAP）后端。
• workflows：存储运行恢复时必须可用的持久化快照。请使用可靠的持久化数据库。
• scores、datasets 和 experiments：存储频率较低的评估数据，通常稍后读取用于分析。
• schedules：存储调度定义和触发历史。请使用实现了 schedules domain 的适配器。

当各 domain 的运维需求不同时，使用组合存储将每个 domain 路由到合适的后端。

本地快速开始

本地开发请使用基于文件的 libSQL 数据库。它不需要单独的数据库服务器，并且能在重启之间持久化状态。

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { LibSQLStore } from '@mastra/libsql'

export const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: 'file:./mastra.db',
  }),
})

与 Studio 共享数据库

当 mastra dev 与应用一起运行时，请使用绝对路径，让两个进程访问同一个数据库：

url: 'file:/absolute/path/to/your/project/mastra.db'

file:./mastra.db 等相对路径会基于每个进程的工作目录解析，而二者可能不同。

Mastra 会在首次使用时初始化所需的存储结构。

生产环境配置

生产环境请使用持久化的托管数据库。对于大多数团队来说，PostgreSQL 是合适的默认选择，因为它适合事务型运行时状态，并且作为托管服务广泛可用。

生产建议：

• 使用带备份、监控和连接池的托管数据库。
• 在多进程生产部署中，避免使用 file:./mastra.db 等本地文件数据库。
• 使用组合存储将高吞吐量 domains（尤其是 observability）路由到专用后端。
• 在存储适配器或组合存储上配置保留策略，然后从调度器或维护任务中调用 storage.prune()。
• 根据应用使用的 domains 选择提供商。例如，schedules 需要实现 schedules domain 的适配器。

配置范围

Storage 可以在 Mastra 实例级别或 Agent 级别配置。

实例级存储

实例级存储由同一 Mastra 实例上注册的 agents、workflows、可观测性、evals、调度及其他运行时功能共享。

PostgreSQL

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { PostgresStore } from '@mastra/pg'

export const mastra = new Mastra({
  storage: new PostgresStore({
    id: 'mastra-storage',
    connectionString: process.env.DATABASE_URL,
  }),
})

MongoDB

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MongoDBStore } from '@mastra/mongodb'

export const mastra = new Mastra({
  storage: new MongoDBStore({
    id: 'mastra-storage',
    uri: process.env.MONGODB_URI,
    dbName: process.env.MONGODB_DB_NAME,
  }),
})

当大多数运行时 domains 可以共享同一个数据库时，请使用实例级存储。

Agent 级存储

Agent 级存储在 Memory 实例上配置。它仅覆盖该 Agent 记忆数据的实例级存储。

src/mastra/agents/support-agent.ts

import { Agent } from '@mastra/core/agent'
import { Memory } from '@mastra/memory'
import { PostgresStore } from '@mastra/pg'

export const supportAgent = new Agent({
  id: 'support-agent',
  name: 'Support agent',
  instructions: 'Answer customer support questions.',
  model: 'openai/gpt-5.6-sol',
  memory: new Memory({
    storage: new PostgresStore({
      id: 'support-agent-storage',
      connectionString: process.env.SUPPORT_AGENT_DATABASE_URL,
    }),
  }),
})

当 Agent 需要隔离的记忆边界或不同的记忆后端时，请使用 Agent 级存储。

组合存储

MastraCompositeStore将 domains 路由到不同后端。当单一数据库无法满足所有 domain 时使用它。

以下示例使用 libSQL 作为默认存储，并将 workflow 状态路由到 PostgreSQL：

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MastraCompositeStore } from '@mastra/core/storage'
import { LibSQLStore } from '@mastra/libsql'
import { WorkflowsPG } from '@mastra/pg'

export const mastra = new Mastra({
  storage: new MastraCompositeStore({
    id: 'composite-storage',
    default: new LibSQLStore({
      id: 'default-storage',
      url: 'file:./mastra.db',
    }),
    domains: {
      workflows: new WorkflowsPG({
        connectionString: process.env.DATABASE_URL,
      }),
    },
  }),
})

你也可以将 observability 路由到专用的分析后端。可观测性专用示例参见可观测性快速开始。

支持的提供商

每个提供商页面都包含安装说明、配置参数和使用示例。libSQL 是本地开发最快的路径，因为它不需要运行单独的数据库服务器。

• Aurora DSQL
• ClickHouse
• ClickHouse Managed Postgres
• Cloudflare D1
• Cloudflare KV
• Convex
• DuckDB
• DynamoDB
• Elasticsearch
• Google Cloud Spanner
• LanceDB
• libSQL
• Mastra
• MongoDB
• MySQL
• MSSQL
• Neon Postgres
• OracleDB
• PostgreSQL
• Redis
• Valkey
• Upstash

后续步骤

• 组合存储
• 存储保留策略
• 存储 schemas
• Memory
• 可观测性存储