Open History to see the last commit
1---
2title: Operating
3id: memory-operating
4order: 5
5description: "Run memoryMiddleware in production: configure its options, add onRecall/onSave telemetry, watch recall and save in devtools, and rely on non-fatal failure handling that never breaks a chat run."
6keywords:
7 - tanstack ai
8 - memory
9 - middleware options
10 - telemetry
11 - devtools
12 - observability
13 - save-only
14---
15
16Memory is wired into your `chat()` call. Now you want to see whether it actually recalls
17anything, get that activity into your own logs, and know that a slow or broken store
18won't take down the chat. This page covers the middleware's options and how to observe
19and operate it.
20
21New to memory? Start with the [Overview](./overview) and [Quickstart](./quickstart) first.
22
23## `memoryMiddleware` options
24
25| Option | Type | Default | Purpose |
26|--------|------|---------|---------|
27| `adapter` | `MemoryAdapter` | (required) | The backend to `recall` from and `save` to. |
28| `scope` | `MemoryScope \| (ctx) => MemoryScope` | (required) | Isolation scope, static or derived per request. |
29| `role` | `'recall+save' \| 'save-only'` | `'recall+save'` | `'save-only'` persists turns without recalling or injecting. |
30| `onRecall` | `({ scope, query, result }) => void` | none | App telemetry after each `recall`. |
31| `onSave` | `({ scope, turn, receipts }) => void` | none | App telemetry after each deferred `save`. |
32
33Every option in one place:
34
35```ts
36import { memoryMiddleware } from '@tanstack/ai-memory'
37import { inMemory } from '@tanstack/ai-memory/in-memory'
38
39const mw = memoryMiddleware({
40 adapter: inMemory(),
41 // Function form derives scope per request. `ctx.threadId` is the stable
42 // per-conversation id; add `userId` from your server-validated session.
43 scope: (ctx) => ({ threadId: ctx.threadId }),
44 role: 'recall+save', // or 'save-only' to persist without injecting
45 onRecall: ({ query, result }) => {
46 console.log('recalled', result.fragments?.length ?? 0, 'hits for', query)
47 },
48 onSave: ({ receipts }) => {
49 console.log('saved', receipts.filter((r) => r.ok).length, 'records')
50 },
51})
52```
53
54## Persist without recalling
55
56By default the middleware both recalls and saves (`role: 'recall+save'`). Set
57`role: 'save-only'` to persist each turn without reading memory back or injecting anything
58into the prompt. Use it to build up a user's history before you turn recall on, or on
59routes where you want to record turns but not shape the current answer.
60
61## Telemetry with onRecall and onSave
62
63The devtools events below are for watching memory during development. For telemetry that
64ships with your app, use the `onRecall` and `onSave` callbacks shown above. `onRecall`
65fires after each recall with the query and result, so you can count hits. `onSave` fires
66after each deferred save with the write receipts, so you can count writes. Send those to
67your metrics client instead of `console.log`.
68
69## Watch it in devtools
70
71The AI DevTools has a **Memory** tab for any chat wired with `memoryMiddleware`. It
72shows each turn's recall (query, fragment count, characters injected, recall duration)
73and, for adapters that implement `inspect`/`listFacts` (the built-in `inMemory()` and
74`redis()` do), the current stored records and facts. See the
75[Memory Inspector](../getting-started/devtools#memory-inspector) for what it renders and
76how server-side memory reaches the panel.
77
78Under the hood the middleware emits these events on `aiEventClient` (from
79`@tanstack/ai-event-client`). The panel reads them, and you can subscribe directly:
80
81| Event | When |
82|-------|------|
83| `memory:retrieve:started` | Recall begins |
84| `memory:retrieve:completed` | Recall returns (fragment count, whether tools were injected) |
85| `memory:persist:started` | A deferred save begins |
86| `memory:persist:completed` | A save completes (receipt count) |
87| `memory:error` | A `recall` or `save` threw (`phase: 'recall'` or `'save'`). Carries `scope` only when it was already resolved; omitted if the resolver failed or never ran. |
88
89## Failures are non-fatal
90
91A memory failure never breaks a chat run. A throwing `recall` or `save` emits
92`memory:error` and the run continues with degraded memory: recall returns nothing, and a
93failed save is dropped. Streaming is never blocked, and a failed save never fails the
94turn. This means a flaky store degrades the experience instead of taking down the chat.
95
96## Where to go next
97
98- [Overview](./overview): the `recall`/`save` contract and how a turn flows
99- [Adapters](./adapters): every adapter's options, with an example of each
100- [Custom Adapter](./custom-adapter): implement `recall`/`save` for a backend that isn't shipped