Configuration

Lucerna is configured entirely through a lucerna.config.ts file. All settings — including embedding provider credentials — live there. No environment variables are read.

The config file is created automatically the first time you run index, watch, or mcp-server if none is found.

How it works

1. On startup, Lucerna walks up the directory tree from the project root looking for lucerna.config.ts (or .js / .mjs).
2. If found, the file is loaded and its settings applied.
3. If not found, a template is created in the current directory.

This means a config at a monorepo root is automatically picked up by any subdirectory — no per-package config needed.

Minimal setup

lucerna.config.ts

import { defineConfig } from "@upstart.gg/lucerna";

export default defineConfig({});

This is a valid config — Lucerna works out of the box with lexical (BM25) search. Add an embedding provider to also enable semantic (vector) search, which is strongly recommended for best results:

export default defineConfig({
  embedding: {
    provider: "voyage",
    model: "voyage-code-3",
    apiKey: process.env.VOYAGE_API_KEY!,
  },
});

defineConfig() is an identity function providing TypeScript autocomplete and type-checking.

What you can configure

Setting	Description
embedding	Embedding provider for semantic (vector) search — optional but strongly recommended. See Embedding Providers.
reranking	Optional cross-encoder reranking. See Reranking Providers.
include	Glob patterns for files to index (default: ["**/*"]).
exclude	Additional glob patterns to exclude beyond the built-in list.

Reranking is optional

Without a reranking provider, hybrid search still applies RRF fusion automatically — merging vector and full-text results into a single ranked list. This is a solid baseline for most codebases. Add a reranking provider when you need higher precision on large codebases where many chunks look similar at the embedding level.