Vercel AI SDK Agents: How State and Memory Work

The Vercel AI SDK is the TypeScript toolkit most JavaScript teams reach for when they add a model to an app. Version 7 shipped on June 25, 2026. Vercel said then that the SDK had "over 16 million weekly downloads." Its agent story has grown from a loop around generateText into three agent classes with different durability. This guide explains how those classes work and what the SDK keeps between calls. It also covers the memory options the docs list, from Anthropic's memory tool to building your own.

What is the Vercel AI SDK, in one sentence?

The AI SDK is Vercel's open-source TypeScript toolkit for building AI-powered applications and agents with one API across model providers.

The introduction splits it into parts. AI SDK Core covers text generation and tool calls, and it is where agents live. AI SDK UI adds framework-agnostic hooks for chat interfaces. A newer surface, AI SDK Harnesses, runs existing agent harnesses through one API. The npm package is called ai, and the GitHub repository licenses it under Apache-2.0.

How do ToolLoopAgent, WorkflowAgent and HarnessAgent differ?

The three differ most in who owns the loop and what survives a crash.

Sources: the agents overview and WorkflowAgent page. The HarnessAgent status comes from the AI SDK 7 announcement.

How does a ToolLoopAgent work?

You create a ToolLoopAgent with a model and a set of tools. Each tool pairs a zod input schema with an execute function. You call generate with a prompt and get back the final text plus the steps the agent took. The agents overview says the class "handles the loop" along with context management and stopping. Loop control options let you set when it stops and adjust each step before it runs.

AI SDK 7 added two kinds of server-side state. A runtime context is shared agent state that flows through the loop and can change between steps. A tools context gives each tool its own typed values, such as an API key, and hides them from other tools. Vercel's announcement describes the tool context as schema-validated.

For more control, the lower-level generateText function is still there, with a streaming twin. The overview recommends the agent class for most cases and the core functions for tightly structured workflows.

What does the AI SDK keep between calls?

Very little, by design. The docs on message persistence are blunt: your app loads and saves the messages. When a response ends, the SDK hands you the full message list. You write it to your own database. The client sends a chat ID, and the server uses it to load history and save the update.

In production, you can send only the newest message from the client and let the server append it to stored history. That keeps requests small. When stored messages contain tool calls or metadata, the guide says to validate them against your current schemas before reuse. A schema change can otherwise break old chats.

Durable runs with WorkflowAgent

Saved messages restore a conversation. A half-finished agent run needs WorkflowAgent. The WorkflowAgent page says a ToolLoopAgent runs in memory, so a crash loses its progress. WorkflowAgent runs model calls inside durable steps. Tools marked with the 'use step' directive become durable too, with three retry attempts by default. Tool approval requests also survive restarts, so a run can wait for a human and resume later.

Tools without the directive run as plain in-memory functions with no durability. Context values may be replayed, so they must be serializable. Replay does not guarantee exactly-once effects, and the docs recommend idempotency keys for external side effects.

How do you add long-term memory to an AI SDK agent?

The SDK has no built-in long-term memory. Its memory page lists three approaches. The more you build yourself, the more you decide about what gets stored.

The first is a provider-defined tool. Anthropic's memory tool gives Claude a structured interface to a memories directory, and you write the function that stores the data. It is low effort, and the model is trained to use it. It only works with Claude.

Memory provider packages are the middle path. The docs list Letta, Mem0, Supermemory and Hindsight, plus a MongoDB package that targets AI SDK 6. These wrap an external service, so storage and retrieval happen without you defining tools. The page names the cost: the provider controls how memory behaves, and you depend on its service.

A custom tool means building storage and retrieval yourself, and the docs describe two patterns for it. One exposes explicit actions that you validate. The other gives the model sandboxed shell commands over memory files and needs command validation. It is the most work and carries no provider lock-in.

Which option should you pick?

For a chat app with signed-in users, start with message persistence plus a memory provider. That gives you per-user recall without writing retrieval code. If you only use Claude, the memory tool is the cheapest path, and the files stay in storage you control. Pick a custom tool when memory is core to the product and you want to own the format.

Add WorkflowAgent once runs get long or need human approval. A crash halfway through a long run is expensive to repeat. We found no independent benchmark comparing these memory options inside the AI SDK, so test recall on your own data.

The bottom line

The AI SDK gives TypeScript teams a well-built agent loop and leaves storage to them. Start with ToolLoopAgent and store messages yourself from day one. Move long or approval-gated runs to WorkflowAgent. For memory, pick a provider if you want it working this week, and a custom tool if the memory format is part of your product.

How do you keep memory across the agents you code with?

The options above give your app's users memory. The developer building the app has a separate problem. Claude Code and Codex each start a session without what the other learned about the project. Each host keeps its own notes in its own format.

memU is a shared memory for those coding agents. A scheduled background task slices new session logs into jobs. The agent distills them into memory and skill Markdown, and memU commits the files. memU's memory service makes no LLM or chat calls. It stores and embeds the Markdown the agent prepared, then retrieves it. A standing instruction in CLAUDE.md or AGENTS.md tells the agent to retrieve before answering. All hosts share one backend, so a convention that Codex learned about your AI SDK routes is there when you open Claude Code.

The hosted version on memu.so is free and syncs across devices. Get an API key there and send your 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

Does the Vercel AI SDK store chat history for you?

No. The docs say your app loads and saves messages. The SDK passes you the complete message list when a response ends, and you write it to your own storage.

What is ToolLoopAgent in the AI SDK?

It is the recommended agent class. Given a model and tools, it runs the tool-calling loop and decides when to stop.

How do I make an AI SDK agent survive a restart?

Use WorkflowAgent from the AI SDK's workflow package. It runs on the Workflow DevKit runtime and reuses completed steps on replay, so a restarted run continues where it stopped.

Which memory providers work with the AI SDK?

The docs name Letta and Mem0 among four providers, plus a MongoDB package. Claude models can also use Anthropic's memory tool.

Is the Vercel AI SDK free to use?

Yes. The ai package on npm is open source under Apache-2.0. You still pay your model provider for tokens.