# How to Add Memory to a TanStack AI Agent with Redis

> **Source:** https://upstash.com/kb/tanstack-ai-memory-redis
> **Date:** 2026-11-11
> **Author(s):** Cahid Arda Oz
> **Topic:** Redis
> **Format:** text/markdown, machine-readable content for agents and LLMs

Add chat history and long-term user memory to a TanStack AI agent with Upstash Redis and the AgentKit TanStack AI adapter.

---

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](https://upstash.com/docs/redis/sdks/agentkit/tanstack-ai). 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](https://upstash.com/docs/redis/sdks/agentkit/tanstack-ai), 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 history | Long-term memory |
| --- | --- | --- |
| Scope | One thread (`threadId`) | One user, across all threads |
| What gets stored | The full transcript, plus runs and pending approvals | Short facts and the user's own messages |
| Who writes it | `withPersistence()`, at the start and end of each run | The model through a `save_memory` tool, and the middleware after each turn |
| How it's read | The client loads the whole thread on mount | A 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:

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

Requires [TanStack AI 1.0 or later](https://upstash.com/docs/redis/sdks/agentkit/tanstack-ai) 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](https://console.upstash.com) 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:

```bash
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:

```ts
// 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](https://tanstack.com/ai/latest/docs/persistence/chat-persistence). 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](https://upstash.com/docs/redis/sdks/agentkit/tanstack-ai#how-to-keep-a-session-index-in-redis), or you can use the [TanStack AI chat persistence tutorial](https://upstash.com/docs/redis/tutorials/tanstack_chat_persistence) 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:

```ts
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:

```text
[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](https://upstash.com/docs/redis/search/introduction). 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:

```text
[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:

```ts
// 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:

```text
[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](https://tanstack.com/ai/latest/docs/memory/adapters) in `@tanstack/ai-memory/redis`, and [lists `upstashMemory()`](https://tanstack.com/ai/latest/docs/memory/adapters#third-party-adapters) 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 HTTP | `ioredis` or node-redis over TCP |
| Where ranking happens | In Redis, with a Redis Search query | In your server process, after loading the scope's records |
| How memories are scored | BM25 full-text with typo tolerance | Word overlap, recency, and importance, plus meaning when you add an embedder |
| Records per scope | Ranked in the database, so no load per turn | [About 10,000](https://tanstack.com/ai/latest/docs/memory/adapters#redis) |
| What gets saved | The user's message, plus facts the model saves with `save_memory` | The user and assistant turn, plus facts from your own `extract` function |
| Also included | Chat persistence, resumable streams, locks, tool caching, rate limiting, RAG tools | Memory 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](https://upstash.com/docs/redis/sdks/agentkit/tanstack-ai), and the source in the [AgentKit repo](https://github.com/upstash/agentkit). You can also read more about resumable streams, locks, and other helpers in the [AgentKit for TanStack AI announcement](https://upstash.com/blog/upstash-agentkit-for-tanstack-ai).

---

This site has a search endpoint: https://context7.com/api/v2/ask?siteKey=ask_4cf2adc7846aa874f833b068&query=<URL-encoded question>. It returns documentation that answers the question, with a source link for each part. No API key is needed. If nothing matches, it says so.
