Java-FSRS

🧠🔄 Build your own Spaced Repetition System in Java 🧠🔄

Java-FSRS is a Java library that allows developers to easily create their own spaced repetition system using the Free Spaced Repetition Scheduler algorithm.

Table of Contents

• Installation
• Quickstart
• Versioning
• Other FSRS implementations
• Contribute

Installation

You can install the fsrs Java library from Maven Central.

Quickstart

import io.github.openspacedrepetition.Scheduler;
import io.github.openspacedrepetition.Card;
import io.github.openspacedrepetition.Rating;
import io.github.openspacedrepetition.CardAndReviewLog;
import io.github.openspacedrepetition.ReviewLog;

import java.time.Instant;
import java.time.Duration;

public class SRS {

    public static void main(String[] args) {

        Scheduler scheduler = Scheduler.builder().build();

        // note: all new cards are 'due' immediately upon creation
        Card card = Card.builder().build();

        // Choose a rating and review the card with the scheduler
        /*
        * Rating.AGAIN (==1) forgot the card
        * Rating.HARD (==2) remembered the card with serious difficulty
        * Rating.GOOD (==3) remembered the card after a hesitation
        * Rating.EASY (==4) remembered the card easily
        */
        Rating rating = Rating.GOOD;

        CardAndReviewLog result = scheduler.reviewCard(card, rating);
        card = result.card();
        ReviewLog reviewLog = result.reviewLog();

        System.out.println(
                "Card rated " + reviewLog.rating() + " at " + reviewLog.reviewDatetime());
        // > Card rated GOOD at 2025-07-10T04:16:19.637219Z

        // when the card is due next for review
        Instant due = card.getDue();

        // how much time between now and when the card is due
        Duration timeDelta = Duration.between(Instant.now(), due);

        System.out.println("Card due on: " + due);
        System.out.println("Card due in " + timeDelta.toSeconds() + " seconds");
        // > Card due on: 2025-07-10T04:26:19.637219Z
        // > Card due in 599 seconds

    }

}

Versioning

This Java library is currently unstable and adheres to the following versioning scheme:

• MINOR version number will increase when a backward-incompatible change is introduced
• PATCH version number will increase when a bug is fixed, a new feature is added or when anything else warrants a new release

Once this package is considered stable, the MAJOR version number will be bumped to 1.0.0 and will then follow semver.

Other FSRS implementations

You can find various other FSRS implementations and projects here.

Contribute

If you encounter issues with java-fsrs or would like to contribute code, please see CONTRIBUTING.