This post reflects personal learning and experimentation. It does not represent commercial offerings or services.
The email came in at 7 AM on a Monday:
"I searched for 'anxiety' but got nothing. Does your app even have content about stress? I'm dealing with work burnout and was hoping to find something relevant."
The reality was stark. GitaWisdom had 47 scenarios about stress, burnout, and feeling overwhelmed. Topics like "When work pressure follows you home" and "Managing expectations that feel impossible."
But she'd searched "anxiety." And we had "stress at work."
The search was blind to what users actually meant. It was matching strings, not understanding intent. And every time that happened, someone walked away thinking we didn't have what they needed - when we absolutely did.
That email changed everything about how search was thought about. It wasn't a feature. It was the first impression of whether your content is worth exploring.
GitaWisdom now has 1,225 real-world scenarios. Users don't search for exact titles - they describe situations in their own words. If search can't bridge that gap, they leave. Here's how we built search that finally understands.
The Problem: Search That Doesn't Understand
Keyword matching is too literal
Basic search looks for exact string matches. If the user types "overwhelmed" but the database has "burnout", no match.
- TF-IDF only catches exact terms
- Synonyms require manual mapping
- Intent is lost in tokenization
Users think in feelings, not keywords
Real search queries are emotional: "feeling stuck", "my boss doesn't listen", "can't make decisions". These need understanding, not matching.
- Users describe situations, not titles
- Empty results = "this app doesn't have what I need"
- Search is the first impression of content quality
Both perspectives pointed to semantic understanding. Engineering needed a way to match meaning, not strings. Product needed users to find relevant content even with imprecise queries.
Decision: Hybrid Search Architecture
Two search systems in parallel
Run both keyword and semantic search, then combine results intelligently based on where matches appear.
KEYWORD LAYER (5ms): - TF-IDF with n-gram support - Field boosting (title 2.5x) - Stop word filtering SEMANTIC LAYER (50-200ms): - 768-dim embeddings - Cosine similarity - Pre-computed vectors
Best of both worlds for users
Exact matches appear instantly. Semantic matches appear as "related" suggestions. Users always find something relevant.
- Type "anxiety" → exact matches first
- Type "feeling overwhelmed" → semantic matches
- Both together → reinforced ranking
The Scoring Formula
Normalized score combination
Results from both systems are combined. If a scenario appears in both keyword and semantic results, scores reinforce each other.
// If in BOTH results: final = keyword + (semantic * 0.5) // Weights normalize different scales keywordWeight = 0.5 // TF-IDF: 0-15+ semanticWeight = 12.0 // Cosine: 0-1
Relevance users can feel
Users don't see scores - they see results in the right order. The formula ensures exact matches rank high while semantic matches fill gaps.
- First results: obvious matches
- Later results: "you might also like"
- No empty result screens
Real Example: "feeling overwhelmed"
What Each Layer Returns
// User types: "feeling overwhelmed" KEYWORD RESULTS: (no exact matches - "overwhelmed" not in titles) SEMANTIC RESULTS: - "Managing burnout when deadlines pile up" (0.82) - "When work stress follows you home" (0.79) - "Dealing with anxiety about the future" (0.74) FINAL OUTPUT: All semantic matches shown, ranked by similarity
Without semantic search, this query returns nothing. With it, users find exactly what they need - even though they used different words.
The Performance Trade-off
Speed vs intelligence
Keyword search is fast (5ms). Semantic search is slower (50-200ms). Hybrid adds latency for better results.
Keyword only: 0-5ms Semantic only: 50-200ms Hybrid: 100-250ms
Acceptable for the use case
100-250ms is fast enough for search. Users expect a brief pause. What they won't accept is no results or irrelevant results.
- Search isn't real-time typing feedback
- Quality matters more than speed here
- Better results = users trust the app
The Re-indexing Bug
Index wasn't built after startup
Early versions returned 0 results after app restart. A 30-day refresh protection was blocking the initial indexing.
// Bug: blocked by 30-day check search.refreshMonthly(); // Fix: force parameter search.refreshMonthly(force: true);
Search broken = app broken
If search returns nothing on first use, users think the app is empty. First impressions matter - search must work immediately.
- New users don't get second chances
- "No results" = uninstall
- Testing must include cold starts
The Results
Key Lessons
Implementation Tips
- Pre-compute embeddings - Don't compute at runtime. Store in JSON, load on startup.
- Use isolates - Semantic comparison runs in background to prevent UI blocking.
- Feature flag it - Semantic can be disabled, falling back to keyword-only.
- Quality threshold - Filter results below 25% of top score to avoid noise.
Hybrid beats either alone
Don't choose between keyword and semantic. Use both. Let keyword handle exact matches, semantic handle intent. Combine scores intelligently.
Search is discovery, not retrieval
Users aren't looking for a specific file. They're exploring. Help them find what they didn't know existed. Empty results = failed discovery.
Sometimes the best solution is "both" rather than choosing one approach. Hybrid search gives users the speed of keywords with the intelligence of AI.
* * *
Next: Learn how caching makes even complex search feel instant.