Storage 概覽

Storage 是 Mastra 執行環境的持久化層。處理程序重新啟動後，它仍會保留記憶體、Workflow 狀態、可觀測性資料、Eval 結果、排程，以及長時間執行 Agent 的狀態。

Storage 支援：

• 記憶體：訊息歷程、討論串、資源與工作記憶體。
• Workflow：用於暫停及繼續 Workflow 執行的耐久快照。
• 可觀測性：Trace、span、指標、記錄與意見回饋。
• Evals：分數、資料集、實驗與評估結果。
• 長時間執行的 Agent：背景工作、排程、目標與討論串狀態。

何時設定 Storage

當狀態必須在重新啟動後保留，或必須在多個處理程序之間共用時，請設定持久性 Storage 介面卡。持久性 Storage 也能讓 Studio 跨工作階段顯示狀態。預設的記憶體內儲存適合測試與短期本機實驗，但處理程序結束時資料便會遺失。

應用程式需要下列任一行為時，請使用 Storage：

• Agent 記住過去的訊息或使用者資訊。
• Workflow 在重新啟動後暫停並繼續執行。
• Trace、指標、記錄、分數或意見回饋可持續供分析使用。
• 排程與背景工作可跨部署繼續執行。
• 多個執行環境處理程序讀寫相同狀態。

Storage 的運作方式

Mastra Storage 由數個**領域（domain）**組成。每個領域擁有一種類型的執行階段資料，而 Storage 介面卡會實作一或多個領域。

領域	儲存內容
memory	討論串、訊息、資源、工作記憶體及其他 Agent 記憶體狀態。
workflows	用於暫停及繼續執行的 Workflow 快照。
observability	Trace、span、指標、記錄與意見回饋。
scores	Eval 分數記錄。
datasets	Evals 與實驗所使用的資料集記錄及資料集項目。
experiments	實驗執行及各項目的實驗結果。
backgroundTasks	背景工作記錄與執行狀態。
schedules	排程定義與觸發歷程。
threadState	耐久的工作、目標與討論串狀態。

各介面卡支援的領域不盡相同。如需完整領域清單與內建結構描述，請參閱 Storage 概覽參考資料。

依資料形態選擇後端

不同領域會寫入及查詢不同種類的資料。請依領域的存取模式選擇後端：

• memory：每次需要記憶的 Agent 呼叫都會讀寫資料列。請使用 libSQL、PostgreSQL 或 MongoDB 等交易式資料庫。
• observability：寫入大量遙測資料，且經常查詢彙總結果。請使用專用的可觀測性儲存區，或 ClickHouse、DuckDB 等線上分析處理（OLAP）後端。
• workflows：儲存執行繼續時必須可用的耐久快照。請使用可靠的持久性資料庫。
• scores、datasets 與 experiments：儲存頻率較低、通常稍後才會讀取以供分析的評估資料。
• schedules：儲存排程定義與觸發歷程。請使用已實作 schedules 領域的介面卡。

當各領域的營運需求不同時，請使用複合 Storage，將每個領域路由至合適的後端。

在本機開始使用

本機開發時，請搭配檔案型資料庫使用 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 會在首次使用時初始化所需的 Storage 結構。

正式環境設定

正式環境請使用持久性的受管理資料庫。PostgreSQL 很適合作為大多數團隊的預設選擇，因為它能妥善處理交易式執行階段狀態，而且普遍可由受管理服務提供。

正式環境指引：

• 使用具備備份、監控與連線集區的受管理資料庫。
• 請勿在多處理程序正式環境部署中使用 file:./mastra.db 等本機檔案資料庫。
• 使用複合 Storage，將高流量領域（尤其是 observability）路由至專用後端。
• 在 Storage 介面卡或複合儲存區設定保留政策，再透過排程器或維護工作呼叫 storage.prune()。
• 根據應用程式使用的領域選擇 Provider。例如，排程需要已實作 schedules 領域的介面卡。

設定範圍

Storage 可在 Mastra 執行個體層級或 Agent 層級設定。

執行個體層級 Storage

執行個體層級 Storage 由註冊至同一個 Mastra 執行個體的 Agent、Workflow、可觀測性、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,
  }),
})

當大多數執行階段領域可以共用同一個資料庫時，請使用執行個體層級 Storage。

Agent 層級 Storage

Agent 層級 Storage 是在 Memory 執行個體上設定。它只會覆寫該 Agent 記憶體資料所使用的執行個體層級 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 需要獨立的記憶體界線或不同的記憶體後端時，請使用 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 路由至專用的分析後端。如需可觀測性專用範例，請參閱可觀測性快速入門。

支援的 Provider

每個 Provider 頁面都包含安裝說明、設定參數與使用範例：

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

提示

libSQL 是本機開發的最快途徑，因為不需要執行獨立的資料庫伺服器。

後續步驟

• 複合 Storage
• Storage 保留政策
• Storage 結構描述
• 記憶體
• 可觀測性 Storage