createClient & the Recall class

The factory comes in four overloads so common cases stay one-liners:

createClient();                                              // env vars
createClient('https://api.recall.dev');                       // url only
createClient('https://api.recall.dev', process.env.RECALL_API_KEY!); // url + key
createClient({ url, apiKey, timeoutMs: 30_000 });              // full options

All four resolve to the same internal createRecall(...) factory, which builds an HttpTransport and constructs a Recall from it.

createClient(options)

function createClient(): Recall;
function createClient(url: string): Recall;
function createClient(url: string, apiKey: string): Recall;
function createClient(options: CreateClientOptions): Recall;

Options

Errors thrown synchronously

createClient() is the rare SDK function that throws synchronously — most others reject. The synchronous throws cover misconfiguration:

When to use which overload

The four overloads exist to keep the common case short while leaving room for full configuration. Reach for the URL-only or URL+key forms in scripts and tests where you want one line. Reach for the options form once you need timeouts, retries, telemetry, or a custom API version.

The zero-argument form is convenient in serverless functions where RECALL_BASE_URL and RECALL_API_KEY come from the platform's secret manager — you spend zero lines wiring environment variables into the constructor.

The Recall class

createClient() returns an instance of Recall. The class has two responsibilities: it owns the transport and exposes the resource handles. Every public method is documented on its own page in this section.

class Recall {
  // data plane
  readonly memory: Memory;     // get / list / patch — see /sdk-typescript/memories
  readonly entity: Entity;     // get / search       — see /sdk-typescript/entities

  // admin plane (requires API key with admin scope)
  readonly agents: Agents;     // create / list / get / patch / delete / stats
  readonly keys: ApiKeys;      // create / list / get / delete / rotate
  readonly org: Org;           // profile / members / plan

  // top-level pipeline methods
  remember(input, options?): Promise<RememberResult>;        // streaming overload available
  search(input, options?):   Promise<SearchResult>;          // streaming overload available
  context(input, options?):  Promise<BuildContextResult>;
  correct(id, correction, options?): Promise<CorrectResult>;
  explain(id, options?):     Promise<MemoryExplanation>;
  forget(input, options?):   Promise<ForgetResult>;
  health(options?):          Promise<HealthResult>;

  // per-request user identity
  forUser(userId: string): Recall;

  // SSR rebind
  withScope(opts: WithScopeOptions): Recall;
}

You should think of recall.remember(), recall.search(), recall.correct(), recall.explain(), and recall.forget() as the pipeline operations — each one runs through the server's typed pipeline and produces a structured outcome. recall.memory.get / list / patch and recall.entity.get / search are the escape hatches — direct CRUD on the underlying tables, useful for dashboards and admin tools.

recall.agents, recall.keys, and recall.org are the admin plane — operations that manage the identity and tenancy infrastructure rather than memories themselves. They require an API key with admin permission scope (the key's bound user must have admin or owner role in the org). If you call these from a key without admin scope, you receive 403 FORBIDDEN.

recall.context() is the context aggregator — a single endpoint that returns a Markdown prompt section ready to inject into an LLM system prompt, plus a structured per-category breakdown for programmatic use.

forUser() — per-request user identity

recall.forUser(userId) returns a new Recall instance that sends X-Recall-User-ID: userId on every request. One API key serves many end-users; the user being served is specified per-request.

recall.forUser(userId: string): Recall

// One key, many users
const recall = createClient({ url, apiKey: process.env.RECALL_API_KEY });

// In your request handler:
const alice = recall.forUser(req.user.id);
await alice.remember({ messages });
await alice.search({ query: 'what does alice prefer?' });

The returned client shares the parent's HTTP config (connection pool, timeout, retries) — no new connections are opened. forUser() calls can be chained with withScope().

How it works

forUser() sets the X-Recall-User-ID header on every request. The Recall server reads this header to determine the user scope for data operations. All memories written or read through this sub-client are isolated to userId.

userId format

userId can be any stable identifier for your user — a UUID, email address, database ID, or opaque token. Constraints:

• Max 256 characters
• Allowed characters: letters, digits, _ - @ . +

Alternative: set a default at construction time

// All calls from this client serve alice
const aliceRecall = createClient({ url, apiKey, userId: 'alice' });

withScope() — per-request rebind (SSR / advanced)

recall.withScope({ apiKey, ...optionalHints }) returns a new Recall instance bound to a different API key. Use this when each user has their own API key (SSR pattern). For the common case where one API key serves many users, use forUser() instead.

The new client inherits url, apiVersion, all of the HTTP knobs, and the telemetry sink — only the key (and optional scope hints) change.

recall.withScope(opts: WithScopeOptions): Recall

interface WithScopeOptions {
  apiKey?: string | (() => Promise<string>);
  userId?: string;
  agentId?: string;
  namespace?: string;
}

The canonical use case is server-side rendering for a multi-tenant app where each user has their own API key:

// One module-scope client for cheap, key-less calls (health, etc.)
const root = createClient({ url: process.env.RECALL_URL! });

export async function GET(request: Request) {
  const session = await getSession(request);
  const userClient = root.withScope({ apiKey: session.recallApiKey });

  const ctx = await userClient.context({ query: 'continue planning the trip' });
  return Response.json(ctx);
}

Because the returned instance owns its own HttpTransport (and therefore its own outstanding-request graph), one user's slow tail latency cannot back-pressure another user's requests through a shared connection pool.

The userId, agentId, and namespace fields on WithScopeOptions are hints only — they update the client's local ClientScope cache for inspection. The server still derives the authoritative scope from the supplied API key.

Custom transports

Both createClient(options) and withScope use the built-in HttpTransport. If you need to inject a custom one — for tests, for a request-recording proxy, or for a future native binding — instantiate Recall directly:

import { Recall, type Transport } from '@arc-labs/recall';

class MockTransport implements Transport {
  async request<T>(method: string, path: string): Promise<T> { /* … */ }
  async requestStream(): Promise<Response> { /* … */ }
}

const recall = new Recall({
  transport: new MockTransport(),
  _internal: { /* see source */ },
});

For most users this is overkill — see Transport for the shape of the interface and a worked-out example.

Lifecycle

Recall instances are cheap to construct and have no destructor — there is no recall.close(). Connections are owned by the global fetch, which manages keep-alive automatically. You can hold a long-lived module-scope client without worrying about cleanup.

For long-running Node servers, consider a single module-scope client per Recall account, then withScope per request for tenant isolation. For serverless functions, construct lazily inside the handler — Node's lambda warm-pool will keep the same instance alive between invocations on the same container.