algernon-review

You run the interactive flashcard review session with FSRS-4.5 spaced repetition. You handle flashcards (binary reveal), dissertative cards (AI-graded), and argumentative cards (AI-graded). At the end, you check promotion eligibility and save the session.

Constants

ALGERNON_HOME="${ALGERNON_HOME:-$HOME/.openalgernon}"
DB="${ALGERNON_HOME}/data/study.db"

FSRS-4.5 Parameters

• DECAY = -0.5, FACTOR = 0.2346
• Stability (S) = days to reach 90% retention
• Grades: 1 = Again, 3 = Good

Step 1 — Fetch Due Cards

sqlite3 "$DB" \
  "SELECT c.id, c.type, c.front, c.back, c.tags, c.source_title, c.deck_id,
          cs.stability, cs.reps, cs.state
   FROM cards c
   JOIN card_state cs ON cs.card_id = c.id
   JOIN decks d ON d.id = c.deck_id
   JOIN materials m ON m.id = d.material_id
   WHERE cs.due_date <= date('now')
   [AND m.slug = 'SLUG']
   ORDER BY cs.due_date ASC
   LIMIT 50;"

(Include AND m.slug = 'SLUG' only if a specific slug was provided.)

If no cards due: "No cards due for review. Great job staying on top of it." and stop.

Display: "Starting review: N cards due."

Step 2 — Review Loop

Flashcards (type = 'flashcard')

1. Show front. AskUserQuestion options: ["Show answer"]
2. Show back. AskUserQuestion options: ["Again", "Good"]
3. Run FSRS update (see Step 3).

Dissertative and Argumentative Cards

1. Show front. AskUserQuestion options: ["Ready to answer"]
2. AskUserQuestion: "Type your answer:" (free text)
3. Evaluate the response against the reference answer (card back):
   • Dissertative: check accuracy of key points, completeness
   • Argumentative: check that both sides are represented, trade-offs identified
   • Output: brief feedback + suggested grade (1 or 3) + optional MISCONCEPTION note
4. Show evaluator feedback + reference answer. AskUserQuestion options: ["Again", "Good"] (Use the user's button choice, not the AI suggestion.)
5. Run FSRS update using the user's chosen grade.
6. If a MISCONCEPTION was detected, create a correction card:

   sqlite3 "$DB" \
     "INSERT INTO cards (deck_id, type, front, back, tags)
      VALUES (DECK_ID, 'flashcard',
              'CORRECTION: MISCONCEPTION_QUESTION',
              'CORRECT_EXPLANATION',
              '[\"[correction]\",\"[N1]\"]');
      INSERT INTO card_state (card_id, due_date)
      VALUES (last_insert_rowid(), date('now'));"
   

Step 3 — FSRS Scheduling

For each graded card, compute new values and update card_state.

Read current state:

sqlite3 "$DB" \
  "SELECT stability, difficulty, reps, lapses, state, last_review
   FROM card_state WHERE card_id = CARD_ID;"

Compute elapsed days (if last_review is not NULL):

sqlite3 "$DB" \
  "SELECT ROUND(julianday('now') - julianday('LAST_REVIEW'), 2) AS elapsed;"

State transitions:

For review+Good, compute retrievability first:

sqlite3 "$DB" \
  "SELECT EXP(LN(0.9) * ELAPSED / STABILITY) AS R;"

Update:

sqlite3 "$DB" \
  "UPDATE card_state SET
     stability   = NEW_S,
     difficulty  = NEW_D,
     due_date    = date('now', '+' || INTERVAL || ' days'),
     last_review = datetime('now'),
     reps        = reps + 1,
     lapses      = NEW_LAPSES,
     state       = 'NEW_STATE'
   WHERE card_id = CARD_ID;
   INSERT INTO reviews (card_id, grade, scheduled_days, elapsed_days)
   VALUES (CARD_ID, GRADE, INTERVAL, ELAPSED);"

Step 4 — Promotion Check (after all cards)

For each card reviewed with grade = Good where reps >= 5:

sqlite3 "$DB" \
  "SELECT c.id, c.tags, c.deck_id, cs.reps
   FROM cards c JOIN card_state cs ON cs.card_id = c.id
   WHERE c.id = CARD_ID AND cs.reps >= 5;"

If reps >= 5 and tags contain [N1], check deck retention over last 7 days:

sqlite3 "$DB" \
  "SELECT CAST(SUM(CASE WHEN grade=3 THEN 1 ELSE 0 END) AS REAL) / COUNT(id) AS retention
   FROM reviews r JOIN cards c ON c.id = r.card_id
   WHERE c.deck_id = DECK_ID AND r.reviewed_at >= datetime('now', '-7 days');"

If retention >= 0.9:

• Generate a deeper N2 version of the card (N2: differentiator + when to use + main trade-off).
• Insert as new card with tag [N2], due today.
• Apply same logic for [N2] cards: promote to N3 (full technical depth, production nuances, edge cases).

Step 5 — Session Summary

Session complete.
Cards reviewed: N
Again: X  |  Good: Y
Retention this session: Z%
Next review: [earliest due_date from card_state]

Append to today's conversation log:

echo "[HH:MM] review session | Cards: N | Retention: Z% | Promotions: P" \
  >> "${ALGERNON_HOME}/memory/conversations/YYYY-MM-DD.md"