Overview

Your assistant forgets everything the moment a session ends. A user tells it their name this week; next week it asks again. memoryMiddleware fixes that. It gives a chat() run memory that survives across turns and across sessions.

It works in two moves. Before the model runs, it recalls relevant memory from a pluggable adapter and adds it to the system prompt. After the run finishes, it saves the turn. The save is deferred, so it never blocks streaming.

Reach for it when you need recall across turns or sessions. To keep the last few messages of the same request, just pass them in messages. Memory is overkill for that.

Everything lives in @tanstack/ai-memory: the middleware, the adapter contract, and the built-in and vendor adapters.

Want a copy-paste setup? See the Quickstart. Building an adapter for a backend that isn't shipped? See the Custom Adapter guide.

When to reach for it#

The contract: recall and save#

A memory adapter has one identifier and two verbs. Extraction, ranking, rendering, and storage are all the adapter's job. The middleware never looks inside a record.

// The MemoryAdapter contract, from `@tanstack/ai-memory`:
import type { MemoryAdapter } from '@tanstack/ai-memory'

// The MemoryAdapter contract, from `@tanstack/ai-memory`:
import type { MemoryAdapter } from '@tanstack/ai-memory'

Built-in adapters, each a tree-shakeable subpath:

import { inMemory } from '@tanstack/ai-memory/in-memory'
import { redis } from '@tanstack/ai-memory/redis'

import { inMemory } from '@tanstack/ai-memory/in-memory'
import { redis } from '@tanstack/ai-memory/redis'

Vendor adapters:

import { hindsight } from '@tanstack/ai-memory/hindsight'
import { mem0 } from '@tanstack/ai-memory/mem0'
import { honcho } from '@tanstack/ai-memory/honcho'

import { hindsight } from '@tanstack/ai-memory/hindsight'
import { mem0 } from '@tanstack/ai-memory/mem0'
import { honcho } from '@tanstack/ai-memory/honcho'

See Adapters for every adapter and its options.

How a turn flows#

1. Recall runs before the model, during the run's init phase. adapter.recall(scope, userText) returns memory, and the middleware adds the systemPrompt, toolGuidance, and any tools to the run.
2. Save runs after the stream finishes, deferred through ctx.defer so it never blocks the response. The middleware hands the { user, assistant } turn to adapter.save(scope, turn).

To add telemetry, watch memory in devtools, persist without recalling, or handle failures, see Operating memory.

Scope and security#

MemoryScope is the isolation boundary. It is session-centric, with an optional durable user id:

// The MemoryScope type, from `@tanstack/ai-memory`:
type MemoryScope = {
  sessionId: string
  userId?: string
}

// The MemoryScope type, from `@tanstack/ai-memory`:
type MemoryScope = {
  sessionId: string
  userId?: string
}

Always derive scope on the server from trusted state. Accepting userId from the request body is how one user reads another user's memory. The function form of scope runs per request and only sees what your server attached to the chat context:

import { memoryMiddleware } from '@tanstack/ai-memory'
import type { MemoryAdapter } from '@tanstack/ai-memory'

declare const adapter: MemoryAdapter
declare function getSession(ctx: unknown): { threadId: string; userId: string }

memoryMiddleware({
  adapter,
  scope: (ctx) => {
    const session = getSession(ctx) // your server-validated session
    return { sessionId: session.threadId, userId: session.userId }
  },
})

import { memoryMiddleware } from '@tanstack/ai-memory'
import type { MemoryAdapter } from '@tanstack/ai-memory'

declare const adapter: MemoryAdapter
declare function getSession(ctx: unknown): { threadId: string; userId: string }

memoryMiddleware({
  adapter,
  scope: (ctx) => {
    const session = getSession(ctx) // your server-validated session
    return { sessionId: session.threadId, userId: session.userId }
  },
})

Next steps#

• Quickstart: wire memoryMiddleware into a real chat() call
• Adapters: every adapter's options, with an example of each
• Custom Adapter: implement recall/save for a backend that isn't shipped
• Operating memory: options, telemetry, devtools events, and failure behavior