Memoire spaced repetition system documentation

By dkl9, written 2023-186, revised 2023-200 (1 revisions)


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.

§ 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 two types of cards: basic multi-cloze and sequential.

From a basic multi-cloze card, there is a prompt for each cloze deletion (indicated with curly brackets around the deletion), which shows 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 construct four prompts from the card, 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.

From a sequential card, there is a prompt for each clause (indicated with a double-semicolon separator), 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 construct four prompts from the card. 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.

You may be able to include images in cards (of either 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.

I say "may be able to" sith this feature expects a particular unpublished program I have on my system.

§ 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 image viewer symlink/wrapper script, which 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 (multi-cloze or sequential) from the content of the note. If there are braces, it's saved as multi-cloze. If there are double-semicolons, it's saved as sequential. If both are present, the procedure favours multi-cloze.

§ 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 presents 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 erroneous 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: