Skip to content

BM25 search upgrade, "How search works" docs, and launch copy - #18

Merged
Joshuaakaspace merged 2 commits into
mainfrom
claude/semantica-repo-evaluation-essnux
Aug 22, 2026
Merged

Joshuaakaspace merged 2 commits into
mainfrom
claude/semantica-repo-evaluation-essnux

Conversation

@Joshuaakaspace

Copy link
Copy Markdown
Collaborator

Three commits' worth: a measurably better search ranking, a docs page that explains it end-to-end, and the ready-to-post launch copy that missed the #17 merge window.

Search: TF-IDF → Okapi BM25

backend/graphier/search.py now ranks with the classic BM25 function (k1=1.5, b=0.75) instead of TF-IDF cosine. Two concrete wins, both pinned by new tests:

  • Term-frequency saturation — a note spamming "compiler" 40 times no longer outranks a note that covers all the query terms once.
  • Length normalization — a match in a short focused note beats the same match buried in a 300-word one.

Raw BM25 is unbounded, so each score is divided by the query's best achievable score, mapping the lexical component into [0, 1]. That keeps the existing +0.35 graph-entity boost and the 0.01 relevance floor at their calibrated weights — the hybrid behavior (entity mentions outrank shared vocabulary) is unchanged, just built on a better lexical base. Still stdlib-only, still deterministic, still no index to maintain.

docs/how-search-works.md

The full pipeline written down: tokenizer, the BM25 formula with the reasoning for each property, the graph boost, snippet windowing, what search deliberately isn't (embeddings, persistent index, fuzzy), and a tuning table for the three module constants. README's hybrid-search bullet links to it; TF-IDF references in CONTRIBUTING/ROADMAP/MCP tool description updated.

Launch copy (docs/launch-posts.md)

Ready-to-adapt drafts for Show HN (post + first comment + prepared answers to the predictable hard questions), r/ObsidianMD, r/PKMS, r/selfhosted, lobste.rs, and an X/Mastodon thread opener — each pitched to what its audience actually cares about.

Testing

63/63 backend tests pass — the 61 existing (including the three prior search tests, untouched) plus two new BM25-property tests: coverage-beats-repetition and length-normalization/score-range.

🤖 Generated with Claude Code

https://claude.ai/code/session_01QVbxD1gd3gsC6zXKE6L3ya


Generated by Claude Code

claude added 2 commits August 22, 2026 11:37
Show HN title + first comment (with prepared answers to the four
predictable objections: extraction noise, why-not-embeddings,
Obsidian-has-plugins, is-this-a-Semantica-demo), tailored posts for
r/ObsidianMD, r/PKMS, and r/selfhosted, and short blurbs for lobste.rs,
X/Mastodon, and awesome-list PRs.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QVbxD1gd3gsC6zXKE6L3ya
Replace TF-IDF cosine with Okapi BM25 (k1=1.5, b=0.75): term-frequency
saturation stops one spammed term from outranking full query coverage,
and length normalization lets short focused notes beat long ones with
the same match. Raw scores are divided by the query's best achievable
score, keeping the lexical component in [0, 1] so the +0.35 graph-entity
boost and the relevance floor keep their calibrated weight.

Add docs/how-search-works.md explaining the full pipeline (tokenize,
BM25, graph boost, snippet) with the tuning knobs, and update every
TF-IDF reference. Two new tests pin the BM25 properties.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QVbxD1gd3gsC6zXKE6L3ya
@Joshuaakaspace
Joshuaakaspace merged commit a4e1133 into main Aug 22, 2026
2 checks passed
Joshuaakaspace added a commit that referenced this pull request Aug 22, 2026
Merge pull request #18 from ioteverythin/claude/semantica-repo-evalua…
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants