fluent-sm2-calculator

SM-2 Calculator

Overview

Fluent uses SM-2 (SuperMemo 2) to decide when the learner next sees an item. This skill is the single source of truth for the algorithm. Every practice skill updates <data_dir>/spaced-repetition.json (where <data_dir> is resolved by fluent_paths.data_dir()) through these rules after each answered question.

When to Use

Load this skill whenever the tutor:

• Grades a review-queue item and must compute its next due date.
• Maps a 0-10 score to an SM-2 quality.
• Updates easiness_factor, interval_days, repetitions, or mastery_level on a spaced-repetition item.
• Decides which queue (today / tomorrow / this_week / later) to place an item in.

Skip this skill when the fluent-db-updater skill is already being used — the update-db.py script runs SM-2 internally.

Instructions

1. Convert score to quality

Score	Quality	Meaning
10/10	5	Perfect, instant recall
8-9	4	Correct after hesitation
6-7	3	Correct with difficulty
4-5	2	Incorrect but remembered when shown
2-3	1	Incorrect, familiar
0-1	0	Complete blackout

Rule: quality = floor(score / 2).

2. Update interval

if quality >= 3:   # correct
    if repetitions == 0:
        interval = 1
    elif repetitions == 1:
        interval = 6
    else:
        interval = round(previous_interval * easiness_factor)
    repetitions += 1
else:              # incorrect
    interval = 1
    repetitions = 0

3. Update easiness factor

Apply after every answer:

EF_new = EF + (0.1 - (5 - quality) * (0.08 + (5 - quality) * 0.02))
EF_new = max(1.3, EF_new)

4. Update mastery level

Track consecutive_correct and consecutive_incorrect per item:

if consecutive_correct >= 5:
    mastery_level = min(5, mastery_level + 1)
    consecutive_correct = 0
elif consecutive_incorrect >= 3:
    mastery_level = max(0, mastery_level - 1)
    consecutive_incorrect = 0