Embeddings and the index

What the embedder is for

An embedder is the model that turns a piece of text into a vector, a list of numbers that places similar meanings close together. ivralo uses one for two things:

• the knowledge index of the workspace's documents (PDF, Word, PowerPoint, Markdown, text), which the Librarian searches and cites by file and page;
• semantic code search, an optional index of the repository's code cut along its symbols.

Both live in PostgreSQL with pgvector, beside the rest of ivralo's state. The search is hybrid: the vector finds a paraphrase, a PostgreSQL text index finds the exact word. The knowledge index covers what is indexed and how it is searched.

Choosing an embedder

IVRALO_EMBED_MODEL takes the same reference as a chat model (see Models and providers), over agno's embedders. A bare name is an Ollama tag.

A local embedder and a hosted one both work. A hosted embedder sends the documents' text off the machine to be embedded, and ivralo announces it the way it announces a hosted chat model.

IVRALO_EMBED_DIMENSIONS also sizes the vector column in PostgreSQL, so set it to the number your model produces. ivralo doctor makes one real embedding request and reports the size that came back, or the error the request ran into.

On a server

A server has no Ollama, so ivralo init --server writes IVRALO_KNOWLEDGE=false unless you name an embedder. With a company endpoint, the embedder is a name served at the same URL as the chat model:

ivralo init --server --model-url http://gpu-box:8000/v1 --model qwen3-32b --embed-model bge-m3

This writes IVRALO_EMBED_MODEL=openai-compatible:bge-m3. Set IVRALO_EMBED_DIMENSIONS to match the model (1024 for bge-m3), then check it:

ivralo doctor

Building and rebuilding the index

ivralo index

Indexing is incremental: unchanged files are skipped, changed ones embedded again, deleted ones removed. Inside a session, /index does the same. ivralo index exits 1 when anything went wrong (an embedder that failed, a size that does not match, a file that could not be embedded) and names each problem on stderr, so a script or a schedule can rely on it.

Vectors from two different models cannot be compared, so a change of embedder means starting over:

--rebuild starts this workspace's index over. When no other workspace is indexed in the database, it drops the vector table, so a new vector size is taken as well. When others are, it removes only this workspace's rows and refuses a changed vector size, since the column is shared. After a change of model, the other workspaces' vectors are the old model's too. --rebuild --all starts every workspace over and drops the table. It is also how you clear the rows of a workspace you moved or renamed.

Embedding code

Semantic code search fills its index as the agents use it. To embed the whole repository at once, build the code index and then embed it:

ivralo index --code --semantic

Each chunk is a symbol (a function, a class, a method) as the code index holds it. Files are the ones git lists, text only, up to 256 KB each, and never a .env.

Whether an embedder is hosted is decided the same way as for a chat model: loopback, private addresses and local names are local, anything else is hosted. Models and providers has the rule.