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-11-18

• Configurable frecency parameters: All frecency algorithm parameters are now exposed as command-line flags, allowing users to tune the scoring behavior for different workflows.

  • --frecency-scale-factor=N (default: 3150.0) — Adjusts score separation in the uint16 range. Increase this value (e.g., 5000 or 10000) if items with similar usage patterns sort inconsistently due to score collisions.
  • --frecency-half-life=DURATION (default: 30d) — Controls decay rate. Use shorter values like 7d for weekly projects where last week's files should fade quickly, or longer values like 90d for reference materials accessed irregularly over months.
  • --frecency-momentum-window=DURATION (default: 6h) — Sets the time window for momentum boost calculation. Use 1h for focused coding sessions or 12h for full workday context.
  • --frecency-momentum-boost=N (default: 0.5, range: 0.0–1.0) — Maximum momentum multiplier. Higher values (e.g., 1.0) strongly favor burst activity; lower values (e.g., 0.2) reduce the burst effect. Set to 0.0 to disable momentum entirely.

• Flexible duration parsing: Duration flags accept both Go's native format (24h, 168h) and common shorthands (d for days, w for weeks, mo for months, y for years).

• Tuning example for weekly projects:

  find . -type f | fzf --frecency --frecency-half-life=7d --frecency-momentum-window=2h

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