Today we're announcing the Mastra integration for SurrealDB. One package, @surrealdb/mastra-ai, gives Mastra agents two things they have always had to assemble by hand: a single database for everything the framework persists, and a managed memory layer that turns conversations into something an agent can actually recall.
What a Mastra agent has to persist
Mastra is a TypeScript framework for building AI agents and workflows, and it is deliberately unopinionated about storage. That freedom has a cost. A production Mastra app ends up persisting four different shapes of data at once.
Conversations: threads, messages, working memory. The verbatim record of what was said.
Workflow state: the suspend and resume snapshots that let a long-running workflow pause for a human approval on Tuesday and pick up again on Thursday.
Observability: spans, traces and scores, so you can see what the agent did and how well it did it.
Embeddings: the vectors behind every RAG pipeline and every semantic lookup.
The usual answer is four systems. Postgres for threads and workflow state, a dedicated vector database for embeddings, a tracing backend for spans, and a memory service bolted on the side. Then the sync jobs, the schema drift, the transaction that isn't really a transaction because it spans two engines, and the latency the agent pays on every single loop.
SurrealDB as Mastra's storage layer
The first half of the integration is SurrealDBStore, a storage adapter that lets Mastra use SurrealDB as its backend for all of it.
Because SurrealDB is multi-model, one database covers everything a Mastra application persists. Conversation memory, workflow snapshots, scoring and observability data, and native HNSW vector search all live in the same ACID engine, under one query language. There is no separate vector database to deploy, and nothing to keep in sync.
That has a practical consequence beyond operational tidiness. When message history and embeddings sit in the same store, a question that spans both is one query rather than three round trips and a join in application code. The agent asks once and gets an answer.
It can be run locally or on SurrealDB Cloud, and for teams who want to go further than the adapter, raw SurrealQL access is there for custom similarity queries and schema management.
Agent Memory as Mastra's memory provider
The second half is a memory provider backed by SurrealDB Agent Memory.
Storing a transcript is not the same as remembering. An agent that replays a raw message history is spending context on noise, and it still cannot tell you what it concluded three sessions ago. Agent Memory handles the harder part: extracting durable facts from conversations, semantic recall over what it has learned, and a user profile that accumulates across sessions.
The split of responsibilities is the point. Verbatim message history stays in-process, where it is cheap and immediate. The managed service handles fact extraction and intelligent retrieval, and degrades gracefully if it is ever unreachable, so a hosted dependency never takes your agent down with it.
For teams who would rather be explicit than implicit, Agent Memory can also be exposed as ordinary agent tools: store a memory, recall semantically, search documents, retrieve context. The agent decides when to reach for them, and you can see it happen in the trace.
Two halves, or one
The two components work independently, which matters more than it sounds.
Use the storage adapter alone if you want everything Mastra persists in one self-hosted engine and nothing else. Use the memory provider alone if you are happy with your existing storage and just want agents that genuinely remember. Use both and you get the full picture: durable conversation storage in SurrealDB, with fact extraction and semantic recall layered over it, facts and memory sitting next to each other because they are the same store.
Getting started
npm install @surrealdb/mastra-aiPoint it at a SurrealDB instance for storage, or at Agent Memory for the memory provider, or both. The docs have the configuration for each path.
FAQ
Do I need both components? No. They are complementary but independent. Pick either, or both.
Does the storage adapter need a separate vector database? No. Vector search is native to SurrealDB, so embeddings live alongside your messages and workflow state.
Is Agent Memory self-hosted or managed? The memory provider talks to the hosted SurrealDB Agent Memory service. The storage adapter runs against your own SurrealDB instance, self-hosted or on SurrealDB Cloud.
What happens if the memory service is unavailable? The provider degrades gracefully. Verbatim message history is held in-process, so your agent keeps working.
What versions do I need?
SurrealDB v3, Bun 1+ or Node.js 22+, and @mastra/core 1.31.0 or later.
Try it
The Mastra storage guide covers the storage adapter, and the Agent Memory integration guide covers the memory provider and agent tools. Share what you build in Discord.
