Supermemory with TanStack Start: A Server-Side Memory Boundary

For a TanStack Start application, put the memory API call behind a server function. TanStack Query can manage client-side fetching and caching, and Router can coordinate navigation, but neither a browser cache nor a route loader should be mistaken for durable user memory.

The security boundary is the server's authenticated session. Keep provider credentials there, derive the memory scope there, and return only information the current user may see.

Name the actual stack

TanStack is a family of libraries. A guide that says only “add memory to TanStack” leaves important questions unanswered: is the application using Start, a separate backend, or a static React frontend? This example concerns Start's server-function boundary. A Query-only app needs an equivalent endpoint on its existing backend.

The Start server-function guide describes request validation and server execution. Authentication remains application-specific; creating a server function does not automatically authenticate a request.

Keep the provider behind an adapter

This helper accepts an already authenticated principal and a provider adapter. It validates the question, constructs an unambiguous tenant/user scope, and passes only that scope to retrieval. It is framework-independent so it can be tested before being wired into a server function.

import { createHash } from "node:crypto";

type Principal = { tenantId: string; userId: string };
type Retriever = (scope: string, question: string) => Promise<string[]>;

export async function recallForUser(
  principal: Principal | null,
  question: unknown,
  retrieve: Retriever,
): Promise<string[]> {
  if (!principal?.tenantId || !principal.userId) {
    throw new Error("Authentication required");
  }
  if (typeof question !== "string" || !question.trim() || question.length > 2000) {
    throw new Error("Question must contain 1–2000 characters");
  }
  const scope = createHash("sha256")
    .update(JSON.stringify([principal.tenantId, principal.userId]))
    .digest("hex");
  return retrieve(scope, question.trim());
}

This example targets a Node-compatible server runtime. For an edge runtime, use its supported cryptography API and preserve the exact scope encoding across environments. Changing the encoding later changes which records the application can retrieve.

Wire it into a Start server function

Use createServerFn with input validation for the question. In its handler, resolve the principal using your application's session middleware, then call recallForUser with an adapter built from the server-side Supermemory client. The Supermemory SDK guide provides the client setup.

Do not accept tenantId, containerTag, or a provider API key as arbitrary form input. If a server function supports an administrator selecting another user's scope, authorize that action explicitly before constructing the principal passed to this helper.

The adapter should return bounded, permitted evidence, not the entire provider response by default. Preserve source IDs when the UI needs citations, and avoid leaking internal metadata that has no purpose in the page.

Treat client caching as a separate layer

A cached response can outlive the server-side memory that produced it. Include the appropriate user scope in client cache keys, clear user-specific state on sign-out, and invalidate affected queries after correction or deletion. Server authorization must still run on each request that reaches the endpoint.

Do not put private recall results into a shared static page or a cache keyed only by the question text. Two users asking “what did we decide?” can require entirely different answers.

Test the boundary before the UI

The local tests cover missing authentication, invalid questions, stable scope construction, and separation when tenants or users differ. A fake retriever records the exact scope passed by the helper. That makes an identity bug visible without a model call.

Then run the real Start route in the deployment runtime: sign in as two fictional users, request the same question, sign out, correct a fact, and repeat. Verify response headers and client-cache invalidation as well as provider behavior. The helper is not a complete authenticated Start application, and no live route or provider request is claimed as tested here.

For the data lifecycle behind the endpoint, use the multi-tenant memory guide.

Connect memory behind your existing sign-in flow: get a Supermemory API key and keep it in the server environment. Wire the retriever into the authenticated Start route, then test the same question as two different users.