embeddings

br8n — Embeddings (which provider, and switching it)

Semantic search needs vectors. br8n produces them one of three ways:

Provider	When it applies	Dim
remote	AI_GATEWAY_API_KEY or OPENAI_API_KEY is set	1536
local	the br8n[local-embeddings] extra is installed, no key is set, and the KB is on the local tier — cloud pgvector columns are 1536-wide, so local always refuses on cloud	384
none	neither — capture and chronological surfaces still work, search is text-only	—

Step 1 — Report the current state

Call mcp__plugin_br8n_br8n__br8n_embeddings_get(). Lead with the provider, model and why it was chosen (source), then flag anything actionable:

• ready: false with provider: local → the model is still downloading (~130 MB, first use only). Search stays text-only for a minute; nothing is lost.
• pending_findings/pending_nodes above zero → a re-embed is draining in the background. It refills on ordinary reads; no action needed.
• provider: none → say what would fix it: either set a key, or pip install 'br8n[local-embeddings]' and switch to local.
• pending_switch not null → the environment quietly changed (e.g. a key went missing) and would flip the space (pending_switch.stored → pending_switch.detected), but existing vectors are at risk, so br8n left them alone instead of rebuilding. Tell the user what changed and offer to apply it — that offer is exactly Step 2.

Step 2 — Switch, if asked

Call mcp__plugin_br8n_br8n__br8n_embeddings_set(provider) with auto, remote, local or none. auto is the default and means "use a key if there is one, else local". To actually apply a deferred pending_switch, pass the concrete detected.provider from Step 1 — that always rebuilds immediately. Passing auto instead re-runs detection but is still subject to the same work-at-risk gate, so if the vectors it would discard are still there it defers again ({ok: true, deferred: true, ...}) rather than forcing the rebuild through.