Reranking

After RRF fusion, a cross-encoder reranker scores each candidate against the query and re-sorts results by relevance. This improves precision at the cost of an additional inference pass.

Reranking is applied automatically in search() and searchWithContext() when a reranker is configured. Opt out per-query with { rerank: false }.

Enabling a reranker

The easiest way is via lucerna.config.ts at your project root — the MCP server and CLI pick it up automatically:

lucerna.config.ts

import { VoyageReranker } from '@upstart.gg/lucerna';

export default {
  rerankingFunction: new VoyageReranker(),
};

Or use the --reranker flag for a one-off run:

lucerna mcp-server /path/to/project --reranker voyage
lucerna search /path/to/project "auth middleware" --reranker jina

Built-in rerankers

Name	Class	Env vars required
cloudflare	CloudflareReranker	CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN
jina	JinaReranker	JINA_API_KEY
voyage	VoyageReranker	VOYAGE_API_KEY

See Built-in Providers for flag usage.

Custom reranker

Custom Providers Implement RerankingFunction in a local file or npm package and wire it up in lucerna.config.ts.

import type { RerankingFunction } from '@upstart.gg/lucerna';

class MyReranker implements RerankingFunction {
  async rerank(query: string, texts: string[]): Promise<number[]> {
    // Return one relevance score (0–1) per text, in the same order.
  }
}