5 · Scheduling, retirement & completion
Spaced repetition is really just bookkeeping: each card remembers how well you know it and when to show it next. This chapter is that bookkeeping: the scheduler, retirement, and how a whole deck reaches “done.”
Each initialized deck keeps this bookkeeping in
.alix/progress/deck-<token>.json at its content root: the workspace root for a
workspace member, or the containing folder for a loose deck.
FSRS
alix schedules with FSRS, the Free Spaced Repetition Scheduler (FSRS-5, via
the rs-fsrs crate). There’s one scheduler and nothing to choose: FSRS keeps a
small memory model per card (its stability and difficulty) and, from your
grade, works out when the card is next due.
Grading feeds FSRS a rating:
- failed → Again, a lapse; the card comes back soon and its interval shrinks
- partly → Hard, a weak success; a shorter next interval than a clean pass
- passed → Good, the interval grows
So a card you keep getting right stretches to longer and longer intervals, a miss pulls it back in, and a partly (you got the gist but stumbled) lands in between. Early on the first successful reviews are minutes-to-hours apart (FSRS’s short-term learning steps); a card graduates into the review phase (where intervals grow to days, then weeks) only after two spaced correct recalls, and missing it resets that progress, so a slip doesn’t shortcut it.
A session shows each due card once. Miss one and it returns spaced (after its short step, interleaved behind other cards) not drilled again the instant you saw the answer (which would test your working memory, not your recall). That gap is floored at the moment you actually move off the card, not when you first saw the answer, so time spent on the feedback screen or working the next card still counts against a short retry interval. When nothing is due right now the session ends; a card still cooling is picked up the next session, or slots back in on its own if you leave the window open.
One knob shapes the whole schedule: retention, the recall probability FSRS
aims for (0.70–0.99, default 0.9). Raise it to see cards more often, lower it to
stretch the gaps. Set it in the [review] config section, or per workspace in an
alix.local.toml (see Configuration).
A workspace deadline
Set a personal deadline on a workspace (Workspaces) and
scheduling leans toward it while the date hasn’t passed: FSRS intervals cap at
the days left (floored at one day), the target retention ramps up linearly to a
fixed 0.95 over the last deadline_ramp days (never lowering a higher personal
retention), and a due-date ceiling keeps anything from being scheduled past
the deadline day. Once the date passes, both the cap and the ramp lift and
scheduling releases back to your base pacing automatically.
New cards: an attempt before they’re tested
A card you’ve never seen isn’t quizzed cold (you can’t reconstruct what you’ve
never read) but it isn’t simply handed to you either, whichever depth you’re
reviewing at. The first encounter is a low-stakes attempt, then the answer,
then one key (Seen) records it without a grade. Usually: the front shows
first, you try, then reveal. On the web you can then hide and show the answer
again (h, or a tap on it) to self-test the fresh encoding before you press
Seen; it flips only the answer’s visibility, so the note, the buttons, and the
layout stay put. If the card has authored choice options, or the deck has AI
distractors (alix deck augment --target choices) and the card is atomic
(single-line answer), it instead
greets you as a multiple-choice question: pick one, see which was right.
Either way a guess records no grade and never punishes it, and the first
graded quiz then comes back later in the same session (once a settle
gap passes it resurfaces, interleaved behind the other cards you’re seeing),
so seeing a deck flows straight into drilling it. That gap is
introduction_cooldown in the [review] config (default "5m"); it also
sets the floor before any just-seen card (a miss, a wrong pick) may return,
so nothing you moved off comes straight back. "0" disables both gaps. If the
gap passes while you are sitting on the session summary, the summary says so
and arms Continue; it never starts the next card for you. Each sitting serves up to max_session cards
(default 10); its new-card share is new_cards_percent (default 30%, so three
of ten) and the rest are due cards, with whichever pool runs short letting the
other fill the cap (a fresh deck fills entirely with new, a deck with nothing
new fills entirely with due). A larger backlog therefore slows introductions
proportionally, so chain another sitting when a deadline is near. Both keys live
in [review] (see Configuration; a workspace can
override them in its alix.local.toml), and --session N overrides
max_session for one launch. This holds at every depth, Recognize included: a
Recognize sitting splits the same cap between never-met cards and cards due
at Recognize.
This is the first step of a card’s life: introduce, then let its depth(s)
schedule it.
Session depths: Recognize, Recall, Reconstruct
FSRS decides when a card is due; the session depth decides how deeply it’s asked when it comes up. A session runs at one of three independent depths, picked when you start it (the web picker’s Depth… menu). See Reveal & session depths for the full check matrix. In short:
- Recognize, Recall, and Reconstruct each keep their own FSRS schedule per card, so a card can be due for one and not the other; nothing cross-credits between them, with one downward exception below.
- Recognize schedules at its own desired retention (
recognize_retention, default 0.85) rather than the deck-wideretention: one mechanism, two tunings.
Nothing climbs or descends between depths on its own. A card doesn’t get harder over time just by surviving reviews. Which depth you exercise, and when, is entirely your call each session.
The exception flows downward, and only on a full pass: get a card fully right at a deeper depth (in cram: only when it was due) and that also counts for every shallower schedule the card already has. Reconstruct credits Recall and Recognize, Recall credits Recognize: if you can produce the answer, you can certainly recall and recognize it, so alix won’t re-ask an easier form days later. If the shallower depth was due at that moment, the pass stands in for that review: full schedule credit, recorded in the card’s history and marked as propagated. If its schedule existed but wasn’t due yet, only its due date is pushed out from now (memory untouched, nothing recorded, the same refresh a cram pass gets). A partly or a miss never propagates, and a missing schedule is never created: a card drilled only at Reconstruct never gains a recall or recognize schedule from this.
Badges
A deck can earn a badge at each depth, shown in the picker: a quick read on how solid it is, never a gate on anything (only passing the AI exam unlocks a dependent deck). A deck earns a depth’s badge once every one of its cards is currently solid at that depth: at or past 21 days of FSRS stability (in practice a few weeks of regular drilling), the same bar at all three depths, Recognize included. Only the highest badged depth shows: solid while the deck still clears the bar, dotted once a card has since lapsed below it (a badge, once earned, keeps its date, a high-water mark, not a live pass/fail).
A deck shows a small “new” chip while any of its cards has never been presented, whether or not the deck is badged. It clears only once every card has been seen at least once, so a large deck you are working through keeps the chip until you reach the end of it: the chip answers “is there anything in here I have never met?”, not “have I started this deck?”.
Retiring cards
A card doesn’t stay in rotation forever. Once its interval grows past
retire_after (default one year), the card retires: it rests and is no
longer scheduled, not even under cram, until you alix reset it. Set
retire_after = "never" to keep drilling a deck forever (facts you never want to
risk forgetting); a workspace can override it in its alix.local.toml.
Completion states
A deck’s state is derived from how far its cards have progressed, and shown in
the picker and alix stats:
- not started: you haven’t reviewed any card yet
- started: somewhere in between
- finished (
done ✓): every card has graduated (reached FSRS’s review phase, past the initial learning steps)
A deck that declares a source: adds one state in between: exam due. For
those decks, drilling the cards no longer finishes them: passing the AI exam
does, which marks the deck mastered. That’s the subject of a later chapter.
Unlocks, in one line
Completion also drives dependencies, with no extra syntax: a deck’s exam is locked while any of its sourced prerequisites hasn’t passed its own exam. The deck itself stays drillable throughout. Passing a foundation’s exam unlocks the exams that build on it. The lock is advisory and recomputed live. The dependencies chapter covers it in full.
Cramming
Need to review everything now, schedule be damned, the night before an exam?
Cram ignores due times and shows every card that isn’t retired, at every
depth (the sitting stays bounded by max_session; at Recognize the pick-only
filter still applies, so only cards with something to pick from appear).
It’s a per-launch tick-box in the picker’s Depth… menu (key c while the
menu is open); plain Learn never crams. On the phone it is the Cram
switch in the sheet a long-press on a deck row opens.
Cram changes which cards are queued, never how a due card is graded: a card that was genuinely due grades exactly like a normal review: full schedule credit, recorded (a due Reconstruct pass even propagates to Recall as usual). Only a pass on a card that wasn’t due yet is treated as the low-information event it is: its due date re-anchors by the current interval, memory untouched, nothing recorded, so a heavy grind can’t inflate your long-term spacing. A card you miss under cram always lapses normally. Retired cards stay out (that’s what retirement is for).
Review order
By default your due cards come up in scheduler order: soonest-due first. That’s right for retention, but it can feel random: a card about parsing, then one about persistence, with no thread between them.
A review order gives the session a thread. alix deck augment <deck> --target order asks the model to read the deck and lay out a graph of how the cards
relate: a suggested walk through them, plus a few coarse named regions
(stages or themes). It’s cached in the deck’s shareable augmentation document
alongside distractors and notes;
a deck can hold several, one per --with principle:
alix deck augment internals.md --target order
alix deck augment capitals.md --target order --with "north to south"
alix deck augment capitals.md --target order --with "by continent"
Then review along it: select the deck in the web picker and an inline focus drawer opens beneath it: choose which order runs the session (“Whole deck” is the default), then start.
The key thing: this changes only the order, never the schedule. SRS still decides which cards are due and how they advance. The order just serves that due set in walk order instead of shuffled, so each card is a natural follow-up to the last. Not-due cards are skipped, so the session stays as short as your due pile.
As you go, a thin region breadcrumb sits above each card (e.g.
Ingestion · Review Engine · Persistence · Frontends, the one you’re in
emphasized) so you see where you are in the material, not just what’s in front
of you. The names are deliberately coarse: they orient without giving away any
card’s answer. Under each region is a card-tier heatmap: one small cell
per card. Neutral means untouched; grey means seen (you met the card:
acknowledged it, or answered and got it wrong); white means learning (at
least one full or partly pass, not yet graduated); a learned (graduated) card is green, yellow, or red by how
well you’d recall it right now; purple means retired. An outlined cell,
unfilled, is a sub-card still
gated on its parent’s graduation, which is why it is usually untouched as well.
A region visibly greens up as you master it, and the breadcrumb doubles as a
progress map.
To drill one weak region on its own, tap its heatmap in the focus drawer to scope the launch to it.
SRS still chooses what’s due within that region. You’ve just narrowed the session to it.
The choice is made before the session; the in-card breadcrumb itself stays read-only. The breadcrumb, the heatmap, and the ordering are all in place; richer map views are still to come.