our.directory

How Ranking Works

Every search result's score is a linear combination of named components. The weights below are read live from the running system.

Candidate Pool

Before scoring, we assemble a pool of candidates. They come from two sources, merged by Reciprocal Rank Fusion: lexical matches (Meilisearch, a small self-hosted search engine that handles typo tolerance, word coverage, attribute priority, and exactness) and semantic matches (cosine similarity against a local sentence-embedding model on the link's title, description, and topic names). Typo tolerance means a search for "exmaple widgts" still finds a page titled "About Example Widgets." Synonym-only matches make the pool even when no keyword in the query appears in the link's text, so a search for "small boats" can find a link titled "Dinghy Maintenance for Beginners." Both Meilisearch and the embedding model run on our own server. Your queries don't leave the directory.

The Formula

score =
    1.00 * text_relevance         (Meilisearch ranking score: word coverage, typo distance, attribute priority title > description > topics > url, exactness)
  + 0.40 * log_popularity         (log(1 + vouches + 0.5*votes), capped)
  + 0.10 * recency_decay          (exp(-age / 30 days))
  - 0.30 * controversy_penalty    (recent reverts on the link)

The score is deliberately impersonal — the same query produces the same scores for everyone. Two personal signals act only as tiebreakers on top of it (below).

Tiebreakers: Curator Proximity & Topic Match

When two results land within 0.05 of each other in score (a near-tie), two personal signals reorder them. They never lift a weaker result over a clearly stronger one — they only break ties between comparable results. This is the part of ranking that differs between viewers.

Within a near-tie, curator proximity is applied first, then topic match. Someone you follow vouching for a link outranks the link merely matching a topic you follow.

curator_proximity =
    1.0 * (1 if anyone you follow vouched for this link, else 0)
  + 0.3 * (1 if anyone followed by people you follow vouched for it)
  + 0.1 * (fraction of vouchers reachable through your follows)

Curator proximity is graded: a direct follow's vouch ranks above a friend-of-a-friend's, which ranks above a faint two-hop fraction. Topic match is all-or-nothing — the link's topics either overlap a topic you follow, or they don't.

Two-hop proximity surfaces respected curators you haven't found yet, without leaking the viewer into a filter bubble of only their direct follows.

Domain Diversity

After scoring, we walk results in order and deduct 0.15 from the score of each subsequent result on the same registrable domain, then re-sort. The first result from a given site is untouched; the second loses 0.15, the third 0.30, and so on. Stops one site from monopolising the page.

Reading the Badges

  • followed curator: at least one direct follow of yours vouched for this link.
  • friend-of-curator: no direct follow, but a friend-of-friend vouched for it.
  • topic match: the link's topics overlap topics you follow in settings → topics. Used to break near-ties, after curator proximity — not to boost the score.

How Topic Discovery Ranks

The /topics page and the empty-feed welcome card use a separate, simpler formula. Each topic's score is a recency-weighted sum of vouches on links tagged with that topic:

topic_score = sum over each vouch of exp(-age_days / 120)

A 120-day half-life means a vouch from yesterday contributes 1.0; from 60 days ago, 0.71; from a year ago, 0.05. Old vouches age out, so the directory's early shape doesn't permanently dictate what surfaces in topic discovery. New topics can climb against established ones without having to outrun two years of accumulated vouches.

This is intentionally not a velocity signal. It doesn't reward "lots of vouches right now." Submission timing can't game it. A separate "Recently created topics" strip on /topics surfaces topics created in the last 60 days regardless of score, so brand-new topics get a dedicated slot before any vouches accumulate.

Same filters as everywhere else: banned curators' vouches don't count (vouches_visible), unreviewed new-user submissions don't count toward topic scores, and safety-flagged revisions are excluded.

What This Is Not

There's no learned ranker, no engagement score. No data about your reading time, scroll depth, mouse movement, or off-platform behavior feeds into this. The score is what the formula says, computed from public signals (vouches, votes) — your follow graph and topic subscriptions only break near-ties on top of it. The semantic candidate-pool step widens recall; it doesn't decide order.

Tuning

When the weights change, this page changes with them. It reads the live constants from the ranking module.