Mastra memory

Mastra memory: the four layers, their scopes, and what crosses threads

Mastra gives agents four memory features in the @mastra/memory package, each with its own scope, storage requirement, and default. Here is what each one does, which ones reach a new thread, and where a shared vault fits.

Mastra. Sources checked 2026-10-26.

How does Mastra memory work?

Mastra memory lives in the @mastra/memory package and needs a storage adapter such as @mastra/libsql or @mastra/pg. Every call passes a resource id for the user and a thread id for the conversation. Message history is on by default and replays recent messages from the same thread. Three features are opt-in: working memory, a small Markdown or schema block of user facts that is resource-scoped by default; semantic recall, which embeds messages into a vector store and finds past ones by meaning; and observational memory, which Mastra now recommends, where background Observer and Reflector agents compress old history into a dense observation log.

What reaches a brand new thread is narrower than it looks. Resource-scoped working memory and semantic recall with scope: "resource" both work only on specific storage adapters, and observational memory is per thread by default, with resource scope deprecated. All of it is stored in your own Mastra database. When the same context has to reach Claude Code, Codex, ChatGPT, or another service, add a MemoryRouter vault as a tool or an MCP server next to Mastra memory.

Mastra memory features compared

The four features in @mastra/memory and a MemoryRouter vault, per Mastra’s docs and MemoryRouter’s own. Checked 2026-10-26.

Feature	Default	Scope	What it holds
Message history	On	One thread	The last N messages of the conversation, in order. Requires a storage adapter. Source
Working memory	Off until enabled	Resource (default) or thread. Resource scope needs libSQL, PostgreSQL, OracleDB, Upstash, or MongoDB.	A small Markdown template or schema-based JSON block of user facts, injected as a system message. Source
Semantic recall	Off until enabled	Thread or resource. Resource scope needs LibSQL, OracleDB, PostgreSQL, MongoDB, or Upstash.	Past messages found by meaning, via a vector store and an embedder you configure. Source
Observational memory	Off until enabled. Recommended by Mastra.	Thread (default). Resource scope is deprecated.	A compressed observation log that replaces old raw history. Retrieval mode adds a recall tool for other threads of the same resource. Source
MemoryRouter vault	Added by you as tools or an MCP server	One vault per user or per connection, shared across apps and tools	Conversation memory: decisions, preferences, and where work stands, searchable by meaning or date. Source

How Mastra handles memory today

Mastra addresses memory with two ids your code passes on every generate or stream call: resource, a stable id for the user or entity, and thread, the conversation. To recall a conversation you call again with the same pair. Each thread has an owner resource that cannot change after creation, so reusing one thread id for two owners causes query errors. Storage is required for every feature, and Mastra stores the results in the adapter you configure, from libSQL and PostgreSQL to MongoDB.

Working memory is the agent’s scratchpad. Template mode uses replace semantics, so the agent must return the full block on each update. Schema mode merges only the fields the agent sends, and atomic merges across processes are currently supported by @mastra/pg; other adapters merge in the application, which serializes writers inside one process only. Switching working memory between thread and resource scope does not carry memory across, because the two scopes are separate records.

Semantic recall is disabled by default and needs a vector store plus an embedder, unless the store embeds text itself, as MongoDB Automated Embedding does. Defaults are topK 4 with one message before and after each match. Observational memory, added in @mastra/memory 1.1.0, runs an Observer once message history passes 30,000 tokens and a Reflector once observations pass 40,000 tokens by default, so context stays bounded. Mastra suggests keeping facts that must carry across threads in resource-scoped working memory, and turning on retrieval mode so the agent can browse earlier threads.

What Mastra forgets

Mastra memory is built for one application and one database. That is the right design for a framework, and it leaves specific gaps.

Anything filed under a different resource id. A new id scheme, a migration, or a second app gives the same person an empty history.
Cross-thread context on other storage adapters. Mastra supports resource-scoped working memory and resource-scoped recall only on the adapters it lists.
Exact wording after compression. Observational memory swaps observed messages for notes in context, and only retrieval mode lets the agent look up the original wording.
Context from other tools. Claude Code, Codex, ChatGPT, and Cursor cannot read your Mastra database, and your Mastra agent cannot read their memory.

The fix with MemoryRouter

Keep Mastra memory for the live conversation and add a MemoryRouter vault for the record that outlives it. Two routes work: call the memory API from Mastra tools with one key per user, or load MemoryRouter’s remote MCP server through MCPClient.

1
Mint one Memory Key per end user
On your server, create a key per user with POST /v1/keys and store it against your own user id, the same way you already map resource ids. The key opens exactly one vault, so it never reaches the browser.
2
Wrap search and ingest as Mastra tools
Use createTool to call POST /v1/memory/search before answering and POST /v1/memory/ingest after a turn completes, with that user’s key. Recall runs when the agent calls the tool, so mention the tools in the agent instructions.
Memory API calls
```
POST https://api.memoryrouter.ai/v1/memory/search
POST https://api.memoryrouter.ai/v1/memory/ingest
Authorization: Bearer mk_...
```
3
Or connect the MCP server for a personal agent
Mastra’s MCPClient speaks Streamable HTTP and handles OAuth-protected servers with authenticate(). Point it at the MemoryRouter server, pick your vault during sign-in, then store a test fact and read it back from a new thread.
Remote MCP server URL
```
https://mcp.memoryrouter.ai/mcp
```

We have not certified Mastra as a native integration. Treat the two-thread test as the receipt: store a disposable fact with one thread id, ask for it with a new thread id, and check the tool call returned it.

Start a MemoryRouter vault

Per-user vaults and a memory API for your Mastra agents. 14-day free trial.

LangGraph memory

Checkpointers for threads plus a published package for durable, per-user memory.

Vercel AI SDK memory

Agents and message persistence, with a memory provider behind them.

AutoGen memory

A Memory protocol for agents, plus a durable store behind it.

Mastra memory FAQ

What is the difference between Mastra working memory and semantic recall?

Does Mastra memory persist across threads?

What is Mastra observational memory?

Should I replace Mastra memory with MemoryRouter?

How do I keep each customer’s memory separate?

Sources

Sources checked 2026-10-26. Tool behavior changes; check the vendor docs before relying on a detail.