memodeck

A tiny spaced-repetition flashcard library with a command-line app. Pure standard library — zero runtime dependencies.

On PyPI: https://pypi.org/project/memodeck/ · Source: https://github.com/Vladikasik/memodeck

Cards live in decks, decks live in a SQLite database, and every review is logged. A simple 3-box Leitner system decides when a card is due again: answer correctly and it moves up a box (waiting 1, then 3 days), answer wrong and it drops back to box 1.

Install

pip install memodeck

Or from source, in a virtual environment:

python -m venv .venv && source .venv/bin/activate
pip install -e .
pip install -r requirements.txt   # dev tools: pytest, build, twine

The CLI

memodeck import examples/capitals.json   # sample deck from the source repo
memodeck decks                           # list decks
memodeck list capitals                   # show cards and their boxes
memodeck study capitals                  # review whatever is due
memodeck stats capitals                  # per-card accuracy
memodeck add capitals                    # add a card interactively
memodeck export capitals backup.json     # write a deck to JSON

The database defaults to ~/.memodeck.db; use --db path to keep it elsewhere.

The library

The CLI is just one consumer — everything it does is available as an API:

from memodeck import BasicCard, ClozeCard, Deck, DeckStore

deck = Deck("chemistry", [
    BasicCard("Symbol for gold?", "Au"),
    ClozeCard("Water is H2{{O}}."),
])

for card in deck.due():                  # polymorphism: any card type works
    print(card.question)
    if not card.check(input("> ")):
        print(f"Answer: {card.answer}")

with DeckStore("chem.db") as store:      # SQLite persistence
    store.save(deck)

Card types are subclasses of the Card ABC. Each one defines three members — question, answer, and check(response) — and registers itself for JSON deserialization automatically, so adding a new card type touches exactly one file:

Project layout

src/memodeck/
├── cards.py     # Card ABC + the three card types (inheritance, polymorphism)
├── deck.py      # Deck collection (dunder protocols: len/iter/contains)
├── storage.py   # DeckStore (SQLite) + JSON import/export (serialization)
└── cli.py       # argparse front-end over the library
tests/           # pytest suite, written test-first

Development

python -m pytest          # run the tests
python -m build           # build sdist + wheel into dist/
twine upload dist/*       # publish to PyPI

License

MIT