Error handling

Handle provider, storage, and queue failures without assuming named package error classes.

Example

errors.ts

try {
  return await agent.recall(query);
} catch (error: unknown) {
  logger.error({ error, sessionId }, "Recall failed");
  return { facts: [], systemPrompt: "" };
}

Failure boundaries

Provider SDKs can throw provider-specific authentication, rate-limit, and transport errors.

Required storage operations reject when the graph cannot be read or persisted.

Queued ingestion can fail after submission, so production workers should record and monitor failed jobs.

Validate identifiers and user-controlled options before invoking destructive lifecycle operations such as forgetting or clearing a session.

Recovery strategy

Catch errors at the boundary where your application can add session and operation context. Retry only transient provider or transport failures, and avoid automatically retrying destructive operations unless they are known to be idempotent.