tai/research/fuzzy-matching-selectors/github-fzy-algorithm-md.md

fzy ALGORITHM.md

Metadata

Field	Value
Institute	Molodetz Institute — Research & Retrieval Division
Subject	fuzzy-matching-selectors
Document type	Source Dossier
Tier	1
Source title	fzy ALGORITHM.md
Source URL	https://github.com/jhawthorn/fzy/blob/master/ALGORITHM.md
Source publisher / author	jhawthorn (fzy maintainer)
Source type	repository
Source date (published)	Unknown — not stated
Date researched	2026-10-25
Researched by	tai (agent), model: Claude Sonnet 5, on behalf of retoor
Research method	direct page fetch
Confidence	Medium
Status	Active

Summary

The design note of fzy, a terminal fuzzy selector. It frames fuzzy scoring as a modified edit-distance problem solved with a dynamic program, and compares fzy to other finders. The page names the bonuses and penalties but the fetched text carries no numeric values or complexity analysis.

Key findings

• Scoring is treated as a modified edit distance related to Levenshtein, with dynamic programming similar to Wagner-Fischer and Needleman-Wunsch.
• The matrix is n-by-m (search length by candidate length); an affine gap penalty inspired by the Gotoh algorithm is used.
• A second matrix D holds the best score which ends in a match, computed alongside the score matrix.
• Penalties (negative): gaps at the start of the match, at the end, and inside the match. Bonuses (positive): consecutive match, after a slash, start of a word (after space, underscore or dash), a capital letter (CamelCase), after a dot.
• Comparison: fzf takes the first match with some logic to find a shorter one but is not guaranteed shortest; ctrlp, pick and selecta (<= 0.0.6) score by the length of the first match; pick can find the absolute shortest match at a speed cost; selecta master compares only the shortest match from the same start; fuzzaldrin-plus uses Smith-Waterman.
• Stated limitations: every search is case-insensitive (scoring favors uppercase matches; smart case is suggested), and the page says fuzzy matching only accepts insertions, not deletions or substitutions.

Pros / strengths

A clear statement of the model (consecutive + word-start + camelCase bonuses, gap penalties) and a useful comparison of why first-match and shortest-match schemes misrank.

Cons / limitations / caveats

No constants and no complexity in the fetched text; the recurrences live in src/match.c. The Command-t section is marked incomplete by the author. Not a measured evaluation, a design note.

Relevance to tai

Gave the bonus taxonomy and the D/M two-matrix recurrence structure that tai's FuzzyMatcher::Subsequence follows. Constants were taken from fzf instead (see the fzf-algo-go dossier) because they were actually retrieved.

Changelog

Date	Change
2026-10-25	Initial dossier created.