spaced-repetition

name	spaced-repetition
description	SM-2 spaced repetition algorithm implementation reference for flashcard-engine. Use when implementing or modifying the SM-2 scheduling algorithm, calculating next review dates, or understanding how interval and ease factor are computed.

spaced-repetition

SM-2 algorithm reference for flashcard-engine.

When to use

• Implementing the SM-2 algorithm in packages/server/src/lib/sm2.ts
• Writing tests for SM-2 calculations
• Debugging incorrect review intervals
• Modifying scheduling behavior

SM-2 Algorithm

All SM-2 logic lives in packages/server/src/lib/sm2.ts. No other file performs SM-2 calculations.

State

interface SM2State {
  interval: number;      // days until next review
  repetitions: number;   // consecutive correct reviews
  easeFactor: number;    // difficulty multiplier (min 1.3)
  nextReview: string;    // YYYY-MM-DD date string
}

Grade meanings

Grade	Behavior
0, 1, 2	Reset: interval = 1, repetitions = 0
3, 4, 5	Advance using SM-2 formula

Interval calculation (grade >= 3)

if repetitions == 0: interval = 1
if repetitions == 1: interval = 6
if repetitions > 1:  interval = round(prevInterval * easeFactor)

EaseFactor update (grade >= 3)

easeFactor = max(1.3, easeFactor + 0.1 - (5 - grade) * (0.08 + (5 - grade) * 0.02))

Grade 5 (perfect): easeFactor increases by 0.1 Grade 4 (easy): easeFactor unchanged Grade 3 (good): easeFactor decreases by 0.14

Next review date

nextReview = today + interval days (YYYY-MM-DD format, UTC)

Test Cases

The SM-2 unit tests in packages/server/src/lib/sm2.test.ts must cover:

1. Grade 0 on new card: interval=1, repetitions=0, easeFactor=2.5
2. Grade 5 on new card: interval=1, repetitions=1
3. Grade 5 twice: interval=6, repetitions=2
4. Grade 5 three times: interval=round(6*2.6)=16, repetitions=3
5. Grade 4 three times: easeFactor stays 2.5, interval grows correctly
6. Grade 3 repeatedly: easeFactor decreases, stays >= 1.3
7. Grade 2 on mature card: resets interval to 1, repetitions to 0
8. EaseFactor minimum 1.3 is enforced

Database integration

The review flow in packages/server/src/routes/study.ts:

// 1. Load current card state from database
// 2. Call applyGrade(currentState, grade)
// 3. Write new state to cards table
// 4. Insert row into review_log table
// 5. Return new state in response

All database writes happen in a single transaction per review.