儲存概覽

儲存是 Mastra 執行階段的持久化層。即使程序重新啟動，它仍可保留記憶、Workflow 狀態、可觀測性數據、Eval 結果、排程及長時間運行的 Agent 狀態。

儲存支援以下功能：

• 記憶：訊息記錄、對話串、資源及工作記憶。
• Workflow：用於暫停及恢復 Workflow 執行的持久快照。
• 可觀測性：Trace、span、指標、日誌及意見回饋。
• Evals：評分、數據集、實驗及評估結果。
• 長時間運行的 Agent：背景任務、排程、目標及對話串狀態。

何時設定儲存

當狀態必須在重新啟動後保留，或需要在多個程序之間共享時，請設定持久儲存適配器。持久儲存亦可讓 Studio 在不同工作階段中持續顯示狀態。預設的記憶體內儲存適合測試及短期本機實驗，但程序結束時便會遺失數據。

如應用程式需要以下任何行為，請使用儲存：

• Agent 記得過往訊息或用戶資料。
• Workflow 在重新啟動後暫停及恢復。
• Trace、指標、日誌、評分或意見回饋可繼續用於分析。
• 排程及背景任務在不同部署之間持續運行。
• 多個執行階段程序讀寫相同狀態。

儲存的運作方式

Mastra 儲存劃分為多個領域。每個領域負責一種執行階段數據，而儲存適配器可實作一個或多個領域。

領域	儲存的內容
memory	對話串、訊息、資源、工作記憶及其他 Agent 記憶狀態。
workflows	用於暫停及恢復執行的 Workflow 快照。
observability	Trace、span、指標、日誌及意見回饋。
scores	Eval 評分記錄。
datasets	Evals 及實驗所使用的數據集記錄與數據集項目。
experiments	實驗執行及個別項目的實驗結果。
backgroundTasks	背景任務記錄及執行狀態。
schedules	排程定義及觸發記錄。
threadState	持久保存的任務、目標及對話串狀態。

各適配器支援的領域不盡相同。如要查看完整領域清單及內置結構描述，請參閱儲存概覽參考資料。

按數據形態選擇後端

不同領域會寫入及查詢不同類型的數據。請根據領域的存取模式選擇後端：

• 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 等本機檔案數據庫。
• 使用複合儲存，將高流量領域（尤其是 observability）路由至專用後端。
• 在儲存適配器或複合儲存上設定保留政策，然後透過排程器或維護工作呼叫 storage.prune()。
• 根據應用程式使用的領域選擇 Provider。例如，排程需要已實作 schedules 領域的適配器。

設定範圍

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

執行個體層級儲存

執行個體層級儲存由註冊於同一 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,
  }),
})

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

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 會將不同領域路由至不同後端。當單一數據庫並不適合所有領域時，請使用它。

以下範例使用 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 是開始本機開發最快捷的方式，因為它毋須運行獨立的數據庫伺服器。

下一步

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