Files
Marcos Paulo b32650767c
ci / ci (macos-latest) (push) Has been cancelled
ci / ci (ubuntu-latest) (push) Has been cancelled
ci / ci (windows-latest) (push) Has been cancelled
docs: specs and briefs for smart folders, version diff, media timestamps, clean paste, link cards, spaced repetition
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-21 12:18:00 -03:00

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-rs crate (https://github.com/open-spaced-repetition/fsrs-rs , not fetched; license not checked). agy proposed fsrs-rs and .notescraft/srs.sqlite: DROPPED for v1 because a new dependency needs owner approval (Q1) and rusqlite is 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

  1. Q::A gives one Basic card; Q:::A two; a multi-line card with ? parses; a paragraph with two ==x== gives two cloze cards each hiding one.
  2. Cards in fenced code, front matter and comments are ignored; notes without the tag give none.
  3. Moving a card to another note keeps its schedule (same key); editing the text makes a new card.
  4. 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.
  5. srs.answer writes only .notescraft/srs.json (atomic) and the note files are untouched; two runs of srs.scan on an unchanged vault are identical.
  6. Scan of 5 000 notes with 20 000 cards < 300 ms warm (ignored perf test).
  7. Review tab: grade with keys 1-4 sends exactly one srs.answer each; 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; the State struct keeps room (version field) for FSRS parameters later.
  • Q2: tag-selected notes only (proposed) or also #card inline tags (Logseq style)?
  • Q3: should srs.json sync across devices (it is small, last write wins loses reviews done on two devices)? Proposal: sync it, merge per card by newest last (task in a later spec).
  • Q4: store as JSON (proposed) or SQLite (approved only for sync)?

Feature ideas (researched, ranked)

  1. Import <!--SR:!2024-05-01,12,250--> schedules from the Obsidian plugin so existing users keep progress (high value for migration).
  2. FSRS option after Q1 (better retention per review than SM-2; Anki ships it).
  3. Review from a single note/selection ("Review this note's cards"), and a Bases view of cards.
  4. 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).