@tanstack/ai-memory 0.0.0

package/src/providers/redis/index.ts

@@ -0,0 +1,179 @@
+import {
+  inspectRecords,
+  isExpired,
+  listRecordFacts,
+  recallRecords,
+  saveTurn,
+} from '../../internal/store'
+import type {
+  BuiltinOptions,
+  MemoryRecord,
+  RecordStore,
+} from '../../internal/store'
+import type { MemoryAdapter, MemoryScope } from '../../types'
+
+/**
+ * Minimal subset of the Redis client API the adapter uses. Shaped to match
+ * `ioredis` directly (lowercase method names). For node-redis v4+'s camelCase
+ * API, wrap the client with {@link fromNodeRedis}.
+ */
+export interface RedisLike {
+  set: (key: string, value: string) => Promise<unknown>
+  get: (key: string) => Promise<string | null>
+  del: (...keys: Array<string>) => Promise<unknown>
+  sadd: (key: string, ...members: Array<string>) => Promise<unknown>
+  srem: (key: string, ...members: Array<string>) => Promise<unknown>
+  smembers: (key: string) => Promise<Array<string>>
+  mget: (...keys: Array<string>) => Promise<Array<string | null>>
+}
+
+/** node-redis v4+ default-mode (camelCase) surface used by {@link fromNodeRedis}. */
+export interface NodeRedisLike {
+  get: (key: string) => Promise<string | null>
+  set: (key: string, value: string) => Promise<unknown>
+  del: (keys: Array<string> | string) => Promise<number>
+  sAdd: (key: string, members: string | Array<string>) => Promise<number>
+  sRem: (key: string, members: string | Array<string>) => Promise<number>
+  sMembers: (key: string) => Promise<Array<string>>
+  mGet: (keys: Array<string>) => Promise<Array<string | null>>
+}
+
+/**
+ * Wrap a node-redis v4+ default-mode client (camelCase API) into the lowercase
+ * {@link RedisLike} shape this adapter expects. For `ioredis`, no wrapper is
+ * needed — pass the client directly.
+ */
+export function fromNodeRedis(client: NodeRedisLike): RedisLike {
+  return {
+    get: (key) => client.get(key),
+    set: (key, value) => client.set(key, value),
+    del: (...keys) => client.del(keys),
+    sadd: (key, ...members) => client.sAdd(key, members),
+    srem: (key, ...members) => client.sRem(key, members),
+    smembers: (key) => client.sMembers(key),
+    mget: (...keys) => client.mGet(keys),
+  }
+}
+
+export interface RedisOptions extends BuiltinOptions {
+  /** A Redis client implementing {@link RedisLike} (ioredis, or wrapped node-redis). */
+  redis: RedisLike
+  /** Key prefix. Defaults to `'tanstack-ai:memory'`. */
+  prefix?: string
+}
+
+/**
+ * Escape the `:` scope-key delimiter (and the `\` escape character itself) in a
+ * scope value before composing the colon-joined key. Without this, a scope
+ * value containing `:` could shift segment positions and collide two different
+ * scopes' index buckets. `_` is escaped too so a literal `_` value can't collide
+ * with the unset-key placeholder.
+ */
+function escapeScopeValue(value: string): string {
+  return value.replace(/[\\:_]/g, '\\$&')
+}
+
+// Track ids we've warned about so ongoing corruption of DIFFERENT ids keeps
+// surfacing, bounded so a pathological store can't spam the console forever.
+const warnedMalformedIds = new Set<string>()
+const MALFORMED_WARN_CAP = 100
+function warnMalformedRow(id: string, err: unknown): void {
+  if (
+    warnedMalformedIds.has(id) ||
+    warnedMalformedIds.size >= MALFORMED_WARN_CAP
+  ) {
+    return
+  }
+  warnedMalformedIds.add(id)
+  console.warn(
+    `[tanstack-ai-memory] redis: skipped malformed record JSON (id=${id}). ` +
+      `The row is left in place (not deleted) in case it is recoverable. ` +
+      `Reason: ${String(err)}`,
+  )
+}
+
+/**
+ * Production memory adapter backed by plain Redis (no vector index required).
+ * Ranks client-side (lexical + optional cosine + recency + importance), so it's
+ * suited to up to ~10k records per scope. Bring your own client (`ioredis`, or
+ * node-redis wrapped with {@link fromNodeRedis}).
+ *
+ * Storage model:
+ * ```text
+ * {prefix}:record:{id}                                          -> JSON MemoryRecord
+ * {prefix}:index:{tenantId or _}:{userId or _}:{threadId}       -> Set<id>
+ * ```
+ * Segments are escaped (so `:`, `\\`, `_` in values cannot collide). Missing
+ * optional dims become `_` (omit ≠ match any — same exact-match model as the
+ * built-in `sameScope` helper). No dual-read of older index layouts.
+ */
+export function redis(options: RedisOptions): MemoryAdapter {
+  const client = options.redis
+  const prefix = options.prefix ?? 'tanstack-ai:memory'
+
+  const scopeKey = (scope: MemoryScope): string => {
+    const tenant =
+      scope.tenantId != null && scope.tenantId !== '' ? scope.tenantId : '_'
+    const user =
+      scope.userId != null && scope.userId !== '' ? scope.userId : '_'
+    return `${escapeScopeValue(tenant)}:${escapeScopeValue(user)}:${escapeScopeValue(scope.threadId)}`
+  }
+  const indexKey = (scope: MemoryScope): string =>
+    `${prefix}:index:${scopeKey(scope)}`
+  const recordKey = (id: string): string => `${prefix}:record:${id}`
+
+  const store: RecordStore = {
+    async add(batch) {
+      const now = Date.now()
+      for (const r of batch) {
+        const next: MemoryRecord = { ...r, updatedAt: now }
+        await client.set(recordKey(r.id), JSON.stringify(next))
+        await client.sadd(indexKey(r.scope), r.id)
+      }
+    },
+
+    async loadScope(scope: MemoryScope) {
+      const idx = indexKey(scope)
+      const ids = await client.smembers(idx)
+      if (ids.length === 0) return []
+      const raws = await client.mget(...ids.map(recordKey))
+      const out: Array<MemoryRecord> = []
+      const stale: Array<string> = []
+      for (let i = 0; i < raws.length; i++) {
+        const raw = raws[i] as string | null
+        const id = ids[i] as string
+        if (!raw) {
+          stale.push(id)
+          continue
+        }
+        let record: MemoryRecord
+        try {
+          record = JSON.parse(raw) as MemoryRecord
+        } catch (err) {
+          // Malformed JSON is skipped, NOT swept — a parse failure isn't proof
+          // the data is unrecoverable (truncated read, older schema, etc.).
+          warnMalformedRow(id, err)
+          continue
+        }
+        if (isExpired(record)) {
+          stale.push(id)
+          continue
+        }
+        out.push(record)
+      }
+      if (stale.length > 0) {
+        await client.srem(idx, ...stale)
+        await client.del(...stale.map(recordKey))
+      }
+      return out
+    },
+  }
+
+  return {
+    id: 'redis',
+    recall: (scope, query) => recallRecords(store, scope, query, options),
+    save: (scope, turn) => saveTurn(store, scope, turn, options),
+    inspect: (scope) => inspectRecords(store, scope),
+    listFacts: (scope) => listRecordFacts(store, scope),
+  }
+}

package/src/types.ts

@@ -0,0 +1,159 @@
+/**
+ * Public contract for the TanStack AI memory subsystem.
+ *
+ * A memory backend implements ONE contract with two verbs: {@link MemoryAdapter.recall}
+ * and {@link MemoryAdapter.save}. This is deliberately the shape every real memory
+ * provider (mem0, honcho, hindsight, …) already exposes — "what's relevant for this
+ * query?" and "remember this turn". The middleware ({@link memoryMiddleware}) is thin:
+ * it calls `recall` before the model runs and defers `save` after the turn finishes.
+ *
+ * Adapters own everything else. Extraction (turning a turn into stored facts),
+ * ranking, rendering into a prompt, scope isolation, and expiry are all the
+ * adapter's responsibility — the middleware never inspects records. The built-in
+ * `inMemory()` / `redis()` adapters keep their store/scoring internals private
+ * behind `recall`/`save`; vendor adapters map these two verbs onto their APIs.
+ */
+
+import type { Scope, Tool } from '@tanstack/ai'
+
+// ===========================
+// Scope & turn primitives
+// ===========================
+
+/**
+ * Isolation scope for memory reads and writes. Alias of the shared {@link Scope}
+ * identity type from `@tanstack/ai` so memory and persistence share one
+ * vocabulary (`threadId`, optional `userId` / `tenantId` / `namespace`).
+ *
+ * Opaque to the middleware — each adapter interprets it (vendors map it to
+ * bank/user ids; the built-in stores key their internal record space by it).
+ *
+ * Resolve every field server-side from trusted session/auth state. A client-
+ * originated `threadId` is only safe after you validate it belongs to the
+ * session user; never accept bare `userId`/`tenantId` from the request body.
+ */
+export type MemoryScope = Scope
+
+/** A completed conversation turn handed to {@link MemoryAdapter.save}. */
+export interface MemoryTurn {
+  user: string
+  assistant: string
+}
+
+// ===========================
+// Recall
+// ===========================
+
+/** A discrete recalled item, when the adapter produces them. */
+export interface MemoryFragment {
+  /** The recalled text. */
+  text: string
+  /** Provenance hint (record id, vendor result type, etc.). */
+  source: string
+}
+
+/**
+ * Result of {@link MemoryAdapter.recall}. Everything the middleware needs to
+ * augment the run: a pre-rendered prompt block, optional discrete fragments,
+ * and optional tools the adapter wants exposed to the model this turn.
+ */
+export interface RecallResult {
+  /**
+   * Pre-rendered block to inject into the system prompt. An empty string means
+   * "nothing to inject" — the middleware skips it.
+   */
+  systemPrompt: string
+  /**
+   * Discrete recalled items, when the adapter produces them. Omitted for
+   * engines that return synthesized output (e.g. honcho's dialectic answer).
+   */
+  fragments?: Array<MemoryFragment>
+  /**
+   * Tools the adapter wants exposed to the model for this turn (e.g. hindsight's
+   * retain/recall/reflect tools). Merged into the run's tool set by the
+   * middleware. Omit or `[]` when the adapter exposes no tools.
+   */
+  tools?: Array<Tool>
+  /**
+   * System-prompt text explaining when/how to use {@link RecallResult.tools}.
+   * Injected ahead of `systemPrompt`. Omit or `''` when there are no tools.
+   */
+  toolGuidance?: string
+  /** Raw vendor payload, surfaced for devtools/inspection. */
+  raw?: unknown
+}
+
+// ===========================
+// Save
+// ===========================
+
+/**
+ * Receipt for a single underlying write performed by {@link MemoryAdapter.save}.
+ * One turn can produce several receipts (e.g. hindsight writes the user and
+ * assistant utterances separately), so `save` returns an array.
+ */
+export interface SaveReceipt {
+  ok: boolean
+  /** Optional adapter-reported write latency (ms), for devtools. */
+  latencyMs?: number
+  /** Present when `ok` is `false`. */
+  error?: string
+  /** Raw vendor payload, surfaced for devtools/inspection. */
+  raw?: unknown
+}
+
+// ===========================
+// Optional introspection (devtools / admin panels)
+// ===========================
+
+/** Full snapshot returned by the optional {@link MemoryAdapter.inspect}. */
+export interface MemorySnapshot {
+  /** ISO timestamp when the snapshot was taken. */
+  takenAt: string
+  /** Adapter-defined snapshot payload. */
+  data: unknown
+}
+
+/** A flat fact row returned by the optional {@link MemoryAdapter.listFacts}. */
+export interface MemoryFact {
+  id: string
+  text: string
+  source?: string
+  /** ISO timestamp, when the adapter tracks creation time. */
+  createdAt?: string
+}
+
+// ===========================
+// Adapter contract
+// ===========================
+
+/**
+ * The single memory adapter contract. All backends — the built-in `inMemory()`
+ * and `redis()` adapters as well as vendor adapters (`hindsight()`, `mem0()`,
+ * `honcho()`) — implement `recall` + `save`. `inspect`/`listFacts` are optional
+ * and exist only for devtools/admin surfaces.
+ */
+export interface MemoryAdapter {
+  /** Stable id used in logs, devtools, and event payloads (e.g. 'in-memory', 'hindsight'). */
+  readonly id: string
+  /** Optional human-readable label; defaults to {@link MemoryAdapter.id} in logs. */
+  readonly name?: string
+
+  /**
+   * Read side — retrieve what's relevant to `query` within `scope`. The ranking
+   * strategy (lexical, semantic, hybrid, vendor-native) is entirely the
+   * adapter's concern.
+   */
+  recall: (scope: MemoryScope, query: string) => Promise<RecallResult>
+
+  /**
+   * Write side — persist a completed turn. Extraction (turn → stored facts)
+   * happens HERE, inside the adapter. Returns one receipt per underlying write.
+   */
+  save: (scope: MemoryScope, turn: MemoryTurn) => Promise<Array<SaveReceipt>>
+
+  /** Optional — full snapshot for a devtools inspection panel. */
+  inspect?: (scope: MemoryScope) => Promise<MemorySnapshot>
+  /** Optional — flat fact list for a devtools panel. */
+  listFacts?: (scope: MemoryScope) => Promise<Array<MemoryFact>>
+}