How ranked evidence is assembled
A zvec-grep result is not produced by asking one index for its favorite passage. The search engine gathers different kinds of evidence, applies the workspace filters, combines candidate rankings, and then chooses what a person or agent can actually read. Understanding that assembly lets you interpret a result as a relevance judgment with visible support—not as a proof that the first item is the whole answer.
The distinction matters because indexed search serves questions whose location or wording is uncertain. A useful candidate must be discoverable by meaning, by recognizable terms, or by both. It must also remain tied to a code entity, document section, file, and source range so that a reader can follow the result back to the workspace. Zvec-grep’s ranking path is designed around that chain.
The indexed store keeps more than one address for an answer
At the storage layer, zvec-grep keeps an entity collection and a separate file-metadata collection. The entity collection stores the content that can be searched, its vector representation, structural metadata, fragment groups, and the range that identifies where the content came from. The file collection records facts about the workspace files themselves, including their paths and indexing state. Separating these responsibilities lets the search engine reason about an entity while still reporting the file and its current status.
The entity text has a full-text search field. Full-text search, or FTS, is the indexed form of lexical retrieval: it works from words and tokens in stored text rather than from conceptual similarity alone. Zvec-grep configures this field with the jieba tokenizer and lowercase filtering. The exact tokenizer is an implementation choice, not a universal optimum, but its role is clear: turn text into terms that the lexical route can rank.
The same entity collection has a vector field configured for the selected embedding model’s dimension and similarity metric. The current storage uses an HNSW vector index for this field. A query can therefore produce candidates through lexical matching, vector similarity, or both. The two routes see related but not identical evidence. Lexical search is strong when the stored text contains a meaningful anchor. Vector search is useful when the query and the stored passage express a related idea with different words.
Structural fields make those routes more informative. For code, an indexed entity can retain its symbol type and name, scope, signature, documentation, modifiers, and syntax-node type. For Markdown, it can retain a heading, heading level, and section scope. A query can narrow candidates by file, symbol name, symbol type, group, file type, path-derived scope, or modification time. These filters do not add relevance by themselves. They define which part of the stored evidence is allowed to compete.
Fragment groups solve a presentation problem created by long entities. A large class or function may have a major outline and several subordinate windows. Each window can contribute searchable content, but the user usually wants the class or function as the public entity rather than a list of disconnected slices. The storage layer records the group relationship and resolves a subordinate hit back to its major entity. That gives the ranking engine more material to search without forcing the final result to expose every internal fragment as a separate answer.
Source ranges complete the connection to evidence.