tanstack-ai-memory-redis

# Redis Memory Adapter Production-grade `recall`/`save` adapter backed by plain Redis (no vector index required). Ranks client-side (lexical + optional cosine + recency + importance). ## Setup Bring your own Redis client. `ioredis` wires in directly; `redis` (node-redis v4+) needs a small wrapper. ### Option A: `ioredis` ```ts import Redis from 'ioredis' import { memoryMiddleware } from '@tanstack/ai-memory' import { redis } from '@tanstack/ai-memory/redis' const client = new Redis(process.env.REDIS_URL ?? 'redis://localhost:6379') const memory = redis({ redis: client, prefix: 'myapp:memory' }) // Resolve scope per request from the server-validated session — never from req.body. function memoryFor(session: { userId: string; threadId: string }) { return memoryMiddleware({ adapter: memory, scope: { threadId: session.threadId, userId: session.userId }, }) } ``` ### Option B: `redis` (node-redis v4+) ```ts import { createClient } from 'redis' import { memoryMiddleware } from '@tanstack/ai-memory' import { redis, fromNodeRedis } from '@tanstack/ai-memory/redis' const client = createClient({ url: process.env.REDIS_URL }) await client.connect() const memory = redis({ redis: fromNodeRedis(client), prefix: 'myapp:memory', }) function memoryFor(session: { userId: string; threadId: string }) { return memoryMiddleware({ adapter: memory, scope: { threadId: session.threadId, userId: session.userId }, }) } ``` node-redis exposes a camelCase API (`sAdd`, `mGet`); `fromNodeRedis` translates it to the lowercase `RedisLike` shape. Passing a raw node-redis client without the wrapper throws `client.sadd is not a function`. `redis()` accepts the same `topK` / `minScore` / `kinds` / `embedder` / `extract` options as `inMemory()`. ## Storage model ```text {prefix}:record:{id} -> JSON record {prefix}:index:{tenantId or _}:{userId or _}:{threadId} -> Set<id> ``` `save` writes the record and adds it to the scope's index set; `recall` loads the set, scores, and renders. Scope values are escaped (`:`, `\`, and `_`) so a delimiter or the unset placeholder inside a dim can't collide two scopes. **Hard cut:** there is no dual-read of older index layouts. If you previously wrote under a different shape (e.g. without `tenantId`), reindex or wipe — old keys are orphaned. Always pass the same `tenantId`/`userId`/`threadId` on write and read: missing optional dims become `_`, so omit ≠ "match any". ## Ranking limits Ranking is client-side: `recall` loads every record for the scope into Node and scores it. Fine up to ~10k records per scope. Beyond that, write a vector-index-aware adapter against the same `recall`/`save` contract. ## Troubleshooting - **Records not visible across processes:** ensure every process uses the same `REDIS_URL` and `prefix`. - **Malformed JSON rows:** a row whose JSON won't parse is skipped on read and **left in place** (never deleted) — the signal is a one-time `console.warn` per bad id. Fix or delete the offending `{prefix}:record:{id}` key to remediate.