Mastra | Agent frameworks

SurrealDB Agent Memory as a memory provider and tools for Mastra, plus the SurrealDB storage adapter.

@surrealdb/mastra-ai is the SurrealDB integration for Mastra. It ships two things that can be used separately or together: a storage adapter backed by a SurrealDB instance you run, and an SurrealDB Agent Memory memory provider backed by the hosted agent memory service.

Note

Spectron was the project name for SurrealDB Agent Memory. These type names
will be renamed in a future release.

Requirements

Bun 1+ or Node.js 22+
@mastra/core 1.31.0+
For the storage adapter: SurrealDB v3
For SurrealDB Agent Memory: an endpoint, context, and API key

Installation

bun add @surrealdb/mastra-ai

The SurrealDB Agent Memory client ships with zod; install it alongside when you use that subpath:

bun add zod

SurrealDB Agent Memory as a memory provider

SpectronMemory works standalone, with no database required. Verbatim message history is kept in-process while SurrealDB Agent Memory handles fact extraction, semantic recall, and the user profile. Every SurrealDB Agent Memory call is guarded, so a service outage degrades to verbatim-only behaviour rather than breaking the agent loop:

import { Agent } from "@mastra/core/agent";
import { anthropic } from "@ai-sdk/anthropic";
import { SpectronMemory } from "@surrealdb/mastra-ai/spectron";

const agent = new Agent({
    name: "assistant",
    instructions: "You are a helpful assistant with long-term memory.",
    model: anthropic("claude-sonnet-4-5"),
    memory: new SpectronMemory({
        endpoint: process.env.SPECTRON_ENDPOINT!,
        context: process.env.SPECTRON_CONTEXT!,
        apiKey: process.env.SPECTRON_API_KEY!,
    }),
});

Pass a Mastra storage to keep durable verbatim threads, messages, and working memory in SurrealDB, with SurrealDB Agent Memory layered on as the intelligence tier:

import { SurrealDBStore } from "@surrealdb/mastra-ai";

const store = new SurrealDBStore({ id: "spectron-demo", url: "ws://localhost:8000", username: "root", password: "root" });
await store.init();

const memory = new SpectronMemory({
    endpoint: process.env.SPECTRON_ENDPOINT!,
    context: process.env.SPECTRON_CONTEXT!,
    apiKey: process.env.SPECTRON_API_KEY!,
    storage: store, // durable verbatim history; omit to keep it in-process
});

SurrealDB Agent Memory tools

Let an agent call SurrealDB Agent Memory explicitly to store, recall, forget, fetch context, and search documents:

import { Spectron, createSpectronTools } from "@surrealdb/mastra-ai/spectron";

const client = new Spectron({
    endpoint: process.env.SPECTRON_ENDPOINT!,
    context: process.env.SPECTRON_CONTEXT!,
    apiKey: process.env.SPECTRON_API_KEY!,
});

const agent = new Agent({
    name: "assistant",
    instructions: "Use spectronRecall before answering questions about the user.",
    model: anthropic("claude-sonnet-4-5"),
    tools: createSpectronTools(client),
});

The toolset is spectronRemember, spectronRecall, spectronForget, spectronContext, and spectronSearchDocuments. Document helpers ingestDocument and searchDocuments cover RAG.

Note

Isolation is soft under a shared API key: resourceId maps to SurrealDB Agent Memory scopes and labels, not a hard tenant boundary. Use client.onBehalfOf(principal) for stronger isolation. One client is pinned to one SurrealDB Agent Memory context.

SurrealDB storage adapter

Used on its own, SurrealDBStore covers conversation memory, workflow suspend/resume snapshots, scoring, observability, and native HNSW vector search against a SurrealDB instance you run:

import { Mastra } from "@mastra/core/mastra";
import { SurrealDBStore } from "@surrealdb/mastra-ai";

const store = new SurrealDBStore({
    id: "my-store",
    url: "ws://localhost:8000",
    username: "root",
    password: "root",
    namespace: "mastra",
    database: "my_app",
});

const mastra = new Mastra({ agents: { assistant }, storage: store });
await store.init();

It also accepts token auth or a pre-connected Surreal instance.

When to use MCP or the SDK instead

For an MCP-native host, use the MCP server.
To call SurrealDB Agent Memory directly, use the JavaScript SDK.