Redis with the Vercel AI SDK

Give Vercel AI SDK agents session and long-term memory with Redis Agent Memory.

The Vercel AI SDK is a TypeScript toolkit for building AI agents. The @redis/vercel-ai-sdk package adds Redis Agent Memory to those agents. It gives them short-term memory for the current session and long-term memories that follow the user across sessions.

The package works with any host that runs Node.js. Your app doesn't need to be deployed on Vercel. To deploy a Vercel app on a Redis Cloud database instead, see Redis with Vercel.

Requirements

  • Node.js 22 or later
  • AI SDK 7.0.114 or later (7.x), and Zod 4.1.8 or later (4.x)
  • A Redis Agent Memory store, which gives you a store URL, an API key, and a store ID. See Create an Agent Memory service.

The package is server-side only and ships as an ECMAScript module (ESM). Don't load it in a browser bundle, because it needs your API key.

Install and configure

Install the package:

npm install @redis/vercel-ai-sdk

Set these environment variables in your server environment. The package has no default endpoint, so all three are required:

Variable Value
AGENT_MEMORY_URL The HTTP endpoint of your store
AGENT_MEMORY_STORE_ID The ID of your store
AGENT_MEMORY_API_KEY The API key for your store

Then create a memory object once, when your server starts:

import { createRedisAgentMemory } from '@redis/vercel-ai-sdk';

const memory = createRedisAgentMemory({
  serverUrl: process.env.AGENT_MEMORY_URL,
  storeId: process.env.AGENT_MEMORY_STORE_ID,
  apiKey: process.env.AGENT_MEMORY_API_KEY,
});

The factory validates its options but makes no network calls. It accepts these optional settings:

Option Default Description
model None The default AI SDK model object for memory.model(). Model name strings aren't accepted.
scope None A default scope: userId, sessionId, and namespaceId. Other fields throw an error.
allowDeletes false Exposes the deletion tools when true.
namespaceTools false Exposes the namespace administration tools when true.
timeoutMs 30000 The timeout for each HTTP request, in milliseconds.

Choose how the agent uses memory

The package offers two ways to add memory. You can use both in one agent.

Automatic memory Memory tools
Use memory.model() as the agent's model memory.tools() as the agent's tools
Recall Automatic, before each model call The model decides when to search
Recording Automatic, after each model call The model decides what to save, or you add hooks
Best for Continuity with no extra prompting Selective, model-directed memory

Don't combine automatic recording with session hooks or session-write tools for the same interaction. Both record the same events, so you get duplicates.

Use automatic memory

Pass memory.model() as the agent's model. Before each model call, the wrapper restores the session and recalls relevant long-term memories. It injects them as a bounded block of context, marked as untrusted and possibly stale. After the call, it records the user message and each successful assistant step.

import { anthropic } from '@ai-sdk/anthropic';
import { ToolLoopAgent, isStepCount } from 'ai';
import { createRedisAgentMemory } from '@redis/vercel-ai-sdk';

const memory = createRedisAgentMemory({
  serverUrl: process.env.AGENT_MEMORY_URL,
  storeId: process.env.AGENT_MEMORY_STORE_ID,
  apiKey: process.env.AGENT_MEMORY_API_KEY,
  model: anthropic('claude-sonnet-4-5'),
});

async function reply(userId: string, sessionId: string, prompt: string) {
  const agent = new ToolLoopAgent({
    model: memory.model({
      scope: { userId, sessionId },
      assistantId: 'assistant',
    }),
    stopWhen: isStepCount(8),
  });
  return agent.generate({ prompt });
}

Create a new memory.model() result for each request. Don't pass one to an agent that outlives the request.

Memories belong to a userId. Session restore and recording also need a sessionId, and recording needs an assistantId. Resolve the IDs from your authenticated user state, never from model output or user input.

Limits and failure behavior

By default, the wrapper:

  • Recalls up to 5 memories and caps the long-term context at 8,000 characters.
  • Caps the restored session context at 24,000 characters.
  • Applies a one-second deadline to reads and to each write.

Override these defaults with the limits option. A memory failure never replaces a successful model response. To see failures, pass an onDiagnostic callback. Its diagnostics never include prompt, memory, or credential text.

Recording is best-effort. Agent Memory has no idempotency key for appends, so a write that timed out may still have landed. Use collision-resistant session IDs, and handle one request at a time for each session.

If your application already stores the conversation history, set historyMode: 'application' and recording: false. The wrapper then recalls long-term memories but doesn't restore or record session events.

Use memory tools

Call memory.tools() to get a standard AI SDK tool map. The model chooses when to search, save, update, or forget memories. The scope is fixed on your side, so the model can't read or write another user's memories.

const tools = memory.tools({ scope: { userId, sessionId } });

const agent = new ToolLoopAgent({
  model: anthropic('claude-sonnet-4-5'),
  tools,
  activeTools: ['search_memories', 'create_memories', 'update_memory'],
  stopWhen: isStepCount(8),
});

Use activeTools to expose only the tools the agent needs. The main tools are:

Tool Description
search_memories Searches long-term memories with a text query and optional filters.
create_memories Saves one or more long-term memories.
update_memory Changes an existing memory.
get_memory Reads one memory by ID.
get_session_memory Reads a session's events and summary.
add_session_event Adds an event to a session.
start_session Starts a session and adds its first event.
list_sessions Lists sessions.
delete_memories, delete_session_event, delete_session_memory Delete data. Available only when allowDeletes is true.

With namespaceTools: true, the map also includes tools to list, create, update, and delete namespaces, and to move memories between them. For every tool and its parameters, see TOOLS.md in the repository.

Record sessions with hooks

Memory tools don't record the conversation on their own. To save each turn, add the session event hooks to the agent:

const agent = new ToolLoopAgent({
  model: anthropic('claude-sonnet-4-5'),
  tools,
  stopWhen: isStepCount(8),
  onStart: tools.createSessionEventHook({
    role: 'USER',
    actorId: userId,
    onError: error => console.error('USER session save failed:', error.message),
  }),
  onEnd: tools.createSessionEventHook({
    role: 'ASSISTANT',
    actorId: '<your-agent-id>',
    onError: error => console.error('ASSISTANT session save failed:', error.message),
  }),
});

The hook saves the user message before the model starts, and keeps it even if generation fails. It saves the assistant message only when the final text isn't empty. Writes aren't atomic, retried, or deduplicated.

More info

RATE THIS PAGE
Back to top ↑