Skip to content
Source
Sign inSign up
TanStack/ai
Open History to see the last commit

quickstart.md

174 lines5.5 KB

1---
2title: Quickstart
3id: memory-quickstart
4order: 2
5description: "Add cross-session memory to a TanStack AI chat() call: install the package, pick a recall/save adapter, wire memoryMiddleware, and derive scope server-side."
6keywords:
7 - tanstack ai
8 - memory
9 - quickstart
10 - in-memory adapter
11 - redis adapter
12 - chat middleware
13---
14​
15You have a working `chat()` call and you want it to remember context across turns or
16sessions. By the end of this guide, `memoryMiddleware` recalls relevant memory into the
17prompt and saves each finished turn through a real adapter, scoped safely from your
18server-validated session.
19​
20> Want the full contract first? See the [Overview](./overview).
21​
22## Step 1: Install the package
23​
24```bash
25pnpm add @tanstack/ai-memory
26```
27​
28`@tanstack/ai-memory` ships `memoryMiddleware`, the `MemoryAdapter` contract, and the
29built-in and vendor adapters (each on its own subpath).
30​
31## Step 2: Pick an adapter
32​
33> **In-memory:** `inMemory()` is zero-dependency and stores records in a `Map`. Use it
34> for local development, tests, and single-process demos. Records vanish on restart.
36> **Redis:** `redis({ redis })` persists across restarts and shares state across
37> processes. Bring your own client (`ioredis`, or `redis` via `fromNodeRedis`).
39> **Vendors:** `hindsight()`, `mem0()`, and `honcho()` delegate to a hosted memory service.
40​
41Custom adapters implement the `recall`/`save` contract. See [Custom Adapter](./custom-adapter).
42​
43## Step 3: Wire `memoryMiddleware` into `chat()`
44​
45Start with the in-memory adapter, the fastest path to a working setup:
46​
47```ts
48import { chat } from '@tanstack/ai'
49import { openaiText } from '@tanstack/ai-openai'
50import { memoryMiddleware } from '@tanstack/ai-memory'
51import { inMemory } from '@tanstack/ai-memory/in-memory'
52​
53const memory = inMemory()
54​
55const stream = chat({
56 adapter: openaiText('gpt-5.5'),
57 messages: [{ role: 'user', content: 'Hello' }],
58 middleware: [
59 memoryMiddleware({
60 adapter: memory,
61 scope: { threadId: 'demo-thread', userId: 'alice' },
62 }),
63 ],
64})
65```
66​
67Each turn, the middleware recalls relevant memory into the system prompt (lexical scoring
68by default), then deferred-saves the user and assistant turn after the stream finishes.
69​
70When you're ready to ship, swap the adapter and keep everything else the same:
71​
72```ts
73import Redis from 'ioredis'
74import { memoryMiddleware } from '@tanstack/ai-memory'
75import { redis } from '@tanstack/ai-memory/redis'
76import type { MemoryScope } from '@tanstack/ai-memory'
77​
78declare const scope: MemoryScope // from Step 5
79​
80const client = new Redis(process.env.REDIS_URL ?? 'redis://localhost:6379')
81const memory = redis({ redis: client })
82​
83memoryMiddleware({ adapter: memory, scope })
84```
85​
86> Using a hosted service? Swap `inMemory()` for `hindsight({ user })`, `mem0({ user })`,
87> or `honcho({ user })`. The middleware wiring is identical. The adapter maps
88> `recall`/`save` onto the vendor API.
89​
90## Step 4: Semantic scoring (optional)
91​
92The built-in adapters score lexically by default. Pass an `embedder` for semantic recall
93when scopes grow large or queries don't share keywords with stored text:
94​
95```ts
96import OpenAI from 'openai'
97import { inMemory } from '@tanstack/ai-memory/in-memory'
98​
99const openai = new OpenAI()
100​
101const memory = inMemory({
102 embedder: {
103 async embed(text) {
104 const result = await openai.embeddings.create({
105 model: 'text-embedding-3-small',
106 input: text,
107 })
108 const embedding = result.data[0]?.embedding
109 if (!embedding) throw new Error('embedding request returned no vector')
110 return embedding
111 },
112 },
113})
114```
115​
116## Step 5: Derive scope server-side
117​
118`scope` is the isolation boundary. Static scopes are fine for fixtures, but in any real
119app derive scope per request from server-validated session data, never from the request
120body.
121​
122```ts
123import { chat } from '@tanstack/ai'
124import { openaiText } from '@tanstack/ai-openai'
125import { memoryMiddleware } from '@tanstack/ai-memory'
126import type { ModelMessage } from '@tanstack/ai'
127import type { MemoryAdapter } from '@tanstack/ai-memory'
128​
129// From earlier steps / your auth layer.
130declare const messages: Array<ModelMessage>
131declare const memory: MemoryAdapter
132declare const session: { userId: string; threadId: string }
133declare function getSession(ctx: unknown): { threadId: string; userId: string }
134​
135const stream = chat({
136 adapter: openaiText('gpt-5.5'),
137 messages,
138 context: { session }, // attached by your auth middleware, not from req.body
139 middleware: [
140 memoryMiddleware({
141 adapter: memory,
142 scope: (ctx) => {
143 const session = getSession(ctx)
144 return { threadId: session.threadId, userId: session.userId }
145 },
146 }),
147 ],
148})
149```
150​
151On the client, nothing changes for memory wiring — consume the same stream as any
152other `chat()` endpoint:
153​
154```ts
155import { useChat, fetchServerSentEvents } from '@tanstack/ai-react'
156​
157function Chat() {
158 const { messages, sendMessage, isLoading } = useChat({
159 connection: fetchServerSentEvents('/api/chat'),
160 })
161 // Memory is entirely server-side; the client only sees the usual message stream.
162 return (
163 // render messages, input, sendMessage, isLoading…
164 null
165 )
167```
168​
169## Where to go next
170​
171- [Overview](./overview): the `recall`/`save` contract, scope, and how a turn flows
172- [Adapters](./adapters): every adapter's options, with an example of each
173- [Operating memory](./operating): options, telemetry, devtools events, and failures
174- [Custom Adapter](./custom-adapter): implement `recall`/`save` for a backend that isn't shipped