Skip to content
Frigg Docs

Semantic search

Semantic retrieval is an optional accelerator for broad discovery such as search_hybrid. It is off by default and never replaces lexical, symbol, structural, graph, navigation, or source proof.

Enable semantic retrieval

Section titled “Enable semantic retrieval”

Enable the same provider settings for indexing and serving. The zero-key local path is:

Terminal window
FRIGG_SEMANTIC_RUNTIME_ENABLED=true \
FRIGG_SEMANTIC_RUNTIME_PROVIDER=local \
frigg index


FRIGG_SEMANTIC_RUNTIME_ENABLED=true \
FRIGG_SEMANTIC_RUNTIME_PROVIDER=local \
frigg serve

Providers

Section titled “Providers”
Provider Default model Credential Endpoint
local all-MiniLM-L6-v2 none In-process prepared model
openai text-embedding-3-small OPENAI_API_KEY Fixed OpenAI API
google gemini-embedding-001 GEMINI_API_KEY Google API
openai_compat text-embedding-3-small protocol default FRIGG_OPENAI_COMPAT_API_KEY, falling back to OPENAI_API_KEY Required full embeddings POST URL

Override a provider’s model with FRIGG_SEMANTIC_RUNTIME_MODEL.

OpenAI-compatible endpoints

Section titled “OpenAI-compatible endpoints”

Use openai_compat for OpenAI-protocol servers such as vLLM, LM Studio, Azure-compatible deployments, or internal gateways:

Terminal window
export FRIGG_SEMANTIC_RUNTIME_ENABLED=true
export FRIGG_SEMANTIC_RUNTIME_PROVIDER=openai_compat
export FRIGG_SEMANTIC_RUNTIME_OPENAI_COMPAT_ENDPOINT=http://127.0.0.1:1234/v1/embeddings
export FRIGG_OPENAI_COMPAT_API_KEY=replace-me
export FRIGG_SEMANTIC_RUNTIME_MODEL=backend-model-id
frigg index

The endpoint must be an absolute HTTP or HTTPS URL for the embeddings POST operation. openai_compat has a distinct storage provider identity from openai. The endpoint itself is not part of that identity, so reindex after switching an endpoint to a different vector space even when the model string stays unchanged.

Local model lifecycle

Section titled “Local model lifecycle”

The local provider prepares missing model artifacts automatically. Use FRIGG_SEMANTIC_MODEL_CACHE to select the cache root. A conflicting HF_HOME can interfere with Frigg’s prepared cache selection; remove that override when local startup reports a cache mismatch.

The default MiniLM model is an offline-smoke, general-purpose embedder rather than a code-specialized model. A healthy semantic status means vectors ran; agents should still pivot from hybrid discovery to exact search_text or search_symbol before proof.

Storage and dimensions

Section titled “Storage and dimensions”

Semantic rows are partitioned by repository, provider, and model. Changing the provider or model requires a semantic pass with full frigg index; partitions do not automatically promote a different head.

The sqlite-vec projection width is 1536. Model metadata reports native dimensions before storage padding. MiniLM produces 384-dimensional vectors, which Frigg zero-pads to the projection width. Padding enables a shared fixed-width store; it does not add semantic signal or improve model quality. Oversize vectors are rejected.

The embedding document envelope includes the source path and language while stored excerpt content remains source text. After a Frigg upgrade changes that envelope, run full frigg index, not only frigg index --changed.

Policy resource and presets

Section titled “Policy resource and presets”

Read frigg://policy/semantic-models.json for the live curated model catalog. It includes provider defaults, native dimensions, projection behavior, credentials, known limits, and soft presets:

  • offline-small
  • cloud-openai
  • cloud-google
  • openai-compat-selfhost

These presets document intent and expand to provider/model settings. They are not CLI flags, and the preset id is never the storage partition key.

Failure policy

Section titled “Failure policy”

By default, semantic failure degrades discovery while the deterministic evidence layers remain available. Set strict mode only when semantic availability must fail the command or service:

Terminal window
FRIGG_SEMANTIC_RUNTIME_ENABLED=true \
FRIGG_SEMANTIC_RUNTIME_STRICT_MODE=true \
frigg index
Section titled “Related”

Source Anchors

Section titled “Source Anchors”
  • ../frigg/README.md
  • ../frigg/docs/operator-runbook.md
  • ../frigg/crates/cli/src/settings/semantic_runtime.rs
  • ../frigg/crates/cli/src/embeddings/provider_factory.rs
  • ../frigg/crates/cli/src/embeddings/local_model.rs
  • ../frigg/crates/cli/src/indexer/semantic.rs
  • ../frigg/crates/cli/src/storage/semantic_store_support.rs
  • ../frigg/crates/cli/src/mcp/guidance.rs