# How Context-Mode Handles Fuzzy Correction for Misspelled Search Queries

> Learn how Context-mode handles fuzzy correction for misspelled search queries using Levenshtein distance, SQLite, and caching for efficient results.

- Repository: [Mert Köseoğlu/context-mode](https://github.com/mksglu/context-mode)
- Tags: how-to-guide
- Published: 2026-04-24

---

**Context-mode corrects misspelled query terms using a Levenshtein distance algorithm with dynamic edit-distance ceilings, SQLite-backed vocabulary lookups, and an in-memory LRU cache to optimize repeated corrections.**

The `mksglu/context-mode` repository implements an intelligent typo-tolerance system that automatically fixes misspelled search queries before executing the search. Understanding how this **fuzzy correction for misspelled search queries** works reveals a sophisticated multi-stage pipeline that balances accuracy with performance through dynamic distance calculations and strategic caching.

## The Three-Stage Fuzzy Correction Pipeline

The core correction logic resides in [`src/store.ts`](https://github.com/mksglu/context-mode/blob/main/src/store.ts) and operates through three distinct computational stages.

### Stage 1: Dynamic Edit-Distance Ceiling Calculation

Before comparing strings, the system calculates a maximum allowable edit distance based on query word length. The `maxEditDistance(wordLength)` function at [`src/store.ts:L139-L143`](https://github.com/mksglu/context-mode/blob/main/src/store.ts#L139-L143) returns `1`, `2`, or `3` depending on the input length, ensuring short words receive tighter tolerance limits while longer words allow more flexibility for typos.

### Stage 2: SQLite Vocabulary Candidate Lookup

Once the ceiling is established, the system queries the SQLite database using the prepared statement `#stmtFuzzyVocab`. This operation, defined at [`src/store.ts:L333-L337`](https://github.com/mksglu/context-mode/blob/main/src/store.ts#L333-L337), retrieves all vocabulary entries whose length falls within `word.length ± maxDist`, narrowing the candidate pool to plausible matches before expensive distance calculations begin.

### Stage 3: Levenshtein Distance Scoring and Selection

For each candidate retrieved, the classic **Levenshtein distance** algorithm computes the exact edit distance between the misspelled term and the candidate vocabulary word. The implementation at [`src/store.ts:L902-L946`](https://github.com/mksglu/context-mode/blob/main/src/store.ts#L902-L946) selects the candidate with the smallest distance that remains within the calculated ceiling. If an exact match exists, the function returns `null` to indicate no correction is necessary.

## Caching Strategy for Performance Optimization

To prevent redundant database queries and repeated distance calculations, context-mode employs an LRU (Least Recently Used) cache strategy.

### In-Process LRU Cache Implementation

The private field `#fuzzyCache` stores correction results as `string | null` mappings between misspelled inputs and their corrections. When `fuzzyCorrect()` executes, it first checks this cache at [`src/store.ts:L906-L915`](https://github.com/mksglu/context-mode/blob/main/src/store.ts#L906-L915). Cache hits are promoted to the tail of the LRU structure, keeping frequently accessed corrections in fast memory. Once the cache exceeds `ContentStore.FUZZY_CACHE_SIZE`, the least recently used entries are evicted automatically at [`src/store.ts:L939-L945`](https://github.com/mksglu/context-mode/blob/main/src/store.ts#L939-L945).

## End-to-End Query Processing and Fallback Strategy

Individual word corrections integrate into the broader search architecture through the `searchWithFallback()` method.

### Multi-Word Query Correction

When processing a search query, `searchWithFallback()` at [`src/store.ts:L653-L670`](https://github.com/mksglu/context-mode/blob/main/src/store.ts#L653-L670) splits the input into individual tokens. It skips stop-words and words shorter than three characters, then invokes `fuzzyCorrect()` on each remaining term. The system rebuilds the query string with corrected terms, and if any modifications occurred, re-executes the search through the RRF-fusion pipeline.

### Result Layer Tagging

Corrected queries are tagged with `matchLayer: "rrf-fuzzy"` to distinguish them from direct hits. This metadata allows downstream consumers to identify when results originate from fuzzy-corrected searches rather than exact matches, providing transparency into the search process.

## Implementation Examples

The following examples demonstrate the fuzzy correction API in practice.

### Basic Fuzzy-Corrected Search

```typescript
import { ContentStore } from "./src/store.js";

const store = new ContentStore();

// Index content containing the correct term
store.index({ content: "# Authentication\n\nThe system uses **authentication** tokens.", source: "doc:auth" });

// Search with a misspelled query
const results = store.searchWithFallback("autentication", 5);
console.log(results[0].matchLayer); // → "rrf-fuzzy"
console.log(results[0].title);      // → "Authentication"

```

This example triggers the complete correction pipeline described in [`src/store.ts:L653-L670`](https://github.com/mksglu/context-mode/blob/main/src/store.ts#L653-L670).

### Direct Correction Inspection

```typescript
const correction = store.fuzzyCorrect("orchestraton"); // typo for "orchestration"
console.log(correction); // → "orchestration"

```

The `fuzzyCorrect` method at [`src/store.ts:L902-L946`](https://github.com/mksglu/context-mode/blob/main/src/store.ts#L902-L946) returns the corrected string or `null` if no suitable candidate exists within the maximum edit distance.

### Cache Behavior Verification

```typescript
// First lookup populates the cache
store.fuzzyCorrect("authentiction");

// Second lookup hits cache, avoiding database work
store.fuzzyCorrect("authentiction"); // Retrieved from #fuzzyCache

```

The LRU eviction policy activates when the cache size exceeds `ContentStore.FUZZY_CACHE_SIZE`, as implemented at [`src/store.ts:L939-L945`](https://github.com/mksglu/context-mode/blob/main/src/store.ts#L939-L945).

## Summary

- Context-mode calculates dynamic edit-distance ceilings via `maxEditDistance()`, allowing tighter tolerance for short words and more flexibility for long words.
- The system queries SQLite vocabulary using `#stmtFuzzyVocab` and filters candidates by length proximity before computing exact Levenshtein distances.
- An LRU cache (`#fuzzyCache`) eliminates redundant correction work for repeated misspellings, with automatic eviction when size limits are exceeded.
- The `searchWithFallback()` method orchestrates multi-word corrections, skipping stop-words and short tokens while tagging results with `matchLayer: "rrf-fuzzy"` for transparency.

## Frequently Asked Questions

### What algorithm does context-mode use for fuzzy correction?

Context-mode uses the classic **Levenshtein distance** algorithm to calculate the edit distance between misspelled query terms and vocabulary candidates. The implementation dynamically adjusts the maximum allowed distance based on word length, ensuring short words like "cat" don't match distant alternatives while longer technical terms have more tolerance for typos.

### How does the fuzzy correction cache work?

The system maintains an in-process LRU (Least Recently Used) cache via the private `#fuzzyCache` field. When `fuzzyCorrect()` encounters a previously seen misspelling, it returns the cached result immediately without querying the SQLite database. Frequently accessed corrections migrate to the tail of the cache structure, while entries exceeding `ContentStore.FUZZY_CACHE_SIZE` are evicted from the front.

### Which words get skipped during fuzzy correction?

The `searchWithFallback()` method intentionally skips two categories of tokens: standard stop-words (common words like "the" or "and") and any word shorter than three characters. This optimization prevents the system from attempting to correct short functional words where corrections would likely introduce false positives rather than helpful fixes.

### How can I identify if search results came from a corrected query?

Results originating from fuzzy-corrected queries carry the metadata `matchLayer: "rrf-fuzzy"` rather than standard layer identifiers. This tagging occurs in `searchWithFallback()` at [`src/store.ts:L653-L670`](https://github.com/mksglu/context-mode/blob/main/src/store.ts#L653-L670), allowing your application to indicate to users when results match a corrected version of their original input.