FlashLearn

FlashLearn is a local Leitner flashcard system with two entry points:

• an MCP stdio server so an AI client can create decks, create cards, read cards, study cards, promote/demote cards, and inspect progress
• a localhost web app for interactive study and deck progress

The app stores data in data/flashlearn.json by default. Set FLASHLEARN_DATA=/path/to/file.json to use another location.

Run the Web App

npm run web

Open http://127.0.0.1:5731.

If that port is already in use, FlashLearn automatically tries the next port and prints the URL.

The web UI lets you add decks and cards, study due cards, turn on All cards to study beyond the due queue, reveal answers, skip cards, mark cards as remembered or forgotten, manually promote/demote cards, search cards, and view progress by deck and Leitner box.

The dashboard also shows an annual practice heatmap with daily average, days learned, longest streak, and current streak; category/tag progress chips; and active toggles for due cards, mastered cards, empty decks, archived decks, and practice-focus mode. Category selection filters both the card library and the study queue, and each card in the library has Practice, Edit, promote/demote, and delete actions for immediate recall and cleanup.

Use Backup JSON to download a full flashlearn-backup.json, or Export CSV to download card rows for spreadsheet review. Deck settings support renaming, descriptions, custom Leitner intervals such as 0,1,3,7,14, archive/restore, and delete.

Keyboard shortcuts while not typing in a form:

• r or Space: reveal
• 1 or f: forgot
• 2 or k: remember
• s: skip
• p: promote
• d: demote

The card library can filter by box, due date range, mastery state, minimum review count, and maximum review count.

Run the MCP Server

npm run mcp

Example MCP client config for Codex or another JSON-configured MCP client:

First, get the repository's absolute path from its root:

pwd -P

Replace /absolute/path/to/flashlearn below with that output. This keeps the configuration portable between clones and does not depend on a particular user account or Desktop layout.

{
  "mcpServers": {
    "flashlearn": {
      "command": "node",
      "args": ["/absolute/path/to/flashlearn/src/mcp-server.js"]
    }
  }
}

Example Claude Desktop config:

{
  "mcpServers": {
    "flashlearn": {
      "command": "node",
      "args": ["/absolute/path/to/flashlearn/src/mcp-server.js"],
      "env": {
        "FLASHLEARN_DATA": "/absolute/path/to/flashlearn/data/flashlearn.json"
      }
    }
  }
}

Available MCP tools:

• create_deck
• list_decks
• update_deck
• archive_deck
• delete_deck
• create_card
• update_card
• delete_card
• read_cards
• due_cards
• review_card
• promote_card
• demote_card
• progress
• export_data

Useful MCP tool arguments:

• create_deck and update_deck: pass boxIntervalsDays for deck-specific Leitner spacing.
• list_decks, read_cards, due_cards, and progress: pass includeArchived to include archived decks.
• read_cards: filter with query, tag, dueOnly, dueBefore, dueAfter, box, mastered, reviewCountMin, reviewCountMax, and hideMastered.
• export_data: pass format: "json" for backup data or format: "csv" for card rows.

Leitner Behavior

New cards start in box 1 and are due immediately. The default box intervals are:

box 1: now
box 2: 1 day
box 3: 2 days
box 4: 4 days
box 5: 7 days
box 6: 14 days
box 7: 30 days

When you remember a card, FlashLearn promotes it one box. When you forget a card, it returns to box 1. The highest box counts as mastered, but the card can still be studied manually or demoted later.

Verification

Install the locked dependencies and Chromium once in a fresh clone:

npm ci
npx playwright install chromium

Then run the complete verification suite:

npm test
npm run smoke:mcp
npm run smoke:web
npm run test:ui

npm run test:ui runs Playwright against an isolated temp data file and writes desktop/mobile screenshots under test-results/.

GitHub Actions runs the same four gates on Node.js 22. The CI runner also installs Chromium and its Linux system dependencies before the UI tests.

License

FlashLearn is available under the MIT License. The npm package remains marked private to prevent accidental publication.

Research Note

See docs/card-systems-research.md for researched alternatives and why this project uses Leitner as the default scheduler.