8.1 KiB
Spaced repetition: flashcards in notes, SM-2 scheduler, review tab (agy gap 3, roadmap 31; supersedes inventory row 23)
Part of specs/plugins-parity/. One new pure crate notescraft-srs (L0, no third-party dependency), an engine group srs.*, a review tab. Obsidian-compatible card syntax so existing vaults work.
Research (2026-10-21; agy claims checked)
- Obsidian Spaced Repetition (st3v3nmw): single-line, multi-line, reversed and cloze cards, images/audio/video/LaTeX; the community listing shows about 498k downloads, 74 releases, MIT. https://community.obsidian.md/plugins/obsidian-spaced-repetition . Our roadmap row 23 says 0.62M; the listing figure is lower: use "about 0.5M". agy wrote "400k+ DL": consistent.
- Logseq has native flashcards (
#card), SiYuan and RemNote have spaced repetition built in (agy; Logseq doc link https://docs.logseq.com/#/page/flashcards not fetched). Anki is the reference tool. These are agy claims, not re-verified. - Algorithms: SM-2 (public SuperMemo 2 algorithm, https://super-memory.com/english/ol/sm2.htm , not fetched) is about 40 lines of arithmetic. FSRS is newer and more accurate but needs trained weights and the
fsrs-rscrate (https://github.com/open-spaced-repetition/fsrs-rs , not fetched; license not checked). agy proposedfsrs-rsand.notescraft/srs.sqlite: DROPPED for v1 because a new dependency needs owner approval (Q1) andrusqliteis approved only for sync; SM-2 plus a JSON file covers a personal vault (agy said effort S; with UI it is L, see roadmap). - Demand: the plugin's size (above) and the "export to Anki" workaround.
Problem
People capture knowledge in notes and forget it. The only in-vault path is a JS plugin; NotesCraft has no such feature.
Goal
Notes (selected by tag #flashcards, or a folder setting) contain cards in Markdown. A "Flashcards: Review" tab shows due cards one at a time; the user grades Again/Hard/Good/Easy; the scheduler computes the next due day; state lives in .notescraft/srs.json, never in the note (notes stay clean and portable).
Card syntax (Obsidian SR compatible)
- Basic, one line:
Question::Answer. Reversed, one line:Question:::Answer(two cards). - Multi-line: lines of the question, a line with only
?, lines of the answer, ended by a blank line (reversed with??). - Cloze:
==hidden==and{{c1::hidden}}inside a paragraph; one card per cloze, other clozes of the paragraph shown. - Ignored inside fenced code, inline code, front matter, HTML comments;
<!--SR:...-->comments from the Obsidian plugin are ignored (no import in v1: Feature ideas 3). - Deck = the tag path after the flashcard tag (
#flashcards/biology) else the note's folder.
Non-goals (v1)
FSRS (Q1); images/audio occlusion cards; editing cards in the review tab; sync conflict handling beyond atomic writes (single JSON, last write wins, Q3); statistics charts (Feature ideas); leech handling.
Design decisions
D1 Crate crates/srs (pure, no IO)
pub enum Kind { Basic, Reversed, Cloze }
pub struct Card { pub key: String, pub kind: Kind, pub front: String, pub back: String, pub deck: String, pub line: usize }
pub struct ScanOptions<'a> { pub tag: &'a str /* "flashcards" */, pub max_cards_per_note: usize /* 2000 */ }
pub fn extract_cards(note_text: &str, folder: &str, opts: &ScanOptions<'_>) -> Vec<Card>; // empty unless the note has the tag (front matter `tags`, or an inline #tag)
pub struct State { pub ease_x1000: u16, pub interval_days: u32, pub reps: u32, pub lapses: u32, pub due_day: u32 }
pub enum Grade { Again, Hard, Good, Easy }
pub fn review(state: State, grade: Grade, today: u32) -> State; // SM-2, days since 1970-01-01 passed by the caller; no clock
pub fn new_state(today: u32) -> State;
pub struct Store { ... } // Store::parse/to_json for { "version":1, "cards": { key: { "s": State, "last": day } } }, max 100 000 cards
key = hex of a 64-bit FNV-1a over (kind, normalised front, normalised back, cloze index), so moving a card between notes or lines keeps its history; two identical cards in one vault collapse into one. SM-2 constants as named consts: ease start 2.5 (2500), min 1.3 (1300), Again -> reps 0, lapses+1, interval 0 (due today, re-shown at the end of the session), ease -0.2; Hard: interval x1.2, ease -0.15; Good: 1, 6, then interval x ease; Easy: x ease x1.3, ease +0.15; interval capped at 36 500 days; all arithmetic checked_/saturating_.
D2 Engine (crates/engine/src/srs/{mod,scan,store,commands}.rs)
| id | params | result | writes |
|---|---|---|---|
srs.scan |
none | {cards, new, due, decks:[{name,total,due,new}]} (reads tagged notes through the index, one pass; cached per index generation) |
no |
srs.due |
{deck?, limit?} (default 50, max 500) |
{cards:[{key,kind,front,back,path,line,deck}], remaining}; due first (oldest due), then new up to new_per_day |
no |
srs.answer |
{key, grade} (again|hard|good|easy) |
{state, due_in_days} |
yes (write_private) |
srs.stats |
none | {due, new, reviewed_today, total} |
no |
srs.prune |
none | {removed} cards in the store that no note has |
yes |
Settings [srs]: tag (flashcards), new_per_day (20, 0..=500), enabled (true). Add due, scan, stats to READ and answer, prune to WRITE in ai/assistant_gate.rs; add to CORE_IDS. The engine owns the clock (today); tests inject it. |
D3 UI
A tab srs: + deck (like tabs::VERSIONS_PREFIX, copy how versions opens: widgets/tabs/kind.rs, shell/app/window/views.rs), view in views/srs_view/{mod,card,summary}.rs. Front shown; Space/click reveals the back (rendered with the note inline renderer so bold, math and links work: reuse views/note_view/inlines.rs); keys 1-4 grade; Again cards reappear at the end of the queue; "Open note" jumps to path:line. Palette entry "Flashcards: Review" and a status-bar due count chip (hidden when 0). Deck picker, session summary (count, time). Strings [ui.srs] at END of en.toml.
D4 Safety
Note text is hostile (patterns, huge lines): extraction is linear, per-note cap, front/back clipped at 4 KiB, no regex backtracking (hand scan), no panics. The store file is bounded (100 000 cards); a corrupt store is NOT overwritten (error toast, review disabled until fixed or moved).
Acceptance criteria
Q::Agives one Basic card;Q:::Atwo; a multi-line card with?parses; a paragraph with two==x==gives two cloze cards each hiding one.- Cards in fenced code, front matter and comments are ignored; notes without the tag give none.
- Moving a card to another note keeps its schedule (same key); editing the text makes a new card.
- SM-2 table tests: new + Good -> 1 day; Good again -> 6; Good again -> 6 x 2.5 = 15; Again resets and lowers ease; ease never < 1.3; interval cap.
srs.answerwrites only.notescraft/srs.json(atomic) and the note files are untouched; two runs ofsrs.scanon an unchanged vault are identical.- Scan of 5 000 notes with 20 000 cards < 300 ms warm (ignored perf test).
- Review tab: grade with keys 1-4 sends exactly one
srs.answereach; the queue ends with the summary.
Open questions
- Q1: FSRS: add
fsrs-rs(needs owner approval, check license) or keep SM-2 only? Proposal: SM-2 in v1; theStatestruct keeps room (version field) for FSRS parameters later. - Q2: tag-selected notes only (proposed) or also
#cardinline tags (Logseq style)? - Q3: should
srs.jsonsync across devices (it is small, last write wins loses reviews done on two devices)? Proposal: sync it, merge per card by newestlast(task in a later spec). - Q4: store as JSON (proposed) or SQLite (approved only for sync)?
Feature ideas (researched, ranked)
- Import
<!--SR:!2024-05-01,12,250-->schedules from the Obsidian plugin so existing users keep progress (high value for migration). - FSRS option after Q1 (better retention per review than SM-2; Anki ships it).
- Review from a single note/selection ("Review this note's cards"), and a Bases view of cards.
- Heatmap of reviews per day on the calendar (roadmap 20 Heatmap Calendar); 5. Leech detection (lapses >= 8) with a tag suggestion; 6. Image occlusion; 7. MCP/AI: generate cards from a note via the assistant (WRITE command with confirmation).