# FSRS for Obsidian

- [🇷🇺](https://github.com/Evgene-Kopylov/fsrs_plugin/blob/main/README.ru.md)
- [🇺🇸](README.md) <
- [🇨🇳](https://github.com/Evgene-Kopylov/fsrs_plugin/blob/main/README.zh.md)

**Free Spaced Repetition Scheduler** — a modern spaced repetition algorithm for Obsidian.
The plugin turns your notes into FSRS-based flashcards for effective memorization.

[![Obsidian](https://img.shields.io/badge/Obsidian-%23483699.svg?&logo=obsidian&logoColor=white)](https://obsidian.md) [![TypeScript](https://img.shields.io/badge/TypeScript-3178C6.svg?&logo=TypeScript&logoColor=white)](https://www.typescriptlang.org/) [![Rust](https://img.shields.io/badge/Rust-000000.svg?&logo=Rust&logoColor=white)](https://www.rust-lang.org/) [![License](https://img.shields.io/badge/License-LGPLv3-blue.svg?)](LICENSE) [![pipeline status](https://gitlab.com/Evgene-Kopylov/FSRS-plugin/badges/main/pipeline.svg)](https://gitlab.com/Evgene-Kopylov/FSRS-plugin) [![DeepSeek](https://img.shields.io/badge/AI-DeepSeek-536DFE.svg)](https://deepseek.com)

## 📋 Table of Contents

[toc]

## 🚀 Features

- **📊 FSRS-6 Algorithm** — more efficient than SM-2
- **🎯 Retention Control** — 70–97% target level
- **⚡ High Performance** — Rust/WASM for fast computations
- **🔄 Dynamic Interface** — auto-updating lists
- **📱 Mobile Support** — iOS(?), Android(✓)
- **🎨 Flexible Configuration** — filtering, sorting, customization
- **📈 Statistics** — track your progress

## 📦 Installation

Install from the community catalog (**Settings** → **Community plugins** → **Browse** → **FSRS**).

### Beta versions via BRAT

1. Install [BRAT](https://github.com/TfTHacker/obsidian42-brat)
2. Add the repository: `https://github.com/Evgene-Kopylov/fsrs_plugin`

### Installation Requirements

- Obsidian v1.12.7 or higher
- WebAssembly support (enabled by default)

### Platform Support

| Platform | Status |
| :--- | :--- |
| Linux (x86_64) | ✅ |
| macOS | ❔ (not tested) |
| Windows (x86_64) | ✅ |
| Android | ✅ |
| iOS | ❔ (not tested) |

## 🐌 Quick Start

1. **Create a card** – open a note → run the command `Add FSRS fields to file header` (Ctrl/Cmd+P).
2. **Add a review button** – use the command `FSRS: Insert review button` (Ctrl/Cmd+P), or insert a ` ```fsrs-review-button``` ` block manually, or enable auto-adding in settings.
3. **Insert a table** – use the command `Insert default fsrs-table` (Ctrl/Cmd+P), or create a ` ```fsrs-table ...``` ` block manually.
4. **Start reviewing** – open the table, hover over a file name, and click a rating.

A detailed step-by-step guide with screenshots: [**Usage Guide**](docs/intended_use.en.md)

## 📖 Usage

### The `fsrs-table` Block (SQL-like Syntax)

The `fsrs-table` block uses SQL-like syntax to customize how cards are displayed.

**Basic syntax:**

````markdown
```fsrs-table
SELECT field1, field2 as "Header", field3
ORDER BY field4 DESC
LIMIT 30
```
````

**Available columns:**

| Field | Description | Notes |
| ------- | ------------- | ------- |
| `file` | card file name | clickable link |
| `reps` | number of repetitions completed | |
| `stability` | card stability (S) | FSRS parameter |
| `difficulty` | card difficulty (D) | value from 0 to 10 |
| `retrievability` | retrievability (R) | probability of correct recall |
| `due` | next review date and time | |
| `state` | card state | New, Learning, Review, Relearning |
| `elapsed` | days since last review | |
| `scheduled` | days until next review | |

**Block parameters:**

- `SELECT` — choose fields to display (required)
- `ORDER BY` — sort by a specified field (`ASC` ascending, `DESC` descending)
- `LIMIT` — limit the number of rows (`0` uses the value from plugin settings)

**Limitations:**

- No subqueries, JOIN, aggregations (`COUNT`, `SUM`, `AVG`), `GROUP BY`, `UNION`
- `WHERE` supports only simple conditions: `=`, `!=`, `<`, `>`, `<=`, `>=`, `~` (regex), `!~`, `AND`, `OR`
- The only function available is `date_format(field, 'format')`
- Unknown field in `SELECT`, `WHERE`, `ORDER BY` — error with field name indicated
- Column order in `SELECT` is preserved in the displayed table

**More:** [How the SQL parser works](https://github.com/Evgene-Kopylov/fsrs_plugin/blob/main/docs/sql-parser.ru.md)

**Examples:**

1. Urgent cards (by due date):

````markdown
```fsrs-table
SELECT file as " ", r as "R",
       s as "S", d as "D",
       due as "Next review"
LIMIT 20
```
````

1. All cards sorted by date:

````markdown
```fsrs-table
SELECT *
ORDER BY due ASC
LIMIT 100
```
````

### FSRS Parameters and Configuration

The plugin uses [rs-fsrs](https://crates.io/crates/rs-fsrs) — the official Rust FSRS implementation by the algorithm authors (L-M-Sherlock). Rationale:

- **rs-fsrs** — maintained by the FSRS team, synced with the Python reference implementation, actively updated.
- **fsrs-rs** — third-party implementation, long outdated, incompatible with current FSRS versions.

**User-configurable** (Settings → FSRS → Algorithm Parameters):

| Parameter | Default | Description |
| --- | --- | --- |
| `request_retention` | 0.9 (90%) | Target retention rate |
| `maximum_interval` | 36500 days | Maximum interval between reviews |


**Not yet configurable:**

- **`w` weights (17 parameters)** — the core of FSRS, determining the forgetting curve. The plugin uses defaults optimized by FSRS authors on the Anki corpus (millions of reviews).
- **Parameter optimization on user statistics** — not supported. Users cannot retrain weights on their responses. Planned for future versions.

### Review Button in Notes `fsrs-review-button`

````markdown
```fsrs-review-button
```
````

### FSRS Card Format

FSRS cards are stored in the note's frontmatter under the `reviews` field:

```yaml
---
reviews:
  - date: "2026-01-15T10:30:00Z"
    rating: 2
  - date: "2026-01-20T14:15:00Z"
    rating: 3
---
```

**Fields of each review session:**

- **`date`** — date/time in ISO 8601
- **`rating`** — `0` (Again), `1` (Hard), `2` (Good), or `3` (Easy)

**Notes:**

- `reviews` can be `[]` for new cards
- Each review adds a session to the array
- FSRS calculates the next review date based on history
- The plugin adds these fields automatically

## 🎮 Plugin Commands

### Via Command Palette (Ctrl/Cmd+P)

- **FSRS: Add FSRS fields to file header**
- **FSRS: Find cards to review**
- **FSRS: Review current card**
- **FSRS: Remove last card review**
- **FSRS: Show review history**
- **FSRS: Insert review button**
- **FSRS: Insert default fsrs-table**
- **FSRS: Show fsrs-table syntax help**

### Via the Status Bar

- Button `🔄FSRS:` at the bottom of the Obsidian window

## ⚙️ Settings

### FSRS Algorithm Parameters

| Setting | Description | Default |
| --------- | ------------- | --------- |
| **Request Retention** | Target retention level | 0.9 (90%) |
| **Maximum Interval** | Max interval (days) | 36500 (~100 years) |

### Default Settings for New Cards

| Setting | Description | Default |
| --------- | ------------- | --------- |
| **Initial Stability** | Initial stability | 0.0 |
| **Initial Difficulty** | Initial difficulty for new cards | 0.0 |

### Display Settings

| Setting | Description | Default |
| --------- | ------------- | --------- |
| **Auto Add Review Button** | Automatically add review button | Disabled |

### Filter Settings

| Setting | Description | Example |
| --------- | ------------- | --------- |
| **Ignore Patterns** | Ignore patterns | `.obsidian/`, `templates/` |

## 🧠 The FSRS Algorithm

**FSRS** is a modern spaced repetition algorithm by Jarrett Ye.
Implements [FSRS-6](https://github.com/open-spaced-repetition/fsrs-rs) (v6.0.0, rev af8448e). Compared to SM-2:

- Learns memory patterns via machine learning
- Adapts to your memory speed
- Requires 20–30% fewer reviews for the same retention level
- Handles breaks (weeks/months) much better

### Key Concepts

- **Retrievability (R)** — probability of successful recall
- **Stability (S)** — time it takes for R to decay from 100% to 90%
- **Difficulty (D)** — information difficulty (affects how stability grows)

The algorithm uses 21 parameters optimized on millions of reviews.

**Read more:** [ABC of FSRS](docs/ABC%20of%20FSRS.md)

## 🛠️ Development

**Development happens on GitLab:** [gitlab.com/Evgene-Kopylov/FSRS-plugin](https://gitlab.com/Evgene-Kopylov/FSRS-plugin).
The GitHub repository is a mirror.

### Tech Stack

- **Frontend:** TypeScript, Obsidian API
- **Algorithm:** Rust (compiled to WebAssembly)
- **Build:** esbuild, wasm-pack
- **Testing:** Rust (cargo test) + TypeScript (vitest)

### Rust and TypeScript Responsibility Split

**Principle:** Rust is the computation core, TypeScript is a thin wrapper for the Obsidian API.

### Release Pipeline

The project uses GitLab CI/CD for automated build, test, and release:

### Building from Source

#### Build Requirements

- **Node.js** 18+
- **npm**
- **Rust** (with `wasm32-unknown-unknown` target)
- **wasm-pack**
- **binaryen** (wasm-opt, installed via `npm install`)

```bash
git clone https://gitlab.com/Evgene-Kopylov/FSRS-plugin.git
cd FSRS-plugin
npm install
npm run build

# Install plugin in vault
ln -s "$PWD" /path/to/vault/.obsidian/plugins/fsrs

# Development (optional)
npm run dev
```

### WASM Integration

The plugin uses Rust/WASM for FSRS computations:

- **WASM binary** is embedded into the plugin via base64
- **No network requests** — everything runs locally
- **High performance** — native-level computation

**Read more:** [WASM Integration](docs/WASM-INTEGRATION.md)

## 📄 License

This plugin is licensed under **LGPLv3**.

**LGPL** permits:

- Use in proprietary software
- Requires modified library source code to be open

### Main Rights

- ✅ Use (free, including commercial use)
- ✅ Study (access to source code)
- ✅ Distribute
- ✅ Improve

### Requirements

- Library modifications must remain under LGPLv3
- Dynamic linking is allowed without disclosing application code
- Maintain copyright notices
- Provide source code when distributing modifications

### For Obsidian Users

- Free to use for personal/commercial purposes
- Derivative plugins must be under LGPLv3
- Modifications to Rust WASM components must be under LGPLv3

Full text: [LICENSE](LICENSE)

## 🙏 Acknowledgements

- **Jarrett Ye (叶峻峣)** — author of the FSRS algorithm
- **Obsidian Community** — inspiration and support
- **Rust Community** — WASM tooling
- **DeepSeek** — a powerful and convenient development tool (code, refactoring, localization)
- **All contributors** — improvements and bug reports

## 📚 Additional Resources

- [Official FSRS Documentation](https://github.com/open-spaced-repetition/fsrs)
- [Obsidian Forum Discussion](https://forum.obsidian.md/)
- [Issues & Feature Requests](https://gitlab.com/Evgene-Kopylov/FSRS-plugin/-/work_items)
- [FSRS Table Usage Guide](docs/intended_use.en.md)