DKL9 GitList
Repositories
DKL9 home
memoire
Code
Commits
Branches
Tags
Search
Tree:
919259f
Branches
Tags
master
memoire
documentation.md
Revise documentation.md
dkl9
commited
919259f
at 2024-15 10:39:47
documentation.md
Blame
History
Raw
Memoire is a [spaced repetition]( https://en.wikipedia.org/wiki/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.]( #setup ) 2. Learn something. 3. Distill knowledge into one or more [notes, suitable for cards]( #data-format ). 4. [Add those cards]( #adding-cards ) to your deck. 5. [Review]( #review-in-the-terminal ) your deck every day (or a bit more or less often, if needed) as Memoire directs. 6. [Correct]( #correcting-cards ) 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]( https://www.gnu.org/software/recutils/manual/The-Rec-Format.html ). 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 ```memoire 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 ```memoire 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 ```memoire 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 ```memoire 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 ```memoire 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. Some [scripts]( #helper-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]( #configuration )). 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]( #data-format ) 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. ## 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 - failed to recall - recalled only with great effort - recalled with moderate effort - recalled easily - see an issue with the note 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. - ease: a number (usually 2 to 3) representing how easy a prompt is to remember - log2-delay: the base-2 logarithm of the delay scheduled between when you reviewed a prompt and when you should review it again - retention: the proportion of reviews of a prompt at which you (indicate that you) recalled it successfully - review counts: the number of times you reviewed each prompt - prompt-count: the number of prompts generated from each card ## 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: - `AllowedRandomVariation`: the maximum magnitude, as a proportion of the calculated interval, by which the actual interval may be randomly adjusted, default 0.1. For example, with ARV = 0.1 and a calculated interval of 12 days, the interval actually used may be anywhere from 10.8 days to 13.2 days, selected randomly. - `BoldContext`: set to any value or absent to determine whether context indicators (the part of a note before the first colon) should be shown in bold. - `DeckFile`: a path to your deck file, relative to the home directory (e.g. if the deck is in `/home/jsmith/memoire/deck.rec`, write `DeckFile: memoire/deck.rec`) - `EspeakFlags`: a string of command-line flags to pass to eSpeak during vocal reviews, default empty. - `HardRatio`: the ratio by which to scale intervals for prompts reviewed with a "hard" rating, default 1.2. - `PriorityBias`: a constant of mysterious units by which to bias the urgency of a prompt from a note containing corresponding `PriorityText`. Positive values make the prompt more urgent, and negative values, less urgent. 0.1 is a reasonable magnitude for this value. - `PriorityText`: a pattern of text such that, if a note contains that text, any prompts generated from that note will be regarded as more or less urgent to review than would otherwise be calculated. You can have multiple `PriorityText` fields to prioritise multiple groups of cards. Each one must have a corresponding `PriorityBias`. - `ShowProgress`: `true` or `false` to determine whether to show a progress indicator in review sessions, default false. - `StartingEase`: the ease-value assigned to a new prompt, default 2.5. Higher ease means reviews will be spaced apart more. Ease is adjusted by reviews. ## 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]( #images ) for cards. The files each contain comments documenting their usage.
