Repository navigation
BM25 search upgrade, "How search works" docs, and launch copy - #18
Merged
Merged
Conversation
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
added a commit
that referenced
this pull request
Aug 22, 2026
Merge pull request #18 from ioteverythin/claude/semantica-repo-evalua…
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.pynow 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: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