Graph-only traversal, graph-scoped semantic ranking
Graph search without hidden embeddings
RetrievalKit supports graph search without embeddings and graph-scoped semantic search with them. Applications supply typed records and relationships. The graph can return stable matches directly, or choose the candidate neighborhood before exact vector, BM25, or hybrid ranking.
Search only inside the project that owns the evidence.
Suppose a local workspace contains notes from many projects. Your app starts from the project it already knows; RetrievalKit follows its declared relationships, then ranks only the connected notes.
QuestionWhy is cold start slow on Android?
- Start fromProject · mobile-appA stable record ID owned by your application.
- FollowcontainsThe relationship selects the eligible neighborhood.
- Rank inside42 connected notesIllustrative scope ranked by vector, BM25, or both.
Responsibilities
What RetrievalKit handles—and what your app supplies.
Graph-only search returns relationships as the result
Build GraphDatabase when traversal, typed field matching, or stable candidate projection is the goal. Its builder accepts no vector metric, vector encoding, embedding dimension, or embeddings. That boundary prevents a graph-only application from carrying retrieval configuration it does not use.
The Rust core owns schema validation, traversal, filtering, ordering, and generation safety. Wrappers do not reimplement those behaviors in Swift, Python, TypeScript, or Kotlin.
How semantic search and graph scope work together
Graph-scoped semantic search uses application relationships to choose eligible records before exact vector, BM25, or hybrid ranking. RetrievalKit does not infer the graph or treat graph proximity as a score. The graph narrows the candidate set; the retrieval ranker orders only those candidates.
This is not graph-augmented scoring and it is not a second ranker. Query-time alpha still controls the same vector/BM25 family used for whole-corpus retrieval. The graph changes the eligible set, not the meaning of the scores.
Relationships are application data
RetrievalKit never extracts or invents a graph from text. The application defines record types, fields, and relationships, then upserts records that conform to that schema. This keeps provenance visible and avoids presenting generated links as established facts.
Stable record identities and corpus generations connect graph candidates back to retrievable chunks. Deleted, outdated, filtered, or generation-mismatched candidates are correctness failures rather than silent edge cases.
Choose graph only when structure answers the query
Use graph-only search for questions such as membership, containment, equality, or traversal where structure itself is the answer. Use graph-scoped retrieval when structure identifies where evidence should come from but text or semantic relevance must still order the final hits.
- Graph-only: relationships in, stable matches out.
- Graph-scoped: relationships choose candidates, retrieval ranks them.
- Flat retrieval: search the whole eligible corpus with no graph stage.
Measured graph-scoped retrieval quality
In the frozen 296-query HotpotQA linked-abstracts comparison over 12,670 chunks, graph-scoped weighted-I8 retrieval raised NDCG@10 from 0.858 to 0.928 and Recall@10 from 0.872 to 0.958. Complete-evidence Recall@10 rose from 0.743 to 0.922.
The candidate stage reduced the mean candidate set by 972.65× while retaining 96.79% candidate recall, with zero empty scopes. This is one dataset and a retrieval-quality result; candidate reduction is not presented as a latency speedup.