flashcard-engine

name	flashcard-engine
description	Spaced repetition flashcard system with SM-2 scheduling, Markdown support, and Anki import. Use when you need to study or manage flashcard decks, grade cards, check review schedules, or import/export card data. Triggers include "flashcards", "spaced repetition", "study cards", "Anki import", "SM-2", "review schedule".

flashcard-engine

Spaced repetition flashcard system with SM-2 scheduling. Cards support Markdown. Import from Anki or CSV.

When to use

• Studying card decks with spaced repetition scheduling
• Creating or editing flashcard decks and cards
• Importing Anki .apkg decks or CSV card files
• Checking the review schedule for upcoming due cards
• Exporting decks to CSV or JSON

Prerequisites

• Node.js 20+
• Server running locally (default port 4000)

Quick Start

pnpm install
pnpm dev
# Server: http://localhost:4000
# Client: http://localhost:5173

Study Flow

1. Open the dashboard at http://localhost:5173
2. Click a deck that has due cards (red badge)
3. Read the card front
4. Press Space or click "Show answer"
5. Read the answer
6. Grade 0-5 (or press 0-5 on keyboard):
   • 0 = Again (forgot completely)
   • 1 = Hard
   • 2 = Difficult
   • 3 = Good
   • 4 = Easy
   • 5 = Perfect (instant recall)
7. Repeat until no more due cards

API Reference

Study

GET  /api/decks/:id/study        Next due card for this deck
POST /api/cards/:id/review       Grade a card

Body: { "grade": 4 }
Response: { "nextReview": "2024-04-01", "interval": 8 }

Decks

GET    /api/decks             List all decks with due counts
POST   /api/decks             Create deck { name, description }
GET    /api/decks/:id         Deck with full stats
PATCH  /api/decks/:id         Update deck { name?, description? }
DELETE /api/decks/:id         Delete deck and all cards

Cards

GET    /api/decks/:id/cards   List cards in deck
POST   /api/decks/:id/cards   Create card { front, back, tags? }
PATCH  /api/cards/:id         Update card { front?, back?, tags? }
DELETE /api/cards/:id         Delete card

Import

POST /api/import/csv          Upload CSV file (multipart/form-data, field: file)
POST /api/import/anki         Upload .apkg file (multipart/form-data, field: file)

Export

GET /api/decks/:id/export/csv    Download deck as CSV
GET /api/decks/:id/export/json   Download deck as JSON

Environment Variables

Variable	Default	Description
PORT	4000	Server port
DATA_DIR	~/.flashcard-engine	SQLite storage directory
CORS_ORIGIN	http://localhost:5173	Allowed CORS origin
LOG_LEVEL	info	Log level: debug, info, warn, error

SM-2 Grades

Grade	Label	Meaning
0	Again	Complete blackout
1	Hard	Remembered with significant difficulty
2	Difficult	Remembered with effort
3	Good	Correct with some hesitation
4	Easy	Correct after brief thought
5	Perfect	Instant recall

Grades 0-2 reset the card's interval. Grades 3-5 increase the interval using the SM-2 formula.

Troubleshooting

No cards are due

All cards have been reviewed. Check the Schedule page for upcoming due dates.

Import fails for Anki .apkg

The .apkg must be from Anki 2.x. Verify the file is not corrupted. Very large decks (10,000+ cards) may take up to 30 seconds to import.

Deck shows 0 due but I have unreviewed cards

New cards are separate from due cards. Configure "New cards per day" in Settings to introduce new cards alongside reviews.