Hybrid Recall, Personalized PageRank & RRF
Pure vector similarity misses relational hops across entities, while pure graph traversal misses lexical and semantic paraphrase. This page explains how muninn-aether-core, muninn-aether-cortex, and muninn-aether-vault score vectors, evaluate portable filters, traverse subgraphs with PersonalizedPageRank, and fuse rankings deterministically with Reciprocal Rank Fusion.
Vector scoring (DistanceMetric::score)
Every vector backend and in-process scorer shares one scoring contract in muninn_aether_core::DistanceMetric::score:
| Metric | Formula | Zero-norm or sign rule |
|---|---|---|
DistanceMetric::Cosine (default) | dot(a, b) / (norm(a) * norm(b)) | Returns 0.0 when either vector has zero norm |
DistanceMetric::Dot | sum(a_i * b_i) | Higher dot product ranks higher |
DistanceMetric::Euclidean | -sqrt(sum((a_i - b_i)^2)) | Negated distance so closer vectors always have higher scores |
Negating Euclidean distance is deliberate. It ensures that recall::merge can combine VectorStore::search results with recall::unindexed and recall::session results using descending score order regardless of which metric the collection uses.
Portable filtering (FilterExpr)
FilterExpr defines a backend-agnostic filter AST translated by QdrantVectorStore, PgVectorStore, ChromaVectorStore, and TurbopufferVectorStore and evaluated in memory by FilterExpr::matches for InMemoryBackend, recall::unindexed, and recall::session.
FilterExpr::Eq { field, value }matchesString,Int(i64),Float(f64withinf64::EPSILON), orBool.FilterExpr::In { field, values }matches any element invalues.FilterExpr::Range { field, gte, lte }evaluates numeric bounds (>= gteand<= lte).FilterExpr::And(exprs)andFilterExpr::Or(exprs)compose nested predicates.
MemoryManager builds recall::scope_filter(&query.scopes) on _aether_scope and wraps it with query.filters using FilterExpr::And so user queries stay isolated inside their allowed tenant scopes.
Sparse subgraph extraction (graph_search)
Dense graphs cannot be loaded into process memory on every query. recall::graph_search calls GraphStore::neighborhood(ns, seeds, hops, per_node_limit, temporal) to extract only a bounded Subgraph (entities and edges).
In MemoryManager, RecallMode::Graph uses query.seed_entities directly. In RecallMode::Hybrid, resolve_hybrid_seeds combines query.seed_entities with every entity ID (Entity::id) and relation endpoint (Relation::source, Relation::target) found on the resolved MemoryItem hits from vector_recall_branch. That design lets hybrid queries discover graph paths even when the caller supplies only a query vector and no explicit seed_entities.
Iterative PersonalizedPageRank and graph_scores
Once Subgraph is in memory, PersonalizedPageRank::rank builds a petgraph::DiGraph<EntityId, ()> and runs power iteration (damping = 0.85, iterations = 20 by default).
- Seeds present in the subgraph receive equal personalization mass
1.0 / seed_hits. If none ofseedsexist in the subgraph, personalization falls back to uniform1.0 / n. - Each iteration pushes
damping * score / out_degalong outgoing edges, redistributes dangling node mass (out_deg == 0) along the personalization vector, and adds(1.0 - damping) * personalization. graph_scores(&subgraph, &entity_ranks)projects entity importance back onto memories by addingrank(edge.source) + rank(edge.target)toedge.source_memory_idfor every edge in the subgraph.recall::graph_searchresolves thoseMemoryIdkeys throughRecordStore::get_many, dropping any deleted or missing records.
Reciprocal Rank Fusion (recall::rrf)
Cosine similarity scores and PageRank weights sit on incompatible numerical scales. Normalizing raw scores across backends is brittle when score distributions shift per query.
Instead, recall::rrf(lists, RRF_K) uses rank positions (rank = idx + 1) with smoothing constant RRF_K = 60.0:
rrf_score(id) = sum over lists containing id of (1.0 / (RRF_K + rank))
When two lists contain different versions of the same MemoryId, rrf keeps the MemoryItem with the higher version and sorts descending by fused score (breaking ties deterministically by MemoryId).
Vault extensions (authority_weight and CrossEncoderReranker)
muninn-aether-vault adapts the same PersonalizedPageRank, graph_scores, and recall::rrf primitives over local Obsidian notes and adds three vault-specific signals:
- Three-way RRF.
VaultStore::recall_bundlegathers up to32FTS5 BM25 hits (amus_ftswithporter unicode61tokenizer), up to32cosine vector hits (fromHashedNgramEmbedder,DenseSubwordEmbedder, orLocalGpuEmbedder), and graph neighbors over[[wikilinks]]and#tags, then fuses all three lists viarecall::rrf. - Authority weighting. Each RRF score is multiplied by the AMU's
authority_weight(1.0forProfile,Rule,Decision, andSpec,0.6forFleeting, and0.3for sections where unchecked- [ ]task lines outnumber checked tasks plus prose lines). - Cross-encoder reranking.
CrossEncoderRerankerevaluates the topDEFAULT_RERANK_TOP_K(30) entries in place without network calls, adding a bonus over four signals (0.40 * token_coverage + 0.30 * ordered_bigram_ratio + 0.15 * phrase_bonus + 0.15 * heading_coverage) scaled byauthority_weight.max(0.1) * 0.10. Callers can substituteNoopRerankeror a customRerankeronVaultConfig::with_reranker.