Open Second Brain Embeddings Setup

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). Only openai-compat sends it, and model, input and encoding_format are refused by name. A dimensions field needs embedding_dimension set to the same width:

OPEN_SECOND_BRAIN_EMBEDDING_EXTRA_BODY='{"dimensions": 512}'
OPEN_SECOND_BRAIN_EMBEDDING_DIM=512

The extra body is not part of the embedding identity, so changing it never triggers a reindex; a changed embedding_dimension does. Some fields shape the vectors the provider returns (a provider task, input_type, normalize or truncate switch): after changing such a field, rebuild the vectors with o2b search reindex --embeddings so new query vectors stay in the space of the stored passages (o2b search index --force keeps the stored vector of every unchanged chunk).