FSRS: a spaced repetition scheduler built on difficulty, stability and retrievability

A specification repository with four files and no code

The repository is unusual for a project that people actually depend on, because it contains no implementation. Its top level holds .gitignore, LICENSE, README.md and README_CN.md, and the Chinese introduction is linked from the English one.

What the repository does contain is the reasoning. It documents the algorithm, it states the memory laws the scheduler follows, and it points at where the code lives.

The line that explains the name is worth reading carefully. The algorithm supports reviewing in advance or delayed, and it is free for users to decide the time of review, and it adapts to the user's memory. That is the sense of free here: freedom in when a review happens, not freedom from cost. The README pairs that with the claim that spaced repetition is an essential technology for free learning, and with the point that FSRS runs entirely locally and has no risk under others' control.

That last sentence is the argument for a self-hosted scheduler in one line. A hosted flashcard service can change its algorithm, change its pricing, or disappear, and a review history collected under one scheduling model is hard to move to another. A local algorithm with published internals can be re-implemented, audited and kept.

The homepage for the project is the wiki page for the algorithm itself, which is where the actual formula lives rather than in the repository.

Difficulty, stability and retrievability as the three inputs

The model behind FSRS considers three variables that affect memory: difficulty, stability and retrievability. The README defines two of them in detail.

Stability refers to the storage strength of memory. The higher the stability, the slower the memory is forgotten. Retrievability refers to the retrieval strength of memory, and the lower it is, the higher the probability that the memory will be forgotten.

Difficulty is named as the third variable but is not separately defined in the repository text, so it is worth noting that the documentation leaves its definition to the algorithm page rather than assuming one.

What makes these variables useful is that they map onto things a review system can observe. Retrievability is what the learner is being tested on at review time. Stability is the model's estimate of how long the memory will last, and it is what changes as a result of each answer. Difficulty explains why the same answer produces different stability gains for different items.

For an implementer, this is the important structural point: the scheduler is not a table of intervals. It computes a next interval from a small set of state variables and a memory model, which is why the same review history can produce different schedules depending on how the parameters are fitted.

The three memory laws the scheduler is built on

Three laws are listed, and they are the whole behavioural contract of the scheduler.

The first is that the more complex the item being memorised, the lower the stability increase. In practice, a hard item that you did get right produces a smaller jump in stability than an easy one. This is the law that makes difficulty matter rather than being a decorative constant.

The second is that the higher the stability, the lower the stability increase, and the README links this to the well known stabilization decay effect. Stability gains shrink as stability grows, which is what keeps intervals growing without the growth rate being constant.

The third is that the lower the retrievability, the higher the stability increase, linked to the stabilization curve. A memory that was nearly forgotten and is then recalled goes up more in stability than one that was still fresh. This is the counter-intuitive part, and it is the mechanism by which a hard review can produce a long interval.

Taken together, the three laws describe a scheduler that increases intervals when recall succeeds, increases them more when recall nearly failed, and slows down as the memory becomes well established. The repository links the DSR model to Piotr Wozniak and describes FSRS as springing from MaiMemo's DHP model, which it calls a variant of that DSR model, so the lineage runs from a three component model of memory through a published paper to this algorithm.

Where the implementations actually live, language by language

The repository lists the libraries that implement the scheduler and the tools that fit its parameters, and this list is the practical entry point for a developer.

The scheduler libraries cover TypeScript in ts-fsrs, Go in go-fsrs, Python in py-fsrs, Rust in rs-fsrs, Clojure in cljc-fsrs, Dart in dart-fsrs, Ruby in rb-fsrs, Swift in swift-fsrs, Android in android-fsrs and Elixir in ex_fsrs.

Separately there is an optimizer. A Python package, fsrs-optimizer, is marked stable, and an RS crate, fsrs-rs, is also marked stable, with a note that fsrs-rs can be run in the browser through fsrs-browser.

The distinction between the two groups is the thing to get right. The scheduler computes the next review time from parameters. The optimizer fits those parameters from a review history, and the README marks both optimizer options as stable while giving no stability marker to the scheduler libraries. If you want the algorithm to adapt to a particular learner rather than to a generic default, the optimizer is the piece that does the adapting, and the parameters it produces are then what the scheduler consumes.

The algorithm itself is documented on the wiki page The Algorithm, linked from the repository and given as the project homepage, and the README refers to it as the formula of memory on FSRS. That page is the specification the libraries implement.

What choosing FSRS costs you in review history data

The model has a consequence for anyone switching an existing flashcard system, and it is not visible from the library list.

Because stability is a state variable that evolves with each answer, the scheduler is only as good as the review history that produced its parameters. A user who arrives from a system using fixed intervals brings a history with no stability information in it, so the scheduler has to bootstrap its estimate of stability for each item from scratch. Items that were reviewed on a fixed interval schedule will get an interval that reflects the model's initial guess rather than anything measured about the learner.

The second consequence is the optimizer's input. To fit parameters to a learner you need a review log with enough reviews per item and enough distinct items. The repository does not document the required fields, the minimum history length, or the format the optimizer expects, so that has to come from the fsrs-optimizer and fsrs-rs projects rather than from here.

A third and more mundane constraint is that FSRS runs entirely locally. That is presented as a benefit and it is one, but it also means the scheduling happens on the device or on your own server. A study tool that a user opens on a shared laptop, or a class of students on school-managed machines, needs somewhere for the review state to live. The repository does not describe any client, only the algorithm and the libraries that compute it, so that product decision stays with the implementer.

How FSRS compares with fixed interval scheduling

The alternative worth naming is the fixed interval scheduler, where a correct answer moves the item to the next rung of a ladder such as one day, three days, then a week, and a wrong answer sends it back to the start.

The difference in approach is straightforward. A fixed ladder has no memory model at all. Every item on the ladder is treated the same way, regardless of how the learner actually recalled it or how hard the item is. The interval depends only on the answer and the item's position on the ladder.

FSRS replaces that with a computation. Stability is estimated for the item, retrievability describes the probability of recall at the moment of review, and the three memory laws decide how much stability moves given the answer and the current state. Two items answered the same way can therefore get different intervals, and the same item can get different intervals depending on how long ago it was last seen and how close it came to being forgotten.

The practical payoff of that model is the third law. Because a near-miss produces a larger stability increase than a comfortable recall, the schedule rewards the reviews that actually carry information. A fixed ladder treats an easy recall and a barely recalled item identically, which is a meaningful difference when the learner's time is the scarce resource.

The cost is complexity and a dependency on review data. A fixed ladder is a lookup table you can implement in an afternoon and that produces the same schedule for every learner. FSRS needs a parameter set, an optimizer to derive one, and a review history to feed it.

Maintenance state and the MIT licence

The project is licensed MIT, with the LICENSE file at the repository root. That is a permissive licence with no copyleft obligation on code that uses the algorithm, which matters here because the algorithm itself is implemented in a dozen separate libraries and each of those carries its own licence terms.

The repository is not archived, and the last push was on 2026-04-21, which is more than six months before this article. There are no tagged releases, so there is no version to pin for the specification itself.

That distinction is the thing to keep in mind when you plan an adoption. This repository is a description of an algorithm, and the description changes less often than the code. The implementations are separate projects with their own release cycles, and the README marks the optimizer implementations as stable, which is a signal about those packages rather than about this repository. When you pick a language binding, you are picking that package's maintenance state, not this one.

A second practical note is that the formula lives on a wiki page under the awesome-fsrs repository rather than in the code you depend on. If you want your scheduler's behaviour to stay stable across library upgrades, capture the parameter set your build uses and pin the scheduler package version, because a change in the model would otherwise change every interval your application produces.

Editorial conclusion

Adopt FSRS when you are building a flashcard or learning product and want a memory model with published mechanics rather than a fixed interval heuristic, since the repository explains the three variables and the memory laws behind the scheduler and points at maintained libraries for most languages. Do not adopt it expecting a turnkey package, because this repository holds only README.md, README_CN.md and the licence, with the implementations living in separate ts-fsrs, py-fsrs, go-fsrs and other projects. Before you start, read The Algorithm page for the formula itself, decide whether you need only a scheduler or also the optimizer that fits parameters to your own review history, and check that your review log exports the fields the optimizer expects.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. open-spaced-repetition/free-spaced-repetition-scheduler on GitHub
4. Project website
5. README