Enabling semantic search

Full-text search (FTS) in Notarium works always, with no setup. Semantic (vector) search is an optional capability: it adds hybrid ranking by meaning, but it pulls in a heavy native stack (onnxruntime + sqlite-vec, ~660 MB on disk) and a local embedding model that downloads when first enabled (~600 MB on disk and hundreds of MB of RAM). That's why it's off by default and turned on deliberately. For how search works under the hood, see Concepts: search.

Two independent switches

It helps to keep two levels apart — installation and runtime:

Installation — whether the native vector stack is present in node_modules. The Docker image always ships it, so turning it on inside the container requires no rebuild. When running from source, the default make deps does not install it (a local node_modules is ~660 MB lighter) — for local vector work you need make deps-vector.
Runtime — the VECTOR_SEARCH variable. In the published image it defaults to off.

For semantic search in Docker, flipping the runtime switch is enough — the stack is already in place.

Turning it on

docker run -d --name notarium \
  -p 3000:3000 \
  -v notarium-data:/data \
  -e VECTOR_SEARCH=on \
  docouno/notarium:latest

(A single /data volume holds all state — the metadata database, indexes, your notes, export artifacts; the same as in a plain run, see Install. Here it only gains VECTOR_SEARCH=on.)

When first enabled, the default model (bge-m3) downloads (~600 MB on disk) and uses hundreds of MB of RAM. Indexing runs in the background: full-text search is available right away, while the vectors catch up.

Model tiers

The model is chosen by the pair EMBED_MODEL + EMBED_DIMENSIONS (the dimensionality must match the model) — it's a runtime setting on a single image, not a separate build:

Tier	Variables	RAM	When
off	`VECTOR_SEARCH=off`	0	A low-powered machine, or keyword search is enough. The image default.
compact	`VECTOR_SEARCH=on`, `EMBED_MODEL=Xenova/multilingual-e5-small`, `EMBED_DIMENSIONS=384`	~120 MB	Homelab, a small VPS.
full	`VECTOR_SEARCH=on` (defaults: bge-m3, 1024)	~600 MB	A powerful machine; 100+ languages, long context.

Asymmetric e5 models

The compact tier (e5) requires the prefixes EMBED_QUERY_PREFIX="query: " and EMBED_PASSAGE_PREFIX="passage: " — forgetting them silently degrades search quality. For the symmetric bge-m3, the reverse holds: you shouldn't set the prefixes at all.

Resources on a tight machine

On a host without swap and ~6 GB of RAM, the initial bge-m3 indexing can hit the memory ceiling. Two levers: use the compact tier (e5-small), or set EMBED_CPU_MEM_ARENA=off — this keeps consumption around ~1.9 GB at the cost of a small slowdown. For the full list of embedding parameters, see the Reference.

Falling back to full-text search

If VECTOR_SEARCH=off, or the native stack fails to load for any reason, search keeps working over full text — with no error, and the results look the same. Semantic search is an extra ranking channel on top of the always-on FTS, not a hard dependency. An instance without vectors is a fully working instance.