Memoire spaced repetition system documentation

By dkl9, written 2023-186, revised 2025-182 (4 revisions)

Document list | dkl9 home

Memoire is a spaced repetition/memorisation/study program, usable entirely in the terminal. I made it largely out of frustration with the slow performance of Anki. It is primarily for my own use and may well be too idiosyncratic or mediocre to benefit you.

§ Overview

Here's how you memorise knowledge with Memoire, roughly the same as with any spaced repetition program:

  1. Set up Memoire.
  2. Learn something.
  3. Distill knowledge into one or more notes, suitable for cards.
  4. Add those cards to your deck.
  5. Review your deck every day (or a bit more or less often, if needed) as Memoire directs.
  6. Correct notes when you realise they're wrong or unhelpful.
  7. Repeat steps 2-4 whenever appropriate.
  8. Be a genius (well, maybe).

§ Data format

Any time you run Memoire, it will operate on a deck. A deck is stored as a Recfile. A deck consists of a list of cards, each card corresponding to a record. A card consists of a note and some associated fields, and may be expanded to a list of prompts generated from the note. For now, there are four types of cards: basic multi-cloze, cyclic, pairwise cloze, and sequential.

§ Basic multi-cloze (bmc)

Each note contains one or more cloze deletions, delimited with curly brackets. There is a prompt for each such deletion, showing the entire note except that deletion. For example, if the note is

bio organelles: matter enters the {Golgi apparatus} on the {cis face} and exits {in a vesicle} on the {trans face}

then Memoire will make four prompts, one omitting "Golgi apparatus", one omitting "cis face", one omitting "in a vesicle", and one omitting "trans face". Each prompt has the deletion re-inserted as the answer.

§ Cyclic (cys)

Each note contains two or more clauses, separated by double-semicolons, and ends with a terminal double-semicolon. Text before the first double-semicolon is treated as context. There is a prompt for each clause, showing the context and that clause alone. For example, if the note is

bio: ;;agar, made of ;;semisolid polysaccharide, found ;;from red algae, used in microbiology as substrate, that's called ;;

then Memoire will make three prompts. One will be "bio: agar, made of", and another will be "bio: semisolid polysaccharide, found". Each prompt has the next clause appended as the answer. The prompt for the last clause has the first clause as its answer, hence "cyclic".

§ Pairwise cloze (pwc)

Each note contains two or more clauses, separated by double-semicolons. Text before the first double-semicolon is treated as context. Each clause may contain a cloze deletion, delimited by curly brackets. There is a prompt for each ordered pair of distinct clauses for which the second clause has a cloze deletion. For example, if the note is

words zh:;; hanzi 面包;; pronounced {miànbāo};; means {bread} (en)

then Memoire will make four prompts, two asking for pronunciation (omitting "miànbāo"), two asking for meaning (omitting "bread").

§ Sequential (seq)

Each note contains two or more clauses, separated by double-semicolons. Text before the first double-semicolon is treated like any other clause. There is a prompt for each clause, which shows the part of the note before that clause. For example, if the note is

quotes: A.N. Whitehead on automatic thought processes: ;;Civilization advances by extending ;;the number of important operations ;;which we can perform ;;without thinking about them.

then Memoire will make four prompts. One of those will show "quotes: A.N. Whitehead on automatic thought processes: Civilization advances by extending ", and append "the number of important operations " as the answer.

§ Images

You may be able to include images in cards (of any type) with IMG[path/to/image] syntax, where the path is relative to the directory containing your deck file. For example, if the note is

machines: what is this thing? IMG[img/velomobile.jpg] {velomobile}

and your deck file is at /home/jsmith/memoire/deck.rec, then, when reviewing, Memoire will display the image at /home/jsmith/memoire/img/velomobile.jpg.

Some scripts, which have their own dependencies, may help you make images for cards.

§ Setup

I have only used Memoire on Linux. It will probably only work on Linux. You can try to run it on a different system, but you'll have to hack the code a bit.

  1. Download the source code.
  2. Make sure you have Lua installed.
  3. Pick a directory to store your deck and images.
  4. Make a blank SOMETHING.rec file there.
  5. Edit ~/.config/memoire/config.rec (see Configuration section). Make sure to at least put in DeckFile, pointing to your SOMETHING.rec.
  6. If you want to use images, make sure you have at /usr/local/bin/iv a copy of iv, or another image viewer that accepts an image path on the command line and a -t title option to set its window title.
  7. If you want to use vocal review, make sure you have eSpeak installed.
  8. Run src/main.lua on the command line. Most operations you might want to do relating to it are implemented as command-line options in src/main.lua.

§ Adding cards

src/main.lua a reads standard input for notes from which to generate cards, and saves them to the deck. The notes must be separated by blank lines. Each note can have multiple lines. There must be an extra blank line at the end of the input.

This feature auto-detects the type of card from the content of the note. If the note is formatted plausibly like pairwise cloze, it's saved as pairwise cloze. If there are braces, it's saved as multi-cloze. If there are double-semicolons, it's saved as cyclic (if there is a final double-semicolon) or as sequential (otherwise). If both are present (and it was not detected as pairwise cloze), the procedure favours multi-cloze.

For suggestions on how to write cards, check my examples.

§ Correcting cards

src/main.lua c N (where N is an integer) opens the note for card N from the deck in a text editor. Edits performed in the editor (once you save and exit) will be applied to the note saved in the deck.

You do not need to manually count out N! Use the query feature.

§ Leech search

src/main.lua l outputs a list of all (non-suspended) prompts which are judged to be "leeches" by their unusual difficulty. At the start of each line is a pair of numbers M:N. M is the number of the card, and N is the number of the leech-prompt in the card.

§ Querying the deck

src/main.lua q A (where A is a string) outputs a list of all cards with A in the note. At the start of each line is the number of the card in the deck.

§ Review (in the terminal)

src/main.lua r runs a review session.

For each prompt due for review, up to the limit you specify at the start (this gets much easier than it looks):

  1. Memoire shows the prompt.
  2. You think of the answer (or fail to do so after trying).
  3. You press Enter.
  4. Memoire reveals the answer.
  5. You enter something starting with a/h/g/e/c (or 0/1/2/3/-) to indicate, respectively, that you
  6. You add q to the end of that input iff you want to quit early, and press Enter.

At the end, you get brief statistics on your results and a list of any prompts you marked as having flawed notes, with their card-numbers. The prompts you reviewed are scheduled for later review according to your responses and a fancy formula.

§ Statistics

src/main.lua s presents statistics on your deck, including several histograms.

§ Toggling prompts

src/main.lua t M:N (where M and N are integers) toggles prompt N of card M from active to suspended (not to be reviewed) or back.

§ Vocal review

src/main.lua v runs a review session. This functions mostly the same as src/main.lua r (review in the terminal), except that the interface's output is conveyed thru eSpeak text-to-speech, and it is probably much more buggy.

§ Configuration

Most configuration is done with a Recfile at ~/.config/memoire/config.rec, which supports the following options:

§ Helper scripts

Included with Memoire are shell scripts frames.sh and occlude.sh, the latter of which works differently when invoked from symlink highlight.sh. They are meant to help make images for cards. The files each contain comments documenting their usage.