Frecency

Frecency

Frecency (frequency + recency) automatically boosts items the user selects frequently or recently.

How It Works

Each time an item is selected, the frecency engine records:

• Frequency — How many times the item has been selected
• Last used — Timestamp via Temporal.Now.instant()

The bonus is calculated using exponential decay buckets:

Time Since Last Use	Weight (default)
< 1 hour	4.0x
< 1 day	2.0x
< 1 week	1.5x
< 1 month	1.0x
> 1 month	0.5x

Formula: bonus = frequency × recencyWeight

Bucket boundaries use Temporal.Duration for human-readable configuration:

const BUCKETS = {
  hour: Temporal.Duration.from({ hours: 1 }),
  day: Temporal.Duration.from({ hours: 24 }),
  week: Temporal.Duration.from({ days: 7 }),
  month: Temporal.Duration.from({ days: 30 }),
};

Enabling Frecency

React

<Command frecency={{ enabled: true }}>
  ...
</Command>

Core Engine

using machine = createCommandMachine({
  items,
  frecency: { enabled: true },
});

IndexedDB Persistence

Persist frecency data across sessions:

import { IdbFrecencyStorage } from 'modern-cmdk';

using machine = createCommandMachine({
  items,
  frecency: {
    enabled: true,
    storage: new IdbFrecencyStorage(),
    namespace: 'my-app',
  },
});

Custom Decay Weights

using machine = createCommandMachine({
  items,
  frecency: {
    enabled: true,
    decayConfig: {
      hourWeight: 6.0,    // Heavily favor recent selections
      dayWeight: 3.0,
      weekWeight: 1.0,
      monthWeight: 0.5,
      olderWeight: 0.1,   // Strongly penalize old selections
    },
  },
});