studyflash

A terminal-based spaced repetition flashcard system that reads from your markdown notes. Study smarter using the scientifically-proven SM-2 algorithm.

The Problem

You take notes in markdown but never review them. Flashcard apps like Anki require manual card creation and are separate from your notes. Your knowledge decays because you don't review at optimal intervals.

Features

• Markdown-powered — Write flashcards directly in your existing .md files
• SM-2 algorithm — Scientifically-proven spaced repetition scheduling
• Terminal UI — Study without leaving your terminal
• Progress tracking — See your retention rates, streaks, and weak areas
• Tags & decks — Organize cards with tags, study specific topics
• Stats — Track your learning velocity and review forecast

Installation

pip install -e .

Quick Start

1. Create flashcards in markdown

Create any .md file with this format:

# Python Basics

## What is a list comprehension?
A concise way to create lists: `[expr for item in iterable if condition]`

## What's the difference between `==` and `is`?
`==` checks value equality, `is` checks identity (same object in memory)

## What does `@property` do?
Defines a method that can be accessed like an attribute, enabling getter/setter patterns

Each ## heading is the question, the content below is the answer.

2. Add a deck

studyflash add ~/notes/python.md --tag python

3. Study!

studyflash study

4. Check progress

studyflash stats

Card Format

Basic (Question → Answer)

## Question here?
Answer here.

With tags

<!-- tags: python, basics -->
## What is a decorator?
A function that wraps another function to extend its behavior.

Multi-line answers

## Explain Python's GIL
The Global Interpreter Lock (GIL) is a mutex that protects access to Python objects.

- Only one thread executes Python bytecode at a time
- I/O operations release the GIL
- Use multiprocessing for CPU-bound parallelism

Commands

studyflash add <file.md>     # Add cards from a markdown file
studyflash study             # Start a study session
studyflash study --tag py    # Study only cards with a specific tag
studyflash stats             # View learning statistics
studyflash due               # See how many cards are due
studyflash list              # List all decks
studyflash reset             # Reset all progress (careful!)

How SM-2 Works

After seeing each card, rate your recall:

• 0 — Complete blackout
• 1 — Wrong, but recognized the answer
• 2 — Wrong, but it was on the tip of your tongue
• 3 — Correct, but with significant difficulty
• 4 — Correct, with some hesitation
• 5 — Perfect recall

The algorithm adjusts the interval until the next review based on your rating. Cards you struggle with appear more frequently.

Data Storage

Progress is stored in ~/.studyflash/progress.db (SQLite). Your markdown files are never modified.

License

MIT