Architecture

Understanding how Unrag processes your content helps you make good decisions about chunking parameters, embedding models, and performance optimization. Let's walk through both pipelines in detail.

The components

Every Unrag instance is built from three pluggable pieces:

The embedding provider turns text into vectors. It has one job: take a string, call an embedding model (local or remote), and return an array of numbers representing that text's position in semantic space. The default provider uses the Vercel AI SDK to call OpenAI models, but you can implement the interface for any embedding service.

The store adapter handles persistence. It knows how to write documents, chunks, and their embeddings to your database, and how to query for similar vectors. Unrag ships adapters for Drizzle, Prisma, and raw SQL—all targeting Postgres with pgvector.

The chunker splits documents into smaller pieces. The default implementation uses token-based recursive chunking with the o200k_base tokenizer (same as GPT-5, GPT-4o). It splits at natural boundaries (paragraphs, sentences, clauses) while respecting token limits. For specialized content, you can install plugin chunkers (markdown, code, semantic) or provide your own chunker function.

These components are assembled in your unrag.config.ts file to create a ContextEngine instance. The engine coordinates the components but doesn't contain business logic itself—it just calls the right methods in the right order.

The ingest pipeline

When you call engine.ingest({ sourceId, content, metadata, assets }), here's what happens:

const result = await engine.ingest({ sourceId: "doc-1", content: "..." });
console.log(result.durations);
// { totalMs: 1523, chunkingMs: 2, embeddingMs: 1456, storageMs: 65 }

The retrieve pipeline

When you call engine.retrieve({ query, topK, scope }), the flow is simpler:

const result = await engine.retrieve({ query: "how does auth work?", topK: 5 });
console.log(result.durations);
// { totalMs: 234, embeddingMs: 189, retrievalMs: 45 }

The delete pipeline

When you call engine.delete({ sourceId }) or engine.delete({ sourceIdPrefix }), the engine removes content from the database:

Deletion is useful for:

• Removing outdated content after updates
• Honoring user deletion requests (GDPR/privacy compliance)
• Cleaning up test data
• Removing entire namespaces (e.g., tenant:acme: prefix)

Improving retrieval with reranking

Vector similarity search is fast but imprecise. The embedding distance between a query and a chunk is a useful approximation of relevance, but it's not perfect. Chunks that are semantically related to your query might rank higher than chunks that directly answer it.

Reranking addresses this with a two-stage approach. First, you retrieve a larger set of candidates using fast vector search—maybe 30 chunks instead of 10. Then you run those candidates through a reranker that directly scores each one against the query. The reranker is more expensive (it sees both the query and candidate text), but it makes much better relevance judgments.

// Stage 1: Fast vector retrieval
const retrieved = await engine.retrieve({ query, topK: 30 });

// Stage 2: Precise reranking
const reranked = await engine.rerank({
  query,
  candidates: retrieved.chunks,
  topK: 10,
});

Reranking is optional and requires installing the reranker battery. The default implementation uses Cohere's rerank-v3.5 model, but you can bring your own reranker. See the Reranker documentation for details.

Where RAG happens

It's worth noting what Unrag doesn't do: it doesn't call an LLM, build prompts, or generate answers. The "retrieval" in RAG is what Unrag handles. The "augmented generation" part—taking retrieved chunks and using them as context for an LLM—is your application's responsibility.

This separation is intentional. Prompt engineering, context window management, streaming responses, and model selection vary dramatically by use case. Unrag gives you the retrieval primitive and trusts you to build the right generation layer for your application.

A typical RAG flow looks like:

1. User submits a question
2. Call engine.retrieve() to get relevant chunks
3. Format chunks into a context string
4. Build a prompt with system instructions, context, and the user's question
5. Call your LLM and stream the response

Unrag handles step 2. Everything else is your code, using whatever patterns and libraries you prefer.