The knowledge index

What it is

Reading a whole document into the model's context to answer one question is slow, and a long one does not fit. Instead, ivralo index cuts the workspace's documents into chunks, turns each chunk into a vector with the embedding model, and stores them in PostgreSQL with the pgvector extension, in the same ivralo schema as everything else.

The Librarian searches the index and answers with the file and the page, section or slide. It owns the documents skill.

ivralo index
ivralo search "rollback procedure for the payments service"

In a session, /index and /find <query> do the same.

What is indexed

Chunks follow the document's own seams, because a fixed window cuts through the sentence that holds the answer. A section longer than IVRALO_CHUNK_SIZE is split between paragraphs, each piece keeping the section's name. A PDF with no text layer goes through OCR, which needs docling (see Documents and data).

Hidden directories and ivralo's own .ivralo/ are never indexed. A # Documents section in the repository's IVRALO.md narrows the index to the paths, folders and globs it names; ivralo index and ivralo doctor say how many files it left out.

Keeping it current

The index is incremental by content: unchanged files are skipped, changed ones embedded again, deleted ones removed. Run ivralo index after documents change, by hand or from a schedule.

The exit code of ivralo index says whether the index was brought in line: 0 when every file it meant to embed was embedded; 1 when the embedding model failed or refused, returned a different vector size than configured, a file could not be read, or the database could not be reached; 2 for a usage error. Each problem is named on stderr, so a script or a schedule can rely on it.

One database, many workspaces

Every chunk carries its workspace's key, so several repositories can share one database. Indexing one never removes another's documents, and a search answers from its own workspace only. --rebuild clears only this workspace's rows; it refuses when the embedding size changed, because the table is shared. --rebuild --all is the way through then, and also the cleanup for a workspace you moved or renamed, whose rows stay under its old path.

How search ranks

Search is hybrid. The vector leg finds paraphrase: "how do we roll back" finds a section titled "Reverting a release". A PostgreSQL text index finds the exact word, such as an error code, a host name or a ticket number, which an embedding is bad at. The two are weighed by IVRALO_INDEX_VECTOR_WEIGHT.

The keyword leg runs in a text-search configuration. The default, simple, stems nothing, so E4471 matches E4471 in any language. english or turkish adds one language's stemming. Change it and run ivralo index again: the text index is rebuilt in the new language without embedding anything again.

Settings

Choosing an embedding model is on Embeddings. ivralo doctor checks the extension, makes one real embedding request and checks its size, counts the files changed since the last index, and checks that the text index speaks the configured language.

Not the code index

The knowledge index is for documents. Code is indexed separately, from the language server and git, in .ivralo/index/ with no database: ivralo index --code builds it. See Code intelligence.