Scope

Defined in: packages/ai/src/scope.ts:22

Shared identity/isolation scope for the TanStack AI subsystems that persist or recall per-conversation data — @tanstack/ai-persistence (keyed CRUD over threads, runs, interrupts) and @tanstack/ai-memory (ranked recall/save).

Both subsystems answer the same underlying question — "whose data is this?" — so they share ONE identity vocabulary defined here rather than each inventing its own. threadId is the single conversation key across the codebase (it is ChatMiddlewareContext.threadId); a subsystem must never introduce a second name (sessionId, conversationId, …) for the same concept.

Security#

A Scope is an isolation boundary. Derive every field server-side from trusted, validated session state — never from client input. threadId in particular resolves from a client-supplied value on the request, so a subsystem that reads/writes user-owned data (memory, per-user metadata) must pair it with a server-trusted userId/tenantId and must not treat a bare client threadId as sufficient isolation: thread ids are guessable, so on their own they let one caller read another's data.

Properties#

namespace?#

optional namespace?: string;

Defined in: packages/ai/src/scope.ts:45

Logical partition within a tenant/user (e.g. separating distinct memory banks or persistence namespaces). Reserved — no subsystem keys on it yet; adapters that don't understand it must ignore it rather than error.

tenantId?#

optional tenantId?: string;

Defined in: packages/ai/src/scope.ts:39

Tenant/organization boundary for multi-tenant deployments. When present, every read and write must be confined to it.

threadId#

threadId: string;

Defined in: packages/ai/src/scope.ts:28

The conversation this data belongs to. Required — the minimal isolation key both subsystems already center on. Same concept as ChatMiddlewareContext.threadId.

userId?#

optional userId?: string;

Defined in: packages/ai/src/scope.ts:34

Durable end-user identity, for cross-thread recall and per-user isolation. Optional, but required in practice for any multi-user deployment — a threadId alone is not an authorization boundary (see Security above).