/embeddings-setup

name: embeddings-setup
description: Bring Open Second Brain semantic search online — embedding API key, sqlite-vec extension, first reindex, optional periodic refresh. INVOKE when the user mentions "embeddings", "semantic search", "vector index", or after `o2b search check` reports `vec_extension: unavailable`, `embedding_key: missing`, or any line in its `recommendations:` block. SKIP when the user is asking conceptual questions about embeddings or comparing providers without intent to set up — answer those directly.

Embeddings setup

Open Second Brain ships with two search paths: keyword-only (always on, no credentials) and semantic via embedded vectors (opt-in). This SKILL walks the activation flow for the semantic path. The flow is proactive — when the user mentions semantic search or `o2b search check` surfaces missing pieces, take the user through this list rather than waiting for explicit instruction.

Step 1 — Always start with `o2b search check`

o2b search check

The output names every missing piece and ends with a `recommendations:` block listing the exact commands to fix each. Read both before suggesting next steps. The `recommendations` field is also present in the `--json` output for headless callers.

Branch on what the report shows:

• `embedding_key: MISSING` → go to step 2. The `key_sources_checked:`

line names where the key was looked for, and `key_present_under:` names any other registered provider profile whose env key is set. If the key sits under another profile, the fix may be pointing `embedding_provider` at that profile rather than adding a key.

• A recommendation saying the embedding model has no known price, or

that the price pair names another model → see "Declare the model's price" in step 2.

• `vec_extension: unavailable` on macOS → go to step 3.
• `vec_extension: unavailable` on Linux → go to step 4.
• Everything OK but `semantic_enabled: false` (no embeddings yet) →

go to step 5.

Step 2 — Provider and API key

Ask the user which provider they want. The default is `text-embedding-3-small` from OpenAI (about $0.02 per 1M tokens, which covers tens of thousands of vault pages). Any OpenAI-compatible endpoint works — Groq, Together, a local LM Studio server, etc.

Required env vars (write to `~/.hermes/.env` or the configured env file, never to a tracked file):

OPEN_SECOND_BRAIN_EMBEDDING_PROVIDER=openai-compat
OPEN_SECOND_BRAIN_EMBEDDING_MODEL=text-embedding-3-small
OPEN_SECOND_BRAIN_EMBEDDING_KEY=<placeholder; user pastes the key>
# Optional — only when not using OpenAI:
# OPEN_SECOND_BRAIN_EMBEDDING_BASE_URL=https://api.together.xyz/v1

The base URL must be `https://`. Plain `http://` works only for a loopback host (`localhost`, `127.0.0.1`, `::1`). When the user's embedding server runs on ANOTHER machine without TLS - LM Studio on the Windows host reached from WSL, Ollama on a LAN box, a tailnet `100.x` address - the endpoint is refused until the operator opts in for it explicitly:

OPEN_SECOND_BRAIN_EMBEDDING_BASE_URL=http://100.64.0.5:1234/v1
OPEN_SECOND_BRAIN_EMBEDDING_ALLOW_INSECURE_HTTP=true

(or `embedding_allow_insecure_http: true` in the o2b config; the reranker has its own `search_rerank_allow_insecure_http`). Tell the user what it means before setting it: chunk text and the API key cross the network unencrypted, so it belongs only on a network they trust. The opt-out never applies to a base URL that comes from a provider profile registered with `o2b search provider add`; set the URL in config or env instead. Every run that uses it prints one stderr warning per endpoint.

**Never invent or echo the key.** Write a placeholder, then ask the user to paste their key in place of it. Recheck with `o2b search check` after the user confirms.

Declare the model's price

Spend estimates name their price source: `builtin` (the built-in table; the `local` provider is free), `operator` (declared) or `unknown`. A model the table does not list (most local servers, newer or niche models) is `unknown`, and its estimates print `price unknown`. When the user has set a positive `embedding_cost_gate_usd`, an unknown price refuses embedding runs with `EMBEDDING_COST_UNPRICED` until the price is declared, and it also refuses the query embeds of searches that do not run at local reach (MCP tools and hooks): a hybrid search falls back to keyword-only and names `semantic-cost-unpriced` in its trail. Ask the user for the provider's rate (USD per million tokens) and write the pair beside the other embedding settings:

OPEN_SECOND_BRAIN_EMBEDDING_PRICE_MODEL=nomic-embed-text:latest
OPEN_SECOND_BRAIN_EMBEDDING_PRICE_USD_PER_MTOK=0

(or `embedding_price_model` and `embedding_price_usd_per_mtok` in the o2b config). Set both or neither. `0` declares the model free; only use it when the user confirms the endpoint costs nothing, because a loopback URL can still be a paid proxy. The pair names one model, so after a model switch `o2b search check` flags the stale declaration until it is updated. Declaring a price never triggers a reindex.

Declare the model's input window (uncurated models)

A search query longer than the model's input window is cut to it before the embed and the trail names `semantic-query-truncated`. The window comes from the curated model table; for a model it does not list the window is unknown and nothing is cut, so a serving stack that truncates silently or refuses long inputs does so unannounced. When the user knows the model's window (in its own tokens), declare it:

OPEN_SECOND_BRAIN_EMBEDDING_INPUT_WINDOW_TOKENS=512

(or `embedding_input_window_tokens` in the o2b config). It is refused for the `local` provider, which has no window.

Extra request fields (OpenAI-compatible endpoints)

When the user's serving stack needs a request field the provider does not send, put a JSON object in `embedding_extra_body` (env `OPEN_SECOND_BRAIN_EMBEDDING_EXTRA_BODY`). O