Update:Our Privacy Policy has changed

How to Add Memory to a TanStack AI Agent with Redis

Cahid Arda OzCahid Arda Oz
7 min read

Each call to chat() in TanStack AI sees only the messages passed to it. It has no access to previous conversations. So if the user tells the agent "I'm vegetarian" in one conversation and asks for a dinner idea in the next, the agent won't be able to know about the first conversation.

To solve this, TanStack AI 1.0 comes with withPersistence() middleware for chat history and memoryMiddleware() for long term memory. But these middlewares need a persistence store to work with. And the stores TanStack AI ships to get you started only work inside one process. In a serverless environment, requests can land on different instances, so this memory is lost on the next request.

In this post, we connect both middlewares to Upstash Redis with the Upstash AgentKit TanStack AI adapter, run a two-conversation demo, and compare it with the redis() memory adapter that TanStack AI ships.

What memory does a TanStack AI agent need?

TanStack AI agents use two kinds of external memory (memory that's stored outside the model's memory):

  • Chat history: When the user reloads, we want to load the chat thread.
  • Long-term memory: When the user starts a new chat thread, we want to load some facts we know about them.

Middleware loads both on the server before each call to the model.

The two kinds work differently:

Chat historyLong-term memory
ScopeOne thread (threadId)One user, across all threads
What gets storedThe full transcript, plus runs and pending approvalsShort facts and the user's own messages
Who writes itwithPersistence(), at the start and end of each runThe model through a save_memory tool, and the middleware after each turn
How it's readThe client loads the whole thread on mountA search for the memories that match the new message

The transcripts, memories, and the search index over them are all stored in the same Redis database, which is fast enough to read on each turn.

Set up the project

Install AgentKit's TanStack AI adapter with TanStack AI, its persistence and memory packages, and a model provider:

npm install @upstash/agentkit-tanstack-ai @tanstack/ai @tanstack/ai-persistence @tanstack/ai-memory @tanstack/ai-anthropic

Requires TanStack AI 1.0 or later starting from @upstash/agentkit-tanstack-ai@0.3.0. For TanStack AI 0.x, use @upstash/agentkit-tanstack-ai@0.2.0.

Create a Redis database in the Upstash Console and copy its REST URL and token into your environment. Every AgentKit helper reads them with Redis.fromEnv(), so there is no client to set up:

UPSTASH_REDIS_REST_URL="https://..."
UPSTASH_REDIS_REST_TOKEN="..."

Store chat history

upstashPersistence() gives withPersistence() a Redis backend for the transcript of each thread, a record of each run, and pending human-in-the-loop approvals. The route below adds it next to the memory middleware, and adds a GET handler that returns a stored thread:

// app/api/chat/route.ts
import { chat, chatParamsFromRequest, toServerSentEventsResponse } from "@tanstack/ai";
import { anthropicText } from "@tanstack/ai-anthropic";
import { memoryMiddleware } from "@tanstack/ai-memory";
import { reconstructChat, withPersistence } from "@tanstack/ai-persistence";
import { upstashMemory } from "@upstash/agentkit-tanstack-ai/memory";
import { upstashPersistence } from "@upstash/agentkit-tanstack-ai/persistence";
 
declare function getSessionUserId(req: Request): Promise<string>; // your auth provider
declare function userOwnsThread(userId: string, threadId: string): Promise<boolean>;
 
const persistence = upstashPersistence();
const memory = upstashMemory();
 
export async function POST(request: Request) {
  const userId = await getSessionUserId(request);
  const params = await chatParamsFromRequest(request);
  if (!(await userOwnsThread(userId, params.threadId))) {
    return new Response("Forbidden", { status: 403 });
  }
 
  const stream = chat({
    adapter: anthropicText("claude-haiku-5-5"),
    messages: params.messages,
    threadId: params.threadId,
    runId: params.runId,
    ...(params.resume ? { resume: params.resume } : {}),
    middleware: [
      withPersistence(persistence),
      memoryMiddleware({ adapter: memory, scope: { threadId: params.threadId, userId } }),
    ],
  });
  return toServerSentEventsResponse(stream);
}
 
export async function GET(request: Request) {
  const userId = await getSessionUserId(request);
  return reconstructChat(persistence, request, {
    authorize: (threadId) => userOwnsThread(userId, threadId),
  });
}

Note that reconstructChat is available for any request knowing the threadId — unless you pass authorize. Same goes for memory: you should use your auth session (Clerk, Auth.js, Supabase Auth) for the userId, which is the only way to separate one user’s memories from another (don’t take it from the request body).

On the client side, use useChat({ threadId, connection, persistence: true }) which calls this GET handler on mount and paints the stored thread. The above implementation forwards params.resume to enable continuing threads that were paused with a tool approval step.

upstashPersistence() also returns a session index store to facilitate listing chats per user in the sidebar (titles and members). This is documented in the AgentKit docs, or you can use the TanStack AI chat persistence tutorial to set up the client side persistence option.

Give the agent long-term memory

upstashMemory() is a memory adapter for memoryMiddleware().

For each turn, it:

  1. Before the model runs, it searches the user's memories using the new user message, adding the top 5 to the system prompt.
  2. It gives the model access to the save_memory tool for saving relevant facts.
  3. After the response, it saves the user's message as a memory as well.

We ran two separate conversations for the same user. The first one shares two facts, and the second one asks a question that needs them:

import { chat, streamToText } from "@tanstack/ai";
import { anthropicText } from "@tanstack/ai-anthropic";
import { memoryMiddleware } from "@tanstack/ai-memory";
import { upstashMemory } from "@upstash/agentkit-tanstack-ai/memory";
 
const userId = "user-45";
const memory = upstashMemory();
 
async function ask(threadId: string, prompt: string) {
  let saved!: () => void;
  const saveDone = new Promise<void>((r) => (saved = r));
 
  const stream = chat({
    adapter: anthropicText("claude-haiku-5-5"),
    messages: [{ role: "user", content: prompt }],
    threadId,
    middleware: [
      memoryMiddleware({
        adapter: memory,
        scope: { threadId, userId },
        onRecall: ({ result }) => console.log(`[${threadId}] recalled:\n${result.systemPrompt || "(nothing)"}`),
        onSave: () => saved(),
      }),
    ],
  });
 
  const tools: string[] = [];
  async function* watch() {
    for await (const chunk of stream) {
      if (chunk.type === "TOOL_CALL_START") tools.push(chunk.toolCallName);
      yield chunk;
    }
  }
  const { text } = await streamToText(watch());
  await saveDone;
  console.log(`[${threadId}] tools: ${tools.join(", ") || "none"}`);
  console.log(`[${threadId}] answer: ${text}\n`);
}
 
await ask("chat-1", "I'm vegetarian and I live in Lisbon.");
await ask("chat-2", "Suggest a dinner place for me tonight.");

The script waits for onSave because the middleware saves the turn after the response is sent. The output, trimmed:

[chat-1] recalled:
(nothing)
[chat-1] tools: save_memory, save_memory
[chat-1] answer: Got it. I've saved that you're vegetarian and live in Lisbon, so I'll keep that in mind for future suggestions like restaurants, recipes, or travel tips.
 
[chat-2] recalled:
Relevant long-term memory about this user:
- I'm vegetarian and I live in Lisbon. (the user said this)
[chat-2] tools: none
[chat-2] answer: Since you're vegetarian and in Lisbon, here are a few well-known vegetarian-friendly spots to check:
...

Memories are saved as a JSON document in agentkit:tanstackMemory:_._.u.<userId>:<id>. The tenant and namespace are inside the _._. In this case, those values are empty. If you use the Upstash Console, you can see the saved memory in the Data Browser.

By default, the adapter blocks until the search index is ready after each save, which ensures that each memory is available in the very next turn. The total run time is 8.8 seconds without any delay between the two different threads. The second thread didn't include any prompt on diet or location, yet the agent had those pieces of information.

How recall finds the right memories

In the demo above, notice how the model stored the memories "The user is vegetarian." and "The user lives in Lisbon.". When asking about the dinner, neither of them matched. The memory was retrieved based on the user's message itself, which was stored as a memory by the adapter after the first turn.

This demonstrates how upstashMemory() scores the memories inside the database, using Upstash Redis Search. It utilizes BM25 full-text query (a standard text relevance score) with tolerance to typos. This approach doesn't require an embedding model, but relies on some shared terms between the user's message and the memory.

We ran the same two conversations for a second user with message capture turned off, so only the model's saved facts were stored:

[chat-2] recalled: ""
[chat-2] answer: I don't know your location, food preferences, or budget yet, so I can't suggest a specific place. Could you tell me:

Recall uses the latest user message as the query, and a query that matches nothing returns nothing. If each user only has a few dozen memories, you can skip the search and load all of them. The adapter returns every memory for the user when the query is empty, so a small wrapper does it:

// memory.ts
import type { MemoryAdapter } from "@tanstack/ai-memory";
import { upstashMemory } from "@upstash/agentkit-tanstack-ai/memory";
 
const base = upstashMemory({ topK: 50, captureUserMessages: false });
 
// Ignore the user's message and load every memory for the user (up to topK).
export const memory: MemoryAdapter = {
  ...base,
  recall: (scope, _query, options) => base.recall(scope, "", options),
};

With this adapter, the same dinner question got both saved facts:

[chat-2] recalled: "Relevant long-term memory about this user:\n- The user is vegetarian. (you saved this)\n- The user lives in Lisbon. (you saved this)"

The default search works well if the memories exceed the prompt size. But it’s nice to have the option to load them all if the memory list is short.

TanStack AI's redis() adapter vs Upstash AgentKit

TanStack AI ships its own redis() memory adapter in @tanstack/ai-memory/redis, and lists upstashMemory() as a third-party adapter for the same memoryMiddleware(). Both plug in the same way, so the route code does not change. They differ in where the ranking happens:

Upstash AgentKit upstashMemory()TanStack AI redis()
Redis client@upstash/redis over HTTPioredis or node-redis over TCP
Where ranking happensIn Redis, with a Redis Search queryIn your server process, after loading the scope's records
How memories are scoredBM25 full-text with typo toleranceWord overlap, recency, and importance, plus meaning when you add an embedder
Records per scopeRanked in the database, so no load per turnAbout 10,000
What gets savedThe user's message, plus facts the model saves with save_memoryThe user and assistant turn, plus facts from your own extract function
Also includedChat persistence, resumable streams, locks, tool caching, rate limiting, RAG toolsMemory only

TanStack AI also lists various hosted memory providers (Hindsight, mem0, and Honcho) for those wanting a dedicated server to extract and rank memories.

redis() also supports embedding-based scoring if you supply an embedding model.

The main difference is that redis() loads each record in the scope into your process for scoring on each turn, while upstashMemory() uses a single search query to load only the top results.

Which one to use

Use TanStack AI's redis() if you are already running a Redis server accessible to your app over TCP, and you want semantic recall with your own embedding model.

Use Upstash AgentKit if your routes are hosted on serverless or edge runtimes that work best with an HTTP client, or you want transcripts, memories, and search all on the same Upstash Redis database. Recall runs within the database, so your server never loads a user's whole memory on a turn.

For most TanStack AI apps running on serverless environments, this is enough: withPersistence(upstashPersistence()) for chat history, and memoryMiddleware() with upstashMemory() for what the agent knows about the user.

You can find the full API reference in the AgentKit docs, and the source in the AgentKit repo. You can also read more about resumable streams, locks, and other helpers in the AgentKit for TanStack AI announcement.