Spaced Repetition Algorithm

Overview

This app uses a simplified spaced repetition system inspired by SM-2. Cards are scheduled for review at increasing intervals based on successful recall.

Interval Levels

There are 10 interval levels (0-9):

Scheduling Logic

Card Selection Priority

Cards are selected for review using the "Review First, Learn Second" principle:

This follows proven SRS best practices used by Anki and SuperMemo. Reviews always take precedence over new material to ensure retention and prevent review backlog.

Separate Tracking for Read/Write

Each card has independent progress for READ and WRITE modes:

progress[word] = {
  read: {
    intervalIndex: 0,      // Current level (0-9)
    nextReview: timestamp, // When card is due
    successCount: 0,       // Total correct answers
    failCount: 0,          // Total wrong answers
    lapseCount: 0,         // Times failed after reaching level 2+
    avgResponseTime: null, // Rolling average response time (ms)
    difficultyScore: 1.0   // Card difficulty (0.5-2.0)
  },
  write: {
    intervalIndex: 0,
    nextReview: timestamp,
    successCount: 0,
    failCount: 0,
    lapseCount: 0,
    avgResponseTime: null,
    difficultyScore: 1.0
  }
}

This means:

• You might master reading a character but still be learning to write it
• Each mode progresses independently through the interval levels
• Stats (due/practiced/mastered) are calculated separately per mode

"Mastered" Definition

A card is considered "mastered" when intervalIndex >= 4 (3+ days interval). This is displayed in the homepage stats.

Progressive Difficulty (Hint Removal)

As you progress with a card, hints are gradually removed to ensure true recall:

Why? At levels 0-1, you're still learning the card and hints help reinforce memory. By level 2, you've succeeded twice — now it's time to prove you can recall without aids. If you fail at level 2+, you reset to level 0 and hints become available again.

Initial State

For new cards (no progress data):

• nextReview defaults to 0, meaning immediately due
• Both READ and WRITE modes start as due
• Cards are shuffled on import for variety

Adaptive Difficulty System

Beyond simple correct/wrong tracking, the app measures implicit difficulty signals to adapt intervals per-card. This provides gradation without requiring extra button clicks.

Difficulty Signals

Three implicit signals determine how well you know a card:

The Eight Scenarios

Combining these signals creates a spectrum of memory strength:

Response Time Measurement

Adaptive Thresholds

What counts as "fast" or "slow" adapts to each user:

// Per-user rolling average (updated each review)
avgResponseTime = avgResponseTime * 0.8 + thisResponseTime * 0.2

// Thresholds relative to user's average
FAST = responseTime < avgResponseTime * 0.7   // 30% faster than usual
SLOW = responseTime > avgResponseTime * 1.5   // 50% slower than usual

Why adaptive? A 5-second response might be fast for a complex sentence but slow for a simple word. User-relative thresholds account for individual pace and card complexity.

Hint Usage Impact

Using a hint indicates incomplete recall, even if you get the answer right:

Key insight: If you needed the pinyin hint to pronounce it, or needed to peek at the characters to write them, you haven't truly memorized the card yet. The interval should stay the same rather than advance.

How It Works

Each card tracks a difficulty score (0.5 to 2.0) that adjusts intervals:

• Easy cards (score < 1): Intervals grow longer — review less often
• Hard cards (score > 1): Intervals shrink — review more often

Example: A 7-day base interval becomes 14 days for an easy card (score 0.5) or 3.5 days for a hard card (score 2.0).

Quick Reference: Outcome Matrix

For implementation details, see Developer Guide: Adaptive Difficulty Implementation.

Leech Detection

A "leech" is a card that consumes review time without being learned. These cards need special attention.

Leech Criteria

A card is flagged as a leech when either:

• 4+ lapses: Failed 4+ times after previously reaching level 2
• Persistently hard: Difficulty score ≥ 1.8 despite 6+ attempts

Leech Indicators Planned

Leech cards will be marked with visual indicators:

• Homepage: Warning icon next to card count
• During review: Subtle border or badge on card
• Stats: "X cards need attention" summary

Leech Recovery Strategies Planned

When a card is flagged as a leech, suggested actions:

1. Mnemonic prompt: "This card is tricky. Try creating a memory story!"
2. Related words: Show similar characters or compounds for context
3. Temporary suspension: Option to pause card and revisit later
4. Forced slow review: Require hint usage to rebuild foundation

For implementation details, see Developer Guide: Leech Detection.

Summary: The Complete Picture