A Tiny Typescript Implementation of FSRS From Scratch

[RickCarlino]

UPDATE: It's an NPM Package Now

Please see: https://www.npmjs.com/package/femto-fsrs

---

I wrote a stripped-down Typescript version of fsrs based on the paper.

This is fsrs based on what I understood in the docs, minus fancy features seen in full-featured implementations like ts-fsrs (there is no logging or revert capabilities like you will find in other implementations)

Test Results

let w = [
  0.4, 0.9, 2.3, 10.9, 4.93, 0.94, 0.86, 0.01, 1.49, 0.14, 0.94, 2.18, 0.05,
  0.34, 1.26, 0.29, 2.61,
];

┌──────┬────────┬───────────────────┬────────────────────┬──────────┐
│ Step │ Rating │ Difficulty        │ Stability          │ Interval │
├──────┼────────┼───────────────────┼────────────────────┼──────────┤
│ 1    │ 3      │ 4.93              │ 2.3                │ '2d'     │
│ 2    │ 3      │ 4.93              │ 7.089940332860096  │ '7d'     │
│ 3    │ 3      │ 4.93              │ 21.233854404199842 │ '21d'    │
│ 4    │ 3      │ 4.93              │ 57.61873858531124  │ '57d'    │
│ 5    │ 1      │ 6.632799999999999 │ 6.721614337784945  │ '6d'     │
│ 6    │ 3      │ 6.615771999999998 │ 15.631866108573828 │ '15d'    │
│ 7    │ 3      │ 6.598914279999998 │ 35.36163287465533  │ '35d'    │
└──────┴────────┴───────────────────┴────────────────────┴──────────┘

Test Method

type Card = { D: Difficulty; S: Stability; I: IntervalDays };

/** For simplicity, a deck will have the same requested retention rate. */
export function createDeck(requestedRetentionRate: number) {
  return {
    newCard(grade: Grade): Card {
      const D = initialDifficulty(grade);
      const S = initialStability(grade);
      const I = nextInterval(requestedRetentionRate, S);
      return { D, S, I };
    },
    gradeCard(card: Card, daysSinceReview: number, grade: Grade): Card {
      // Calculate current retrievability based on days since last review
      const currentRetrievability = retrievability(daysSinceReview, card.S);
      const D = nextDifficulty(card.D, grade);
      let S: number;
      if (grade === Grade.AGAIN) {
        S = nextStabilityAfterForgetting(D, card.S, currentRetrievability);
      } else {
        S = nextStabilityAfterRecall(D, card.S, currentRetrievability, grade);
      }
      var I = nextInterval(requestedRetentionRate, S);
      return { D, S, I };
    },
  };
}

const { newCard, gradeCard } = createDeck(0.9);
const ratings = [
  Grade.GOOD,
  Grade.GOOD,
  Grade.GOOD,
  Grade.GOOD,
  Grade.AGAIN,
  Grade.GOOD,
  Grade.GOOD,
];
let results: {}[] = [];
let card: Card = newCard(ratings[0]);

ratings.forEach((rating, index) => {
  if (index > 0) {
    let daysSinceReview = card.I;
    card = gradeCard(card, daysSinceReview, rating);
  }
  results.push({
    Step: index + 1,
    Rating: rating,
    Difficulty: card.D,
    Stability: card.S,
    Interval: card.I + "d",
  });
});

console.table(results);

Implementation

enum Grade {
  AGAIN = 1,
  HARD = 2,
  GOOD = 3,
  EASY = 4,
}
type Difficulty = number; // how difficult it is to increase memory stability after a review. 1..10
type Stability = number; // Number of days until 90% recall probability
type Retrievability = number; // probability of recall
type IntervalDays = number; // Days until ideal next review
type DaysSinceReview = number;

// Constants for FSRS-4.5
const DECAY = -0.5;
const FACTOR = 19 / 81;

/**
 * Calculates the retrievability after t days since the last review.
 * @param {number} t - The number of days since the last review.
 * @param {number} S - Stability (interval when R=90%).
 * @returns {number} - Retrievability (probability of recall).
 */
function retrievability(t: DaysSinceReview, S: Stability): Retrievability {
  // Should return 0.9 when t = S
  return Math.pow(1 + FACTOR * (t / S), DECAY);
}

/**
 * Calculates the next interval based on requested retention.
 * @param {number} r - The requested retention rate.
 * @param {number} S - Current stability.
 * @returns {number} - The next interval in days.
 */
function nextInterval(R: Retrievability, S: Stability): IntervalDays {
  // I(r, S) = S when R = 0.9
  return (S / FACTOR) * (Math.pow(R, 1 / DECAY) - 1);
}

/**
 * Calculates initial stability after the first rating.
 * @param {number} G - Grade (1: again, 2: hard, 3: good, 4: easy).
 * @returns {number} - Initial stability.
 */
function initialStability(G: Grade): Stability {
  return w[G - 1];
}

/**
 * Calculates initial difficulty after the first rating.
 * @param {number} G - Grade (1: again, 2: hard, 3: good, 4: easy).
 * @returns {number} - Initial difficulty.
 */
function initialDifficulty(G: Grade): Difficulty {
  const val = w[4] + (G - 3) * w[5];
  return Math.max(1, Math.min(10, val));
}

/**
 * Calculates new difficulty after review.
 * @param {number} D - Current difficulty.
 * @param {number} G - Grade (1: again, 2: hard, 3: good, 4: easy).
 * @returns {number} - New difficulty.
 */
function nextDifficulty(D: Difficulty, G: Grade): Difficulty {
  const val = w[7] * initialDifficulty(3) + (1 - w[7]) * (D - w[6] * (G - 3));
  return Math.max(1, Math.min(10, val));
}

/**
 * The stability after recall. Thanks, ts-fsrs.
 * @param {number} d - Difficulty.
 * @param {number} s - Current stability.
 * @param {number} r - Retrievability.
 * @param {number} g - Grade (1: again, 2: hard, 3: good, 4: easy).
 * @returns {number} - New stability after recall.
 */
function nextStabilityAfterRecall(
  d: Difficulty,
  s: Stability,
  r: Retrievability,
  g: Grade
): Stability {
  const hard_penalty = Grade.HARD === g ? w[15] : 1;
  const easy_bound = Grade.EASY === g ? w[16] : 1;
  return (
    s *
    (1 +
      Math.exp(w[8]) *
        (11 - d) *
        Math.pow(s, -w[9]) *
        (Math.exp((1 - r) * w[10]) - 1) *
        hard_penalty *
        easy_bound)
  );
}
/**
 * Calculates stability after forgetting.
 * @param {number} d - Difficulty.
 * @param {number} s - Current stability.
 * @param {number} r - Retrievability.
 * @returns {number} - New stability after forgetting.
 */
function nextStabilityAfterForgetting(
  d: Difficulty,
  s: Stability,
  r: Retrievability
): Stability {
  return (
    w[11] *
    Math.pow(d, -w[12]) *
    (Math.pow(s + 1, w[13]) - 1) *
    Math.exp((1 - r) * w[14])
  );
}

[RickCarlino]

OK, I was able to fix my mistakes. Re-opening for discussion.

[L-M-Sherlock]

https://huggingface.co/spaces/open-spaced-repetition/fsrs4anki_previewer

You can compare your results with the above previewer.

[RickCarlino]

@L-M-Sherlock Thank you, after cross-referencing the simulator, I was able to fix a few mistakes and I believe I now have a working implementation that matches your results.

[RickCarlino]

UPDATE: I have published the module on NPM as femto-fsrs if others find it useful.