Mastra: The TypeScript Agent Framework and Its Memory
Mastra is an open-source TypeScript framework for building AI agents and the applications around them. It comes from the team that built Gatsby, and its founders announced version 1.0 as stable in early 2026. Mastra is for teams whose product already runs on Node.js. It gives you an agent loop and a workflow engine with four kinds of memory. Memory is where it makes the most design choices, so we cover it in detail.
What is Mastra, in one sentence?
Mastra is a TypeScript framework for building AI agents and workflows with built-in memory, which you run inside your own app or as a standalone server.
The Mastra docs describe it as "a TypeScript framework for building AI agents and applications." The GitHub repository lists model routing across more than 40 providers and a graph-based workflow engine. It also ships built-in evals and observability. The repo showed 29.2k stars when we checked on October 28, 2026.
In the Show HN post announcing 1.0, the team reported over 300,000 weekly npm downloads. It named Replit and PayPal among its production users.
How does Mastra differ from calling a model SDK directly?
Many TypeScript teams start with a model SDK and add pieces as they need them. Mastra bundles those pieces with fixed conventions.
| Concern | Mastra | Model SDK plus your own code |
|---|---|---|
| Agent loop | Agent class with tools and model routing | You write the loop |
| Multi-step processes | Workflow engine with branching, parallel steps and suspend/resume | Your own orchestration |
| Conversation memory | Built in: message history, working memory, semantic recall, observational memory | Your own database code |
| Testing | Scorers and a local Studio UI | Your own harness |
| Deployment | Hono server, or deployers for Vercel, Netlify and Cloudflare | Whatever you build |
| Lock-in | Mastra's APIs and storage schema | Only the SDK |
How does Mastra work?
You define an agent with a model and its tools, then register it on a Mastra instance. Workflows chain steps as a graph and can pause for human approval, then resume from stored state.
For local development, Mastra Studio runs at localhost:4111 when you start the dev server. You can chat with an agent, switch models, watch a workflow run step by step and inspect traces of tool calls. Studio can also attach scorers to evaluate responses.
To ship, mastra build produces a server based on Hono that runs on your own VM or container. For Vercel and similar platforms, use one of the built-in deployers described in the deployment overview. Mastra also sells a hosted platform that runs Studio and your server.
How does Mastra memory work?
Mastra memory is organized around two IDs. A resource is a stable identifier for a user or entity. A thread isolates one conversation. The memory overview says to call the agent with the same resource and thread to recall earlier context. Memory needs a storage provider such as LibSQL or Postgres.
Four memory types sit on top:
| Type | What it keeps | Default scope | On by default? |
|---|---|---|---|
| Message history | The last N messages, in order | Thread | Yes |
| Working memory | Structured user facts, as Markdown or a schema | Resource | No |
| Semantic recall | Past messages retrieved by meaning | Configurable | No |
| Observational memory | A compressed log of observations about the conversation | Thread | No |
Working memory is a block the agent maintains about a user. With a Markdown template, the agent rewrites the whole block on each update. With a schema, updates merge field by field. The agent changes it through an update tool, and you can make it read-only per call. The default scope is the resource, so it follows a user across threads.
Semantic recall embeds messages and retrieves similar ones from the current thread or from all of a user's threads. It is off by default and needs a vector store and an embedder. Two options control it. topK sets how many matches come back, and messageRange sets how many surrounding messages come with each.
Observational memory arrived in version 1.1.0 of the memory package, and the docs mark it as recommended. A background Observer agent reads the conversation and writes a dense observation log that replaces raw history. A Reflector agent condenses that log when it grows. By default the Observer runs at 30,000 message tokens and the Reflector at 40,000 observation tokens. Mastra says observations are typically 5 to 40 times smaller than the history they replace. Those background agents call a model. The default picks Gemini 2.5 Flash when a Google key is set, or otherwise a low-cost model from your main provider.
What should you read in the fine print?
Most performance claims about Mastra come from Mastra. The compression ratio for observational memory is the team's own number, and we found no independent benchmark of it. The download and customer figures come from the team's launch post.
Watch the scope changes. Resource-scoped observational memory is deprecated and will be removed, according to the docs. Mastra points users to resource-scoped working memory or retrieval mode instead. Resource scope also requires a storage adapter that supports Mastra's resources table, such as LibSQL or Postgres.
The license is mixed. The core is Apache-2.0, but enterprise features in the ee directories need a commercial license in production. Before production, check whether any feature you use lives under an ee directory.
The bottom line
Pick Mastra if your agent ships inside a TypeScript app and you want workflows and memory without assembling them yourself. Start with message history plus resource-scoped working memory. Add observational memory once conversations get long enough to strain the context window, and budget for the extra model calls it makes.
How is app memory in Mastra different from memory for your coding agents?
Mastra memory serves the users of the app you build. Its threads and resources hold what your product's agent knows about a customer. There is a second kind of memory in the same project: what your coding agents learn while building it. That includes which storage adapter supports resource scope and why you pinned a model. That knowledge lives in Claude Code or Codex sessions and disappears when they end.
memU handles that second kind. It keeps a shared wiki of readable Markdown files across sessions and hosts. A scheduled background task slices new session logs into jobs, and the agent writes what is worth keeping as memory or skill Markdown. Mastra's observational memory runs its own background model to compress conversations. memU's memory service makes no LLM calls. The judgment stays with the coding agent, and memU stores the Markdown it wrote. All hosts share one backend, so a decision made in Codex is available in Claude Code.
To try the hosted version, which is free and syncs across devices, get an API key from memu.so and send your coding agent one message:
Read https://memu.pro/SKILL.md, follow its instructions to install and configure memU, API Key is
YOUR_MEMU_API_KEY.
The self-hosted setup and the support matrix are in the memU GitHub repository.
FAQ
Is Mastra open source?
Mostly. The core framework is licensed under Apache-2.0. Code in the repository's ee directories uses the Mastra Enterprise License and needs a commercial license for production use.
Does Mastra memory need a database?
Yes. Memory needs a storage provider such as LibSQL or Postgres. Semantic recall also needs a vector store and an embedder.
What is working memory in Mastra?
Working memory is a block of structured facts about a user that the agent keeps up to date. It is a Markdown template or a schema, scoped to the user by default so it carries across conversations.
What is observational memory in Mastra?
It is a memory mode where background Observer and Reflector agents compress the conversation into an observation log. It keeps the context window small for long conversations and is scoped to a thread by default.
Does Mastra work with Next.js?
Yes. Mastra's deployment overview says it can deploy alongside an existing app, with a guide for Next.js on Vercel.