Storage 概述

Storage 是 Mastra 运行时的持久化层。进程重启后，它仍会保留 Memory、Workflow 状态、Observability 数据、Eval 结果、Schedule 和长时间运行的 Agent 状态。

Storage 为以下功能提供支持：

• Memory：消息历史记录、thread、资源和 working memory。
• Workflow：用于暂停和恢复 Workflow 运行的持久快照。
• Observability：Trace、span、指标、日志和反馈。
• Evals：评分、数据集、实验和评估结果。
• 长时间运行的 Agent：后台任务、Schedule、目标和 thread 状态。

何时配置 Storage

当状态必须在重启后继续存在或需要跨进程共享时，请配置持久化 Storage adapter。持久化 Storage 还能让 Studio 在不同会话间持续显示状态。默认的内存存储适用于测试和短期本地实验，但进程退出时会丢失数据。

如果应用需要以下任一行为，请使用 Storage：

• Agent 记住过去的消息或用户信息。
• Workflow 在重启后暂停并恢复。
• Trace、指标、日志、评分或反馈可供后续分析。
• Schedule 和后台任务在部署之间持续运行。
• 多个运行时进程读写同一状态。

Storage 的工作原理

Mastra Storage 按域组织。每个域负责一种运行时数据，Storage adapter 会实现一个或多个域。

域	存储内容
memory	Thread、消息、资源、working memory 和其他 Agent Memory 状态。
workflows	用于暂停和恢复运行的 Workflow 快照。
observability	Trace、span、指标、日志和反馈。
scores	Eval 评分记录。
datasets	Eval 和实验使用的数据集记录及数据集条目。
experiments	实验运行和逐条目实验结果。
backgroundTasks	后台任务记录和执行状态。
schedules	Schedule 定义和触发历史记录。
threadState	持久化的任务、目标和 thread 状态。

不同 adapter 支持的域有所差异。有关完整域列表和内置 schema，请参阅 Storage 概述 Reference。

根据数据形态选择后端

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

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

当各域的运维需求不同时，请使用组合式 Storage，将各域路由到适合的后端。

在本地开始使用

本地开发时，使用基于文件的 libSQL 数据库。它不需要单独的数据库 Server，并且可在重启之间保留状态。

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 会在首次使用时初始化所需的 Storage 结构。

为生产环境配置

在生产环境中，请使用持久化托管数据库。PostgreSQL 很适合作为大多数团队的默认选择，因为它能良好支持事务型运行时状态，并且被广泛用作托管服务。

生产环境建议：

• 使用具备备份、监控和连接池的托管数据库。
• 不要在多进程生产部署中使用 file:./mastra.db 等本地文件数据库。
• 使用组合式 Storage，将高流量域（尤其是 observability）路由到专用后端。
• 在 Storage adapter 或组合存储上配置保留策略，然后通过 Scheduler 或维护任务调用 storage.prune()。
• 根据应用使用的域选择 Provider。例如，Schedule 需要实现了 schedules 域的 adapter。

配置范围

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

实例级 Storage

实例级 Storage 由注册在同一 Mastra 实例上的 Agent、Workflow、Observability、Evals、Schedule 和其他运行时功能共享。

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,
  }),
})

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

Agent 级 Storage

Agent 级 Storage 在 Memory 实例上配置。它仅覆盖该 Agent Memory 数据的实例级 Storage。

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 需要隔离的 Memory 边界或不同的 Memory 后端时，请使用 Agent 级 Storage。

组合式 Storage

MastraCompositeStore 将不同域路由到不同后端。当一个数据库无法适配所有域时，请使用它。

以下示例使用 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 路由到专用分析后端。有关针对 Observability 的示例，请参阅 Observability 快速入门。

支持的 Provider

每个 Provider 页面都包含安装说明、配置参数和使用示例：

• libSQL
• PostgreSQL
• MongoDB
• OracleDB
• Upstash
• Redis
• Cloudflare D1
• Cloudflare KV 与 Durable Objects
• Convex
• DynamoDB
• LanceDB
• Microsoft SQL Server
• Google Cloud Spanner

提示

libSQL 是本地开发的最快上手方式，因为它不需要运行单独的数据库 Server。

后续步骤

• 组合式 Storage
• Storage 保留策略
• Storage schema
• Memory
• Observability Storage