quanta-fsrs

FSRS v4.5/5 Spaced Repetition Scheduler — zero dependencies, TypeScript-native, edge-ready.
Used in production at quanta-study.de — MINT-Lernplattform für Studenten.

---

What is FSRS?

The Free Spaced Repetition Scheduler (FSRS) is a modern, open-weights algorithm for scheduling flashcard reviews. It was developed by Jarrett Ye (et al.) and published at KDD 2022:

Ye, J., Su, T., Cao, J. (2022). A Stochastic Shortest Path Algorithm for Optimizing Spaced Repetition Scheduling. KDD '22. doi.org/10.1145/3534678.3539081

Key benchmark: FSRS achieves a log-loss of 0.35 on 20,483,712 real Anki reviews, vs. 0.45 for SM-2 — a 22% improvement in predictive accuracy.

How FSRS Works

FSRS tracks three parameters per card per learner:

Symbol	Name	Definition
S	Stability	Days until Retrievability drops to 90%
D	Difficulty	Intrinsic item difficulty, range [1, 10]
R(t)	Retrievability	Probability of recall at time t: R = 0.9^(t/S)

The algorithm updates S and D after each review using grade-dependent equations, then schedules the next review at t = S days (the exact point where R = 90%).

---

Installation

npm install quanta-fsrs
# or
yarn add quanta-fsrs
# or
pnpm add quanta-fsrs

Zero dependencies. Works in Node.js >= 18, browsers, Deno, Bun, Cloudflare Workers, and Vercel Edge.

---

Quick Start

import { createInitialState, updateFSRS, calculateRetrievability, formatStability } from 'quanta-fsrs';

// 1. Create a new card state
let state = createInitialState();

// 2. After the first review — grade 3 (Good)
state = updateFSRS(state, 3);
console.log(state.stability);    // ~3.33 days
console.log(state.nextReview);   // ISO 8601, ~3 days from now
console.log(formatStability(state.stability)); // "3.3d"

// 3. After reviewing successfully again
state = updateFSRS(state, 4); // Easy
console.log(formatStability(state.stability)); // "35.8d" — interval grew

// 4. Check current recall probability
const r = calculateRetrievability(state.stability, state.lastReview);
console.log(`Recall probability: ${(r * 100).toFixed(1)}%`); // e.g., "98.7%"

---

API Reference

createInitialState(): FSRSState

Creates a blank state for a new card.

const state = createInitialState();
// { stability: 0, difficulty: 5, lastReview: null, nextReview: null }

---

updateFSRS(state, grade, now?, weights?): FSRSState

Processes a review and returns the updated state with the next scheduled date.

const newState = updateFSRS(state, grade, now?, weights?);

Parameter	Type	Default	Description
state	FSRSState	—	Current card state
grade	1|2|3|4	—	Review grade (Again/Hard/Good/Easy)
now	Date	new Date()	Review timestamp
weights	number[]	DEFAULT_MINT_WEIGHTS	Custom FSRS weight vector

Grade mapping:

Grade	Label	Quanta alias	Meaning
1	Again	'learning'	Complete blackout
2	Hard	'unsure'	Recalled with great difficulty
3	Good	'known'	Recalled correctly
4	Easy	—	Instant, perfect recall

---

calculateRetrievability(stability, lastReview, now?, targetRetention?): number

Returns the current probability of recall (0-1).

const r = calculateRetrievability(14, '2024-01-01T00:00:00Z');
// R = 0.9^(daysSince / 14) -> e.g., 0.874 after 2 days

---

isDue(state, now?): boolean

Returns true if the card is scheduled for review.

if (isDue(state)) { /* show card */ }

---

daysUntilReview(state, now?): number

Returns days remaining (positive) or overdue days (negative).

---

sortByUrgency(states, now?): FSRSState[]

Sorts cards by ascending Retrievability — most forgotten first.

const queue = sortByUrgency(allCards);
// queue[0] has the lowest recall probability -> review first

---

filterDue(states, now?): FSRSState[]

Returns only cards currently due for review.

---

Formatting Utilities

formatStability(3.33)  // "3.3d"
formatStability(45)    // "1.5mo"
formatStability(400)   // "1.1y"

formatRetrievability(0.874) // "87.4%"

---

MINT-Optimized Weights

The DEFAULT_MINT_WEIGHTS are calibrated for high-performance academic learning in MINT disciplines (Mathematics, Informatics, Natural Sciences, Technology). They slightly favor longer intervals compared to stock FSRS weights, reflecting the abstract, interconnected nature of MINT content.

import { DEFAULT_MINT_WEIGHTS, updateFSRS } from 'quanta-fsrs';

// Use default MINT weights (pre-selected)
const state = updateFSRS(current, 3);

// Or supply your own optimized weights
const myWeights = [/* 17 values */];
const state2 = updateFSRS(current, 3, new Date(), myWeights);

---

Full Example: Study Session Simulator

import {
  createInitialState, updateFSRS, calculateRetrievability,
  sortByUrgency, filterDue, formatStability, formatRetrievability
} from 'quanta-fsrs';

// Simulate a deck of 5 cards over 30 days
const deck = Array.from({ length: 5 }, (_, i) => ({
  id: `card-${i}`,
  ...createInitialState()
}));

// Day 1: Review all cards
let now = new Date('2024-01-01');
const graded = deck.map(card => ({
  ...card,
  ...updateFSRS(card, [3,4,2,3,4][card.id.slice(-1) as any] || 3, now)
}));

// Day 3: Check what's due
const day3 = new Date('2024-01-04');
const due = filterDue(graded, day3);
console.log(`${due.length} cards due on day 3`);

// Show urgency queue
const queue = sortByUrgency(graded, day3);
queue.forEach(c => {
  const r = calculateRetrievability(c.stability, c.lastReview, day3);
  console.log(`S=${formatStability(c.stability)}, R=${formatRetrievability(r)}`);
});

---

TypeScript Types

interface FSRSState {
  stability: number;      // days until R = 90%
  difficulty: number;     // [1, 10]
  lastReview: string | null;  // ISO 8601
  nextReview: string | null;  // ISO 8601
}

type FSRSGrade = 1 | 2 | 3 | 4;
type QuantaGrade = FSRSGrade | 'known' | 'unsure' | 'learning';

---

Scientific Background

FSRS is built on three decades of cognitive science research:

• Ebbinghaus (1885): Exponential forgetting curve — memory decays predictably without rehearsal.
• Spacing Effect (Cepeda et al., 2006): Distributed practice dramatically outperforms massed practice.
• Testing Effect (Roediger & Karpicke, 2006): Active retrieval (~30% stronger than re-reading).
• Cognitive Load Theory (Sweller, 1988): Difficulty modulates encoding quality via schema automation.
• Karpicke & Roediger (2008): Active recall achieves 81% long-term retention vs. 27% for passive study (Science 319, doi:10.1126/science.1152408).

The FSRS power law R(t) = retention^(t/S) is the modern replacement for Ebbinghaus's pure exponential, providing dramatically better fit on real learner data.

---

Comparison: FSRS vs SM-2

Feature	FSRS v4.5	SM-2 (Classic Anki)
Log-loss (20M reviews)	0.35	0.45
Stability growth model	Power-law (grade-adaptive)	Linear multiplier
Difficulty tracking	Per-card, continuous	Per-card, integer
Failure recovery	Smooth decay	Hard reset
Open weights	Yes	No
TypeScript types	Yes	No
Zero dependencies	Yes	No

---

About Quanta

Quanta is an evidence-based MINT learning platform for students in Germany, Austria, and Switzerland (DACH region). Core technology:

• FSRS-6 (Free Spaced Repetition Scheduler v6) for optimal review scheduling
• Active Recall via Q&A flashcards (Karpicke & Roediger, Science 2008)
• AI Card Generation powered by Gemini 2.5 Flash (Google DeepMind 2025)
• Community Library with thousands of free, importable MINT flashcard decks
• Student Discount — Pro plan from 6.99 EUR/month for students and pupils

Visit quanta-study.de to start learning with FSRS.

---

Contributing

Pull requests are welcome. Please open an issue first for major changes.

git clone https://github.com/ammmcreativetech-dot/quanta-fsrs
cd quanta-fsrs
npm install
npm test

---

License

MIT — free for commercial and non-commercial use.

---

Built by the Quanta Team — MINT-Lernplattform fuer Studenten in Deutschland, Oesterreich und der Schweiz.