Mastra
Build Mastra agents with persistent storage using Recall and @mastra/core.
This guide demonstrates how to integrate Recall's persistent storage capabilities with the Mastra
agent framework using the @mastra/core
and @mastra/mcp
packages. This approach focuses on
directly configuring and running agents with tools provided by MCP (Model Context Protocol) servers.
Overview
Mastra is a TypeScript framework for building AI agents. By integrating
Recall's decentralized storage via its MCP server (@recallnet/mcp
), you can empower your Mastra
agents to:
- Store and retrieve data, findings, or state persistently across runs.
- Utilize Recall buckets for organized data management.
- Leverage Recall's verifiable storage within your agent's operations.
This guide uses @mastra/core/agent
for agent definition and @mastra/mcp
to manage the connection
to the @recallnet/mcp
tool server.
For the latest Mastra features and documentation, always refer to the official Mastra documentation.
Prerequisites
- Node.js (v18 or later recommended)
- pnpm (or npm/yarn)
- A Recall Network private key (get one from Recall)
- An API key for your chosen Language Model (e.g., Anthropic, OpenAI)
Installation
Install required packages
Ensure you have the necessary Mastra and Recall packages, along with supporting libraries:
Or, replace @ai-sdk/anthropic
with your preferred provider, e.g., @ai-sdk/openai
.
Note: @types/node
is needed for Node.js specific types like process
.
Create TypeScript Configuration
Ensure you have a tsconfig.json
file configured for your project. A basic example:
Ensure "types": ["node"]
is included if you face issues with Node.js globals like process
.
Basic integration example
This example shows how to create a simple agent that uses Recall tools provided by @recallnet/mcp
.
We'll set up the agent configuration, environment variables, and enable the Recall tools in Mastra.
Scaffold the basic agent
First, create a src/agent.ts
file and set up our basic logic.
Add the Recall tools
Next, we'll initialize MCP Configuration for Recall Server, which tells Mastra how to run the
@recallnet/mcp
server. Then, we'll get the toolsets from the MCP server and pass them to the
agent, before running it with pre-defined instructions.
Running the agent
-
Save the code above as
src/agent.ts
. -
Ensure your
.env
file is correctly populated with your keys. -
Run the agent using
tsx
(or compile withtsc
and run the JS file):
You should see output showing the agent starting, initializing the Recall MCP server, making tool
calls (get_or_create_bucket
, add_object
), receiving results, and finally confirming the
operation. You can verify the bucket and object creation in your Recall dashboard.
Explanation
@mastra/core/agent
: Provides the fundamentalAgent
class for defining the agent's identity, instructions, and the model it uses.@mastra/mcp
: TheMCPConfiguration
class manages the lifecycle (startup, shutdown) of external MCP tool servers like@recallnet/mcp
. It retrieves the tools (toolsets
) defined by these servers.@recallnet/mcp
: This is the MCP server process that exposes Recall's functionalities (like managing buckets and objects) as tools that the Mastra agent can call.agent.stream(messages, { toolsets })
: This is the core execution call. We pass the conversation history (messages
) and the availabletoolsets
. The Mastra agent, guided by its instructions and the user prompt, decides when to call the Recall tools provided in thetoolsets
.
This approach directly leverages MCP for tool integration without needing the abstractions (like
Task
, Workflow
) present in the outdated guide's examples.
Next steps
- Explore the different tools exposed by
@recallnet/mcp
(check its documentation or prompt the agent to list available tools). - Build more complex prompts that require retrieving or querying data from Recall.
- Integrate other MCP servers alongside Recall for more diverse agent capabilities.
- Implement more robust output parsing and state management for multi-turn conversations.