Sort items by frecency (frequency + recency)

[lalvarezt]

Sorts fzf results based on your selection history, prioritizing items you return to often and those you touched most recently.

Note: Author has stated (#777, #1213) that they're not interested in adding this functionality, so I thought I'll give it a try.

How it works:

• Tracks every selection: increments the counter, records the latest timestamp, and remembers the previous one.
• Computes a continuous score
  raw = log₂(frequency + 1) × 0.5^(age / 30d) × momentum
  • Frequency is log-compressed so long-term favorites still matter without overwhelming everything.
  • Age applies a 30-day half-life, so stale entries fade steadily.
  • Momentum gives up to a 50 % boost when you pick the same item again within six hours (otherwise it stays at 1.0).

Usage:

fzf --tiebreak=frecency,score,length  # Enable frecency sorting (equiv to --frecency)
fzf --frecency-file=PATH              # Custom database location, defaults to: ~/.cache/fzf/frecency.gob
fzf --frecency-debug                  # Show database contents with raw/decay/momentum metrics

Inspired by: zoxide's frecency algorithm for directory jumping.

You can check it here (frecency branch)
https://github.com/lalvarezt/fzf/tree/frecency

---

Updates

2025-10-29

• Tiebreak integration: Frecency now integrates via fzf's standard --tiebreak mechanism instead of being prepended to criteria.

  • Add frecency and score as explicit tiebreak criteria
  • When frecency is the first criterion in --tiebreak, byScore is not auto-prepended (allows frecency-first sorting)
  • --frecency flag remains as backward-compatible shorthand for --tiebreak=frecency,score,length

• Flexible criterion ordering: Users can now position frecency anywhere in the sort order:

  fzf --tiebreak=frecency,score,length  # Frecency primary (equiv to --frecency)
  fzf --tiebreak=score,frecency,length  # Score primary, frecency secondary
  fzf --tiebreak=frecency,pathname      # Custom combinations

• Frecency scoring: Simplify frecency scaling and optimize for realistic frequency ranges
  Score distribution across realistic usage patterns:

  Frequency	Age	Momentum	Raw Score	Scaled	% uint16
  15,000	0d	1.5	20.81	65,535	100.0%
  10,000	0d	1.5	19.94	62,811	95.8%
  10,000	30d	1.0	6.64	20,916	31.9%
  2,000	0d	1.5	16.47	51,881	79.2%
  2,000	30d	1.0	5.49	17,294	26.4%
  500	0d	1.5	13.47	42,431	64.7%
  500	30d	1.0	4.49	14,144	21.6%
  10	0d	1.0	3.46	10,899	16.6%
  10	30d	1.0	1.73	5,450	8.3%

2025-10-27

• Optimizes frecency scoring by pre-calculating all scores once at startup using a frozen sessionTime, making GetScore a simple O(1) cache lookup instead of recalculating expensive math.Exp on every call.
• Removes dead code and improves consistency

2025-10-15

• Switched to the continuous log/half-life/momentum scoring model and expanded --frecency-debug to surface raw, decay, momentum, and scaled columns.
• Better overall documentation.

2025-10-10

• Added new actions to manage the frecency database

  • frecency-entry-buff
  • frecency-entry-nerf
  • frecency-entry-remove

  It can be used like so:

  fzf --frecency --bind alt-r:frecency-entry-nerf --bind alt-t:frecency-entry-buff