Adding Memory to Your Mastra Agent

Large language models are stateless by default. Every API call starts with a clean slate, so the model forgets what you said two seconds ago unless you send the entire conversation history back in the prompt.

Mastra solves this problem with a dedicated memory system. In this lesson, you will connect persistent storage, configure conversation history, and set up working memory for your customer support agent.

Previous lesson: Mastra Tools: Giving Your Agent Tools | Next lesson: Structured Output with Mastra

The Anatomy of Mastra Memory

Mastra divides conversation memory into two distinct operational layers: conversation history and working memory.

Conversation history tracks the raw exchange of messages between the user and the agent. Mastra manages this history through message threads. It fetches the recent turns, appends them to the model context, and saves new replies automatically.

Working memory operates as an active scratchpad. Instead of scanning through dozens of old chat logs, the agent maintains an updated summary of key user facts. Think of working memory like a sticky note attached to a customer file folder. The agent reads the note on every turn and updates it whenever new facts emerge.

Goal: Add persistent thread storage and working memory to your customer support agent so it remembers user details across multiple queries.

Setting Up Persistent Storage with LibSQLStore

Memory requires a backing database to persist across server restarts. Mastra provides @mastra/libsql, which uses an embedded SQLite-compatible engine called LibSQL.

First, install the memory and database packages in your terminal:

bash
Copy

Open src/mastra/index.ts and attach LibSQLStore to the root Mastra instance.

typescript
Copy

Common Mistake: Passing memory options to an agent without adding storage to your Mastra instance causes runtime errors. Agents delegate the actual writing and reading of data to the central storage adapter.

Passing file:./mastra.db writes the data to a local file in your project root. If you want a temporary database for automated tests, you can use :memory: instead.

Threads and Resources

Mastra organizes saved messages using two identifiers: resource and thread.

A resource represents the identity of the user or entity interacting with the system. In your support assistant, a customer ID like customer-42 serves as the resource.

A thread represents a single conversation session. A single customer can open three separate support tickets over a month. Each ticket receives its own distinct thread ID, such as ticket-101 or ticket-102.

When querying the agent, you provide both values inside the call options so Mastra knows which message history to retrieve.

Configuring the Memory Class

You configure memory directly on the agent by instantiating the Memory class from @mastra/memory.

Open src/mastra/agents/support-agent.ts and update your agent definition:

typescript
Copy

The lastMessages option sets how many recent messages Mastra pulls from the database into the model prompt. Setting this to 20 preserves ten complete turns of back-and-forth dialogue while keeping token usage predictable.

The workingMemory configuration instructs Mastra to extract facts matching the template. Every time the customer shares their name or plan, the model automatically revises the template in the background.

Pro Tip: Keep working memory templates short and structured. Markdown lists with clear headers work best because models parse and update them reliably.

Testing Agent Memory in Code

Create a test script named src/test-memory.ts to verify that the agent remembers previous messages within a thread:

typescript
Copy

Execute the script with npx tsx:

bash
Copy

In the second response, the agent answers with your name and plan even though the second prompt did not contain that information.

Quick Insight: You can also inspect stored threads, messages, and working memory drafts visually by running npm run dev and browsing the agents section in Mastra Studio at http://localhost:4111.

Quick Challenge: Open src/test-memory.ts and send a third prompt with a new thread ID such as ticket-2, keeping the resource ID as customer-42. Ask the agent if it remembers your name to see how working memory carries forward across different threads for the same resource.

In the next lesson, Structured Output with Mastra, you will learn how to force your agent to return type-safe JSON objects using Zod schemas.