Inside srs-langly: The Spaced Repetition Algorithm Behind Langly Cards

This document describes srs-langly, the spaced repetition system that schedules reviews in Langly Cards. It covers the underlying memory model, the ways the system departs from conventional SRS designs such as Anki's SM-2, how it relates to FSRS, the algorithm's internals, and the reasoning behind the design. It is written for readers already familiar with spaced repetition basics.

Overview

srs-langly consists of two layers:

• srs-core — a general-purpose scheduling engine. It models each card's memory state with two numbers, predicts recall probability over time, and derives review dates from that prediction.
• srs-langly — a language-learning layer on top of the core. It models words and sentences as cards, each quizzed through a set of modalities (recall, listening, production, dictation), books every card an appointment on a capacity-aware calendar, and plans daily sessions from a time budget rather than card counts.

Both layers are deterministic, pure functions: a review goes in, a new memory state comes out. The system contains no self-tuning component; every adaptive behavior is surfaced as a suggestion that the user explicitly accepts or declines.

Philosophy: a light daily exercise

Underneath every decision described below is one stance: spaced repetition is a supplement, not the curriculum. In Langly, the primary learning happens in real content — reading and watching material in the target language. The SRS exists to support that work and should be done in addition to it, never instead of it. A review habit that consumes most of a learner's daily study time has failed at its job, no matter how optimal its intervals are.

That stance inverts the usual priority order of SRS design. Most scheduler research concentrates on interval prediction — squeezing another point of retention accuracy out of a per-card memory model. srs-langly treats interval prediction as solved well enough and puts its weight on the other half of the problem: shaping the daily load. The scheduler's most important output is not the theoretically best due date for any single card; it is a review day that stays digestible — small, flat from day to day, and never a wall of accumulated cards.

The asymmetry justifying that trade is easy to state. A card reviewed a day or two off its optimal interval costs almost nothing — the memory model absorbs the error, and the spacing-effect bonus even rewards the late case. A Tuesday with three hundred due cards costs the habit itself, and with it every review that would have followed. What matters most is that the learner actually studies each day, so the design optimizes for the day being doable before it optimizes anything about an individual card. The capacity-aware calendar, the appointment bookings, the sustainable new-card intake, and the time-budget valve described in this article are all mechanisms in service of that single goal.

Differences from conventional SRS

Binary grading

Anki and other SM-2 derivatives ask the user to grade each answer on a four-point scale (Again / Hard / Good / Easy). Self-grading on a scale has two documented problems: it is inconsistent (the same user grades the same recall differently across sessions), and in SM-2 the grade permanently modifies the card's ease factor. Repeated "Hard" grades can push a card into a state where its intervals stop growing regardless of later performance — commonly called ease hell.

srs-langly uses binary grading: a review either succeeded or failed. The information that grade buttons attempt to capture is obtained instead from the type of quiz that was answered, described next.

Quiz modality as evidence

For vocabulary, receptive comprehension, listening, and production are distinct skills with different difficulty. Conventional SRS treats all reviews of a card as equivalent evidence. srs-langly assigns each quiz modality an evidence weight that scales the effect of the review on the card's memory state, plus a time estimate used by the daily planner:

The weighting follows the retrieval-effort principle: a successful retrieval on a harder task strengthens the memory more. The inverse also holds — a failure on an easy task (for example, failing a recall quiz) is stronger evidence that the memory is gone than a failure on a hard task, and produces a larger setback. Dictation sits at the top of the ladder because it demands recognizing the item by ear and reproducing its written form, with nothing shown on screen; it is also by far the slowest to answer, which its time estimate reflects.

Word and sentence cards

Cards come in two kinds. Both support all four modalities; what differs is the default set, and the user can change either set per deck:

Sentences leave production off by default deliberately: producing a whole sentence from its translation alone has no single right answer, so it cannot be graded cleanly as success or failure. Dictation is fair game for sentences — the audio is the prompt, so there is exactly one correct target.

Modality rotation

Every modality in a card's set is in play from its first quiz. At each review, the scheduler draws the modality uniformly at random from the modalities that card has been asked the fewest times, so a card cycles through its full set in a random order before repeating any one of them. Quizzing one card across all of its modalities replaces the common Anki workaround of maintaining separate forward and reversed decks, and the balanced-random draw keeps coverage even without making the next task predictable.

Appointment scheduling from a time budget

Conventional SRS asks the user to set a new-cards-per-day limit. The long-term cost of that setting is not visible when it is chosen: each new card adds a compounding stream of future reviews, and an overambitious setting produces a backlog weeks later. Accumulated backlogs are a primary reason users abandon spaced repetition.

srs-langly plans everything from a single input: minutes per day. That converts, via the per-modality time estimates, into a day capacity — the number of cards the daily time can absorb. Every card then holds an appointment on a shared calendar:

• Reviews. After each answer, the card's next due date is placed on the least-crowded day the memory model allows, at the least-loaded hour of that day (the placement rules are described under "Where an appointment lands" below).
• Introductions. A newly saved word is immediately booked an introduction appointment. Placement walks forward from today, taking at most the sustainable number of new cards per day and skipping days already at capacity. The sustainable rate is derived from steady state: simulation measurements show each new card per day eventually costs approximately 5, 6, or 9 reviews per day at the easy, moderate, and difficult settings respectively, so the intake rate is the day capacity divided by that figure. Saving forty words at once books them out across the coming days — and while a backlog occupies the calendar, new-card intake pauses by itself, because there are no under-capacity days to book into.
• The session. A study session simply serves the appointments that have come due, most overdue first. The time budget acts as a safety valve for backlog days: in normal operation the balancer keeps each day at or under capacity, so the cap rarely binds; after skipped days it serves the most overdue capacity-worth and parks the rest for tomorrow rather than presenting the whole pile. Cards completed earlier the same day are charged against the budget first, so a rebuilt queue offers only the time actually left.

This makes backlog accumulation structurally difficult rather than relying on the user to tune limits correctly.

Leech handling

Anki suspends cards that fail repeatedly. srs-langly instead detects struggling cards — at least 4 lapses, lapses making up at least 40% of reviews, and stability still under 7 days — and recommends capping the card to an easier modality (for example, removing production from a failing word's rotation so it is practiced as recall and listening). If the card is already at the easiest modality, the system reports that no scheduling adjustment is available; the recommended remedy is editing the card itself, such as adding context, an example sentence, or a mnemonic. Detection is advisory: the application decides whether to apply the cap, and nothing is changed silently.

Retirement

A word whose stability exceeds the deck's retirement threshold — 365 days by default, adjustable per deck — is marked as known and removed from the review queue, on the premise that ordinary reading and listening will maintain it from that point. If a retired word later fails a review, it returns to the queue automatically.

Relationship to FSRS

srs-core uses the same memory model popularized by FSRS: stability, difficulty, and a retrievability curve. The differences are deliberate design choices:

• Fixed parameters instead of per-user optimization. FSRS fits roughly 20 weights per user against their review history. srs-core ships one hand-tuned parameter set validated by simulation. This removes the cold-start problem (a new user has no history to fit), avoids unstable early-stage behavior, and keeps scheduling explainable. The cost is forgoing per-user optimality, which is modest for most users.
• Binary grading instead of four grades. FSRS consumes Anki's four-button grades and inherits their inconsistency. srs-langly replaces grade nuance with modality nuance, which is determined by what task was performed rather than by self-assessment.
• Modality awareness. FSRS has no concept of how a card was tested. In srs-langly the modality's evidence weight scales every state update. This is the language-specific layer that a general-purpose scheduler does not provide.
• No self-tuning. FSRS periodically re-optimizes its weights against the user's history. srs-langly has no adaptive machinery: parameters are fixed, and the schedule changes only when the user changes a setting, such as the deck's difficulty.

Algorithm details

Memory model

Each word's memory state is two numbers:

• Stability (S) — the number of days until recall probability decays to 90%.
• Difficulty (D) — a value from 1 to 10 representing how resistant the item is to stabilizing.

Recall probability follows the forgetting curve R(t) = 0.9^(t / S), where t is days since the last review. A word with S = 10 has a predicted 90% recall at day 10 and 81% at day 20.

Scheduling

The scheduling rule is: show the word when predicted recall falls to the deck's target retention. The target is set by the deck's difficulty setting:

A higher target produces shorter intervals and more frequent review. Due dates are derived from stability and the target at scheduling time; they are not stored as independent schedule state. Consequently, changing the difficulty setting reschedules the entire deck immediately and consistently, with no stored intervals to migrate.

Successful reviews

On success, stability is multiplied by a growth factor with three properties:

• Scaling by ease. The factor includes the term (11 − D): less difficult words grow faster.
• Damping by maturity. Growth is damped as stability rises, so early reviews multiply intervals substantially while mature words grow more slowly.
• A spacing-effect bonus. The factor increases with how far recall had decayed at review time. A successful retrieval made when the memory was nearly lost produces the largest stability gain. This also means overdue reviews automatically receive larger increases, which is the mechanism that lets a schedule recover from a study break without manual intervention.

The complete factor is scaled by the modality's evidence weight and capped at a 6× increase per review.

Failed reviews

A lapse reduces stability to approximately its square root, scaled by difficulty — a word at S = 100 days falls to roughly S = 10 rather than restarting from zero, reflecting the retained value of long-term prior knowledge. The reduction is larger when the failed modality was easy (via the inverted evidence weight) and when the word's difficulty is high. Stability never drops below a floor of 0.25 days.

Difficulty updates and mean reversion

Difficulty decreases slightly on success and increases on failure, but on every review it also reverts a fixed fraction toward the default value of 5. Sustained failures can raise a word's difficulty temporarily, but sustained success always pulls it back. A card therefore cannot be permanently degraded by a period of poor performance; the ease-hell failure mode of SM-2 is excluded by construction rather than mitigated.

Where an appointment lands

The interval the memory model wants is not a point but a window, and the balancer places the card inside it in three steps:

1. Window. The ideal interval (from stability and the retention target) opens a balance window of ±5%. Once the interval reaches 2 days the window is never narrower than ±1 day — without that floor, a young deck's cohorts (everything sitting at the ~2.5-day first interval and the ~7-day second) would come back as synchronized blocks the balancer cannot touch. Intervals under 2 days get no whole-day window at all: a lapsed card must come back promptly, so it keeps a ±5%-fuzzed timestamp and skips the remaining steps.

2. Day. Among the window's days, the least-loaded day that is still under the deck's capacity wins, ties going to the day closest to the ideal. If every window day is full, the placement spills to the nearest under-capacity day just outside the window (up to about a quarter of the interval in either direction, never earlier than the minimum interval) — chosen by nearness rather than load, because inside the window any day is schedule-acceptable but every day outside it costs retention accuracy. If even those days are full, the least-crowded window day takes the overload: capacity is a preference, not a hard constraint, so a deck bigger than its budget degrades to relative balancing instead of pushing intervals ever further out.

3. Hour. Within the chosen day, the card takes the least-loaded hour, ties going to the hour nearest its fuzzed time of day, plus a random offset within the hour. Introduction appointments use the same hour-balancer, anchored to midday.

The result is that reviews accrue in a trickle across each day instead of arriving as a midnight block — a user who checks in several times sees a few cards each visit, not the whole day's pile at breakfast — and day-to-day counts stay flat relative to what the time budget can absorb.

Design rationale

The Langly team chose to build srs-langly rather than adopt an existing scheduler for four reasons.

Vocabulary knowledge is multi-dimensional. A word is a bundle of skills — receptive recall, listening comprehension, production. A scheduler that models a word as a single fact tests only one of them. Rotating every card through its full modality set, with evidence weights reflecting each task's difficulty, addresses this directly, and no general-purpose scheduler provides an equivalent mechanism.

Configuration burden belongs in the algorithm. Experienced Anki use involves accumulated practice around grading strategy, new-card pacing, and leech management. Each of these has a structural equivalent in srs-langly: binary grading removes grading strategy, the time-budget planner removes new-card tuning, and the modality cap removes leech management. The intent is for the scheduler to embody this operational knowledge instead of requiring the user to acquire it.

Predictability is prioritized over marginal optimality. A per-user optimizer can produce somewhat better intervals, at the cost of schedules that change for reasons that cannot be inspected. srs-langly instead uses fixed, documented parameters; the only scheduling lever is the deck's difficulty setting, and it is always the user who moves it. The fixed parameters are validated the way an optimizer would be: the simulation test suite asserts flat daily load (day-to-day variation under 25%), recall calibrated near the retention target, recovery from a two-week break without a backlog spiral, and full interval growth after a lapse streak followed by successes.

Review is a means, not the goal. This is the philosophy section made concrete. The function of the SRS is to carry words to the point where immersion maintains them — hence retirement at a year of stability by default, and a daily plan bounded by a deliberately small time budget, so that the bulk of study time remains where the real learning happens: reading and listening to actual content.

Availability

srs-langly runs under every deck in Langly Cards. The scheduling behavior described here applies uniformly; the difficulty setting, time budget, and enabled modalities are configurable per deck.