第17章 Mastra 存储（Storage）

存储 存储是 Mastra 运行时的持久化层。它让记忆、工作流状态、可观测性数据、评估结果、调度任务以及长时间运行的 Agent 状态在进程重启后依然可用。 存储支撑的功能包括： 记忆（Memory）：消息历史、线程、资源和工作记忆。 工作流（Workflows）：用于挂起和恢复工作流运行的持久化快照。 可观测性（Observability）：追踪、Span、指标、日志和反馈。 评估（Evals）：分数、数据集、实验和评估结果。 长时间运行的 Agent：后台任务、调度、目标和线程状态。 什么时候需要配置存储 当状态需要在重启后保留，或者需要跨进程共享时，就应配置持久化存储适配器。持久化存储还能让状态在 Studio 中跨会话可见。默认的内存存储适合测试和短期本地实验，但进程退出后数据就会丢失。 当应用有以下任一需求时，请使用存储： Agent 需要记住历史消息或用户信息。 工作流在重启后需要挂起并恢复。 追踪、指标、日志、分数或反馈需要保留下来供后续分析。 调度和后台任务需要在多次部署之间持续运行。 多个运行时进程需要读写同一份状态。 存储的工作原理 Mastra 的存储按域组织。每个域负责一类运行时数据，一个存储适配器可以实现一个或多个域。 | 域 | 存储内容 | | memory | 线程、消息、资源、工作记忆及其他 Agent 记忆状态 | | workflows | 用于挂起和恢复运行的工作流快照 | | observability | 追踪、Span、指标、日志和反馈 | | scores | 评估分数记录 | | datasets | 评估和实验使用的数据集记录及数据项 | | experiments | 实验运行记录和逐项实验结果 | | backgroundTasks | 后台任务记录和执行状态 | | schedules | 调度定义和触发历史 | | threadState | 持久化的任务、目标和线程状态 | 不同域的适配器支持情况各不相同。完整的域列表和内置 schema 请参考存储概览文档。 按数据形态选择后端 不同域写入和查询的数据类型不同，应根据域的访问模式来选择后端： memory：每次带记忆的 Agent 调用都会读写数据行，适合使用 libSQL、PostgreSQL 或 MongoDB 这类事务型数据库。 observability：写入大量遥测数据，且常做聚合查询，适合使用专门的可观测性存储或 ClickHouse、DuckDB 这类 OLAP 后端。 workflows：存储必须在运行恢复时可用的持久化快照，应使用可靠的持久化数据库。 scores、datasets 和 experiments：存储频率较低的评估数据，通常供后续分析读取。 schedules：存储调度定义和触发历史，使用实现了 schedules 域的适配器即可。 当各域的运维需求不同时，可以使用组合存储，把每个域路由到合适的后端。 本地快速上手 本地开发推荐使用基于文件的 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 这类本地文件数据库。 把高流量的领域（尤其是可观测性数据）路由到配置了 composite storage 的专用后端。 在存储适配器或 composite store 上配置保留策略，然后通过定时任务或维护任务调用 storage.prune()。 根据应用实际使用的领域来选择 provider，例如 schedules 功能要求适配器实现 schedules 领域。 配置范围 存储可以在 Mastra 实例级别配置，也可以在 agent 级别配置。 实例级存储 实例级存储由注册在同一个 Mastra 实例上的 agents、workflows、可观测性、evals、schedules 等运行时功能共享。 PostgreSQL MongoDB 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,
}),
})
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,
}),
})
当大多数运行时领域可以共享同一个数据库时，就使用实例级存储。 Agent 级存储 Agent 级存储配置在 Memory 实例上。它只会覆盖该 Agent 记忆数据的实例级存储配置。 src/mastra/agents/support-agent.tsimport { 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 可以将不同领域路由到不同的后端。当一个数据库无法满足所有领域的需求时，就可以使用它。 下面的示例使用 libSQL 作为默认存储，并将工作流状态路由到 PostgreSQL： src/mastra/index.tsimport { 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,
}),
},
}),
})
你还可以把可观测性数据路由到专门的分析后端，具体示例可参考可观测性快速入门。 支持的提供商 每个提供商的页面都包含安装说明、配置参数和使用示例。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 下一步 复合存储 存储保留策略 存储模式 Memory 可观测性存储