Do I need pgvector to build RAG on Supabase?

No. pgvector gives you vector storage, but you still have to own chunking, embeddings, reranking, prompt construction, refusal behaviour and a citation UI. @uthereal-sdk/cortex calls a hosted retrieval service that returns cited answers, so Supabase keeps doing what it is good at: auth, storage and your application data.

Where does the Cortex API key live in a Supabase app?

In Supabase Edge Function secrets, as CORTEX_SHARED_API_KEY. The browser calls your Edge Function with the user's Supabase session; the Edge Function calls Cortex. The key never reaches the client bundle.

How do I map Supabase users to Cortex sessions?

Use the Supabase adapters: @uthereal-sdk/cortex/adapters/supabase-server for the handler and /adapters/supabase-browser for the client. Derive the Cortex user and session identifiers from the verified Supabase JWT, never from client input.

Can I keep conversation history in my own Postgres tables?

Yes. The SDK takes a CortexStore adapter, so conversations and messages are written to your own tables with your own row level security policies.

Does this work with Supabase Storage PDFs?

Yes. Upload the documents to a Cortex agent for retrieval; citations resolve to the exact page and open with the passage highlighted. Supabase Storage can remain your system of record for the original files.

Add RAG with citations to a Supabase app

Supabase gives you auth, Postgres and Edge Functions. What it does not give you is a retrieval stack that can prove where an answer came from. This is the shortest path from a Supabase project to a cited knowledge agent.

Last updated 18 September 2026 · SDK v1.1.0 · changelog

Short answer: install @uthereal-sdk/cortex, mount createCortexHandler in a Supabase Edge Function with the Supabase server adapter, and call it from the browser with createCortexBrowserClient. Keep CORTEX_SHARED_API_KEY in Edge Function secrets. You do not need pgvector, an embedding pipeline or a reranker.

Create your agent Read the SDK guide

Why not pgvector on its own

pgvector solves storage and similarity search. A production knowledge product needs more than that: layout-aware parsing, chunking that respects headings and tables, reranking, claim-to-source mapping, page-level PDF evidence and a refusal path when no passage supports the question. Those are the parts that take months and decide whether users trust the answers.

Keep Supabase for auth, application data, storage and row level security
Hand retrieval, ranking and citation mapping to Cortex
Ship a cited answer in one install instead of an embedding pipeline

The Edge Function handler

One authenticated endpoint. It verifies the Supabase session, then forwards to Cortex with the server-side key.

supabase/functions/cortex/index.ts

// supabase/functions/cortex/index.ts
import { createCortexHandler } from "@uthereal-sdk/cortex/server";
import { supabaseAuthenticate, supabaseStore } from "@uthereal-sdk/cortex/adapters/supabase-server";

const handler = createCortexHandler({
  config: {
    baseUrl: Deno.env.get("CORTEX_API_BASE_URL")!,
    assistantId: Deno.env.get("CORTEX_ASSISTANT_ID")!,
    apiKey: Deno.env.get("CORTEX_SHARED_API_KEY")!, // secret, server only
  },
  allowedOrigin: "https://your-app.example",
  authenticate: supabaseAuthenticate(),
  store: supabaseStore(),
});

Deno.serve(handler);

Secrets: never in the client bundle

supabase secrets set \
  CORTEX_API_BASE_URL="https://agent.uthereal.ai/api/functions/v1/api-server-proxy" \
  CORTEX_ASSISTANT_ID="your-assistant-id" \
  CORTEX_SHARED_API_KEY="sk-..."

Calling it from the browser

client.tsx

import { createCortexBrowserClient } from "@uthereal-sdk/cortex/browser";
import { CitedAnswer } from "@uthereal-sdk/cortex/react";
import { supabaseFetch } from "@uthereal-sdk/cortex/adapters/supabase-browser";

const cortex = createCortexBrowserClient({
  endpoint: "/functions/v1/cortex",
  fetch: supabaseFetch(supabase), // attaches the user's access token
});

const conversationId = await cortex.createConversation();
for await (const update of cortex.ask(conversationId, { message })) {
  if (update.type === "answer") showPreview(update.answer);
}

Render CitedAnswer inside your existing TanStack Query provider, and clear caches on sign-out so one user never sees another user's cached evidence.

Let your AI coding tool wire it

Lovable, Codex, Claude Code, Cursor, Windsurf and GitHub Copilot each read a ready-made instruction file for this SDK. With the file in place, describe the feature and the tool writes the Supabase wiring.

Prompt for your coding tool

Add a chat panel to this Supabase app that answers only from our uploaded
documents. Every claim must cite its source and open the PDF page,
highlighted. Use the Uthereal Cortex SDK with the Supabase adapters and keep
CORTEX_SHARED_API_KEY in Edge Function secrets.

Frequently asked questions

Do I need pgvector to build RAG on Supabase?: No. pgvector gives you vector storage, but you still have to own chunking, embeddings, reranking, prompt construction, refusal behaviour and a citation UI. @uthereal-sdk/cortex calls a hosted retrieval service that returns cited answers, so Supabase keeps doing what it is good at: auth, storage and your application data.
Where does the Cortex API key live in a Supabase app?: In Supabase Edge Function secrets, as CORTEX_SHARED_API_KEY. The browser calls your Edge Function with the user's Supabase session; the Edge Function calls Cortex. The key never reaches the client bundle.
How do I map Supabase users to Cortex sessions?: Use the Supabase adapters: @uthereal-sdk/cortex/adapters/supabase-server for the handler and /adapters/supabase-browser for the client. Derive the Cortex user and session identifiers from the verified Supabase JWT, never from client input.
Can I keep conversation history in my own Postgres tables?: Yes. The SDK takes a CortexStore adapter, so conversations and messages are written to your own tables with your own row level security policies.
Does this work with Supabase Storage PDFs?: Yes. Upload the documents to a Cortex agent for retrieval; citations resolve to the exact page and open with the passage highlighted. Supabase Storage can remain your system of record for the original files.

SDK overview

Full setup and API reference.

npm package

Install, exports and runtimes.

PDF page citations

How highlighted evidence works.

Do you need a vector database?

What you own if you run one.