# Cosimo User Guide

Cosimo helps you study prompt and response pairs with spaced repetition. It is designed for keyboard and screen reader use.

## What Spaced Repetition Means

Spaced repetition is a study method based on reviewing material at increasing intervals.

When something is new, difficult, or recently missed, it should come back soon. When something is easy and consistently remembered, it can wait longer. The goal is to spend more time on material that needs attention and less time repeating what is already secure.

In Cosimo, each thing you learn is a card:

- the prompt is the question, cue, or sentence you see first
- the response is the answer you check yourself against

Cosimo records your ratings after each review and uses that history to decide which cards are due.

## Installing and Upgrading

Cosimo is a portable application. To install it, expand the release zip file into the folder where you want Cosimo to run, then start `cosimo.exe` from that folder.

To upgrade, close Cosimo, expand the new release zip over the existing Cosimo folder, and allow program files to be overwritten. Release packages should not overwrite user data such as `cosimo.ini`, personal decks, review databases, reports, or backups. Keep normal backups before upgrading, especially if you store your own decks in the application folder.

## Decks

A deck is a file containing cards. Cosimo deck files use the `.cosimo-deck` extension.

You can edit cards inside Cosimo, or edit the deck file directly in a text editor. The deck file stores prompts, responses, deck metadata, and card markers such as non-reversible status. Review history and ratings are stored separately.

Deck files also contain a small numbered marker at the end of each card, such as `=1=`. Leave that number in place when editing by hand. It lets Cosimo keep the card’s review history even if you change the prompt or response text. When Cosimo opens an older deck, it backs up the original according to your deck backup setting and upgrades the deck file to the current format.

Use `File -> Deck Properties` to view the deck format version and optional metadata fields: title, author, description, and URL. Use `File -> Edit Deck Metadata` to edit those metadata fields.

Cosimo can use a same-stem directory beside a deck file for optional WAV review audio. For example, `Indonesian.cosimo-deck` can use an `Indonesian` directory containing files such as `1.prompt.wav` and `1.response.wav`. Cosimo reads those files during ordinary review, and reads prompt audio while answering exam questions, if review audio is enabled. It does not create, edit, or back up audio files in this first audio pass.

The default deck is `decks/deck.cosimo-deck` beside the Cosimo executable. On Windows portable installs, keep your decks in the `decks` folder beside the application. If the default deck is missing, Cosimo creates an empty one. You can open another deck from `File -> Open Deck`. If you choose a deck file that does not exist, Cosimo asks whether to create an empty deck there.

When Cosimo closes, it remembers the last opened deck and opens it again next time. It also keeps up to eight recently opened decks in `File -> Recent Decks`, omitting the current deck. If there is only one other recent deck, Cosimo shows it directly in the `File` menu instead of placing it in a submenu. It stores this and other application settings in `cosimo.ini` beside the executable. Cosimo also remembers the ready-list filter and sort mode. If Cosimo finds older `cosimo-settings.txt` or `cosimo-last-open-deck.txt` files, it migrates them into `cosimo.ini` and removes the old files.

The options dialogue can also configure review-availability sounds, review audio, the learning-dashboard calibration recall rule, and minimise-to-tray behaviour. Sound notifications can be set to `Always`, `When Cosimo is visible`, `When Cosimo is in the system tray`, or `Never`. When the chosen policy permits sound, Cosimo plays a short sound when the timed ready-screen refresh notices that reviews have become available, or that more reviews have become available since the last automatic refresh. User-triggered changes, such as adding or removing cards, and manual `F5` refreshes do not play this sound. Cosimo also stays silent while a review pass is active, even if more cards become due during that pass. With minimise-to-tray enabled, using the normal window minimise action hides Cosimo in the system tray instead of leaving it on the taskbar. Activating the tray icon restores the window, and the tray context menu contains Restore and Quit. Closing Cosimo still exits the application.

## Help and Project Links

The `Help` menu opens the local user guide, the project wiki, and the new ticket page for bug reports. Bug reports are handled through Fossil tickets on the project site.

## Backups

Back up both the deck file and its matching review database. The deck file contains your cards, deck metadata, and non-reversible card markers. The review database contains scheduling state, ratings, and review history.

Cosimo also creates automatic deck-content backups. Before it overwrites an existing deck, it copies the current deck into the app-level `backups` directory beside the executable. Backup files have rising numbers, for example `backups/000001-deck.cosimo-deck`. The `backups/index.txt` file records each backup filename and the original deck path.

Set automatic deck backups in `File -> Options`:

- `Full`: keep every automatic deck backup.
- `Last only`: keep only the newest automatic backup for each original deck path.
- `None`: do not create automatic deck backups.

Set review database backups in `File -> Options`:

- `On session start`: refresh one retained review-database backup when a review pass starts.
- `Off`: do not create or refresh review-database backups.

Use `File -> Scrub Review Database` to permanently delete dormant review database rows for cards that are no longer in the current deck and for inactive generated reverse cards. Active cards, active generated reverse cards, current schedules, current suspensions, and current flags are kept. Non-reversible markers are stored in the deck file, not the review database. If review database backups are off, Cosimo warns that the scrub is irreversible. If review database backups are enabled, Cosimo refreshes the retained review-database backup before scrubbing and warns that the retained backup will be overwritten. After deleting inactive rows, Cosimo vacuums the database so the SQLite file can reclaim unused space.

Use `File -> Reclaim Database Space` to run the same SQLite vacuum without deleting dormant review data. This rewrites the review database file and may take some time on a large database. If review database backups are enabled, this command does not overwrite the retained backup; if backups are off, Cosimo reminds you to make sure you have a backup if concerned.

For the default deck, back up:

- `decks/deck.cosimo-deck`
- `decks/deck.reviews.sqlite3`, if it exists

For another deck, the review database is beside the deck and uses the same base name. For example, `spanish.cosimo-deck` uses `spanish.reviews.sqlite3`.

Close Cosimo before copying or restoring backup files. Restoring only the `.cosimo-deck` file restores the cards but starts them without their previous review history. Restoring both files preserves the cards and their scheduling history.

Cosimo checks the review database integrity when opening a deck. If Cosimo says the review database failed an integrity check, close Cosimo and restore the matching `.reviews.sqlite3` file from your backup.

Automatic deck backups contain only the deck text, not review history. To restore one, close Cosimo and copy the chosen backup over the active `.cosimo-deck` file. To restore scheduling history, restore the matching `.reviews.sqlite3` file from your own backup or from Cosimo’s retained review-database backup.

Use `File -> Options -> Delete Old Backups` to keep only the newest automatic backup for each original deck path. Cosimo asks for confirmation before deleting or renumbering backup files.

For step-by-step recovery help, see Troubleshooting.

## Ready Screen

When Cosimo starts, it opens on the ready screen. This screen shows:

- how many cards are in the deck
- how many cards are scheduled now
- the minimum cards per session
- the review database file
- a list of card prompts

If the minimum cards per session causes Cosimo to add extra cards that are not due yet, the scheduled count also shows the due-card count in parentheses. For example, `Scheduled now: 10 (6 due)` means a pass would include 6 due cards and 4 extra cards to reach the minimum.

The main window status bar also gives a short overview: total cards, cards due now, and either that a review is due now or roughly how long until the next scheduled review. Durations are rounded up to speech-friendly units such as `2 days`, `4 weeks`, or `3 months`.

While the ready screen is open, Cosimo refreshes the ready summary, list filters, and status bar about once per minute. A card that becomes due while the application is open will therefore become available for `Start` without closing and reopening the deck.

You can add, edit, or remove cards before starting a pass. After a card has been revealed during review, you can also edit that current card if you notice a mistake in the prompt or response. `Cards -> Edit Selected Card` changes to `Cards -> Edit Current Card` at that point.

For repeated entry, use `Cards -> Add Card Batch`. Enter a prompt and response, then press `Ctrl+Enter` from either field to add the card and return to the prompt field. Pressing Tab from the response field also adds the card and returns to the prompt field when both fields contain text. Press Escape to close the batch dialogue.

Useful keys on the ready screen:

- `Alt-S`: start the scheduled pass
- `Alt-T`: force-start all cards not suspended or deferred
- `Alt-X`: start an exam pass from a random active-card sample
- `Alt-L`: move to the text filter for the prompt list
- `F5`: refresh the ready summary, list filters, and status bar
- `Ctrl+L`: show the learning dashboard
- `Alt-Q`: quit
- `Alt+Enter`: show details and statistics for the selected card
- `Delete`: remove the selected card from the prompt list
- `Ctrl+S`: suspend or unsuspend the selected card
- `Ctrl+F`: flag or unflag the selected card
- `Ctrl+D`: defer the selected card until tomorrow, or clear its deferral
- `Ctrl+R`: make the selected card reversible, or remove the generated reverse card

The card details dialogue shows the prompt, response, card ID, current card state, review count, last review, scheduling state, next scheduled review, and review history for the selected card. Card state combines visible markers such as suspended, flagged, deferred, reverse, has reverse, and non-reversible on one line. Generated reverse cards show the parent card ID, because editing the parent card in the deck also changes its generated reverse direction. Date fields in the summary, such as last review, schedule last reviewed, and next scheduled review, are shown first as a complete relative duration, such as `1 day, 1 hour, 1 minute, 1 second`, followed by the exact UTC timestamp in parentheses. Past dates use the same complete relative duration followed by `ago`. The review history list at the bottom uses exact UTC timestamps only.

Use `File -> Learning Dashboard`, or press `Ctrl+L`, to show a deck-wide learning summary. It reports several kinds of information:

- card counts by scheduling state: new, learning, review, and relearning
- available-now and scheduled-and-overdue counts, ignoring suspended and deferred cards
- model-based recall estimates for active cards with scheduling data
- confidence calibration from your pre-response predictions and later recall ratings
- recent learning pace, based on how many reviews cards needed before first reaching review state
- review activity, including days with answers, stored answers, answers in recorded passes, and time spent in completed passes

The recall section is an estimate from Cosimo’s scheduling model, not a direct test result. For each active card with scheduling data that is not suspended or deferred, Cosimo uses the last review time, the stored stability, and the actual scheduled interval to estimate how likely you are to recall the card now. New cards without scheduling data, suspended cards, and currently deferred cards are not included in this estimate. Learning and relearning cards use their short scheduled interval as the effective 90% point, so a card due after a short failed-card step does not look safer than it is.

`Available now` counts active cards that are not suspended or deferred and can be reviewed immediately. This includes new cards and scheduled cards whose due time has arrived. `Scheduled and overdue` is the narrower count of scheduled cards whose due time is already in the past and that are not suspended or deferred, so it does not include new unscheduled cards.

`Average estimated recall` is the average of those per-card estimates. `Likely known cards` counts estimated cards at or above 90% recall. `At-risk cards` counts estimated cards below 70% recall. These numbers are best used for triage and trends, not as a promise that exactly that percentage of cards will be answered correctly in the next pass.

The calibration section treats your prediction before seeing the response as a target interval for whether you will recall the answer, not as a precise percentage. `Don't know` means a 0-5% recall target, `Probably don't know` 5-32%, `Probably know` 68-95%, and `Certainly know` 95-100%. The middle range is deliberately uncovered; reveal without a confidence rating if you do not want to make a prediction. The recall rule is configured in `File -> Options`. The lenient rule counts `Hard`, `Good`, and `Easy` as recalled, while `Again` counts as not recalled. The strict rule counts only `Good` and `Easy` as recalled. The dashboard shows the active rule before the calibration figures. The target recall range is the average of the target intervals for answered confidence ratings. The observed recall rate is what actually happened under the current recall rule. Calibration is within target if observed recall falls inside the target range, under-confident if observed recall is above the range, and over-confident if observed recall is below it. The per-confidence lines show the same comparison for each confidence rating. Cards revealed without a prediction are counted separately.

The review activity section is based on recorded review events and pass summaries. `Stored answers` counts individual stored answers. `Days with answers` counts UTC days on which at least one answer was recorded. Pass, answer, and time totals labelled as recorded passes come from completed pass summaries. If older data predates pass summaries, the dashboard shows `Older answers without pass timing` so the stored-answer total is not confused with the smaller timed-pass total. That line is hidden when the value is zero.

Use the dashboard’s `Save Report` button to save the current dashboard text in the `reports` directory. The report file name uses the deck name and the UTC time when the dashboard was opened, and the report includes the full deck and review database paths.

If the deck has generated reverse cards, the dashboard shows standard cards, reversed cards, and total cards separately, because one direction can be much easier than the other.

Use `View -> Deck Order`, `View -> Next Scheduled Review`, or `View -> Last Reviewed`, `View -> Prompt Text`, `View -> Response Text`, or `View -> Estimated Recall` to choose how the prompt list is sorted. Use `View -> Ascending` or `View -> Descending` to choose the direction. The checked View menu items show the current sort criterion and direction. Last reviewed defaults to descending, putting the most recently reviewed cards first and new cards at the bottom; ascending last reviewed puts the oldest reviewed cards first and still leaves new cards at the bottom. Estimated recall uses the same scheduling estimate as the learning dashboard; ascending estimated recall puts cards estimated as less likely to be remembered first and leaves cards without an estimate, such as new cards, at the bottom. The text filter narrows the list by matching text in the prompt or response. The filter combo box controls which type of cards are shown, including flagged cards, duplicated prompts, and duplicated responses, non-reversible cards, and deferred cards. Its counts follow the current text filter. The duplicated-response filter is especially useful before making cards reversible, because duplicate responses make reverse prompts ambiguous.

Use `Cards -> Suspend Selected Card`, the context menu on the prompt list, or `Ctrl+S` while the prompt list has focus, to keep the selected card in the deck while preventing it from appearing in normal or forced review passes. The prompt list marks suspended cards with `(suspended)`. Suspended cards can still be found with the `Suspended cards` filter and unsuspended from the same menu, context menu, or shortcut. Suspended cards are also ignored when the status bar reports whether a review is due now or when the next review is due.

Use `Cards -> Defer Selected Card until Tomorrow`, or the context menu on the prompt list, to postpone the selected card temporarily without changing its stored schedule. A deferred card remains in the deck and returns automatically when the deferral expires. While deferred, it is marked with `(deferred)`, appears in the `Deferred cards` filter, and is excluded from scheduled passes, forced passes, ready-screen counts, and status-bar due calculations. Use `Cards -> Clear Selected Card Deferral`, or the context menu, to make it available again immediately.

During a review pass, before revealing the answer, use `Ctrl+D` or the `Defer Card until Tomorrow` button to postpone the current card and move on. Deferral is not available after the answer has been revealed. If every card in the pass is deferred before any answer is recorded, Cosimo shows a notice that no cards were reviewed.

Use `Cards -> Flag Selected Card`, the context menu on the prompt list, or `Ctrl+F` while the prompt list has focus to flag or unflag the selected card. During a review pass, `Ctrl+F` flags or unflags the current card. The review screen also has a Flag/Unflag button after the confidence buttons and after the recall buttons. Flagging is for manual follow-up: use it when a card may need editing, feels confusing or ambiguous, has a dubious answer, or otherwise needs attention after the pass. Flagging does not affect scheduling or whether the card appears in review. Flagged cards are marked with `(flagged)` in the prompt list and can be found with the `Flagged cards` filter.

Use `Review Flagged` on the ready screen, or `Cards -> Review Flagged Cards`, to start an unscheduled pass through flagged cards only. This pass includes flagged cards whether or not they are currently scheduled, but excludes cards that are suspended or deferred. The order is randomised, and the pass does not clear the flags; remove flags manually when the cards no longer need follow-up. The button is disabled when there are no flagged cards available to review.

Use `Cards -> Make Selected Card Reversible`, or press `Ctrl+R` while the prompt list has focus, to add a generated reverse card. A reverse card asks for the original response and expects the original prompt. Reverse cards have their own scheduling state and review history. Cosimo blocks making a card reversible when another card has the same response, because the reverse prompt would be ambiguous. Reverse cards are marked with `(reverse)` in the prompt list and can be found with the `Reverse cards` filter. Removing a reverse card removes only the generated reverse direction; it does not remove the parent card. The reverse card’s review data remains in the database and is used again if you make the parent card reversible later. When a generated reverse card is selected, the card menu and context menu offer removal of that reverse direction, not marking the parent card non-reversible.

Use `Cards -> Mark Selected Card Non-Reversible` when a card should not have a generated reverse direction. This writes a marker into the deck file, removes any active generated reverse card for that parent card, and prevents `Make Possible Cards Reversible` from adding it again later. Use `Cards -> Allow Selected Card Reversal` to remove that marker. The card then becomes eligible for manual or bulk reversal again, provided its response is not duplicated. Non-reversible cards are marked with `(non-reversible)` in the prompt list, can be found with the `Non-reversible cards` filter, and show the non-reversible marker on the card details state line. When a non-reversible card is selected, the menus offer allowing reversal again rather than making a reverse card directly.

Use `Cards -> Make Possible Cards Reversible` to mark every currently eligible card reversible in one operation. Cosimo asks for confirmation and tells you how many cards can be changed. Cards that are already reversible, cards marked non-reversible, and cards whose responses are duplicated by another card are excluded. If review database backups are enabled, this operation refreshes the retained review-database backup before writing and the confirmation warns that the retained backup will be overwritten.

Use `Cards -> Undo Last Bulk Reversal` to remove only the reverse cards created by the latest bulk reversal. Manually created reverse cards and earlier bulk batches are kept. Parent cards and reverse review history remain in the database.

Removing a parent card also removes its generated reverse card from the prompt list, because the reverse card is derived from the parent card. The reverse review data remains in the database, but it is only useful again if you restore a deck backup containing the original parent card.

Known issue: when you tab or shift-tab into the prompt list, some screen reader and wxWidgets combinations announce the selected item twice. Once you are in the list, arrow-key navigation should work normally.

## Starting a Pass

There are three main ways to start reviewing.

`Start` uses the schedule. It reviews due cards first. If fewer cards are due than your configured minimum cards per session, Cosimo randomly adds extra cards from the rest of the deck.

`Force Start` ignores the schedule. It puts every card that is not suspended or deferred into a random order. Use this when you want to study even though no cards are due, or when you want a longer practice session.

`Start Exam` samples from the active deck instead of using the schedule. Suspended and deferred cards are excluded. Cosimo asks whether to choose a number of questions or a percentage of active cards, then picks and orders the selected cards randomly to reduce cues from deck order.

During an exam, Cosimo shows each prompt and asks you to type the response. It does not show feedback while the exam is running. Exact answers are counted as correct automatically. At the end, for each answer that was not an exact match, Cosimo shows the prompt, your answer, and the expected response, then asks whether the answer should count as correct.

If the `Exact` checkbox is selected when starting the exam, non-exact answers are not graded manually. They count as incorrect, and Cosimo shows each one for review with the prompt, your answer, and the expected response. Choose `Next` or press `Alt-N` to continue reviewing inexact answers, or choose `Summary` to go straight to the exam summary.

Exam mode currently produces a report only. It does not record review events, change card schedules, or add failed answers back into the same pass. This is deliberate: the first version is an assessment tool, not another scheduling input.

During a normal pass, press `0` to end the pass early. During an exam pass, choose `End Exam` to stop after the answers submitted so far. If no answers were submitted, Cosimo shows a notice.

## Before the Response

When a prompt is shown, you can rate how likely you think you are to know the response:

- `1`: don’t know
- `2`: probably don’t know
- `3`: probably know
- `4`: certainly know

This is your prediction before seeing the response.

You can also choose `Reveal Response`, or press Space, to show the response without recording a prediction. This is stored as `Not answered` in the pass statistics.

## Rating After the Response

After you rate your prediction or reveal the response directly, Cosimo shows the response. Then rate what actually happened:

- `1`: Again
- `2`: Hard
- `3`: Good
- `4`: Easy

This feedback is what Cosimo uses most directly to schedule the card.

If you notice a mistake after the response is shown, choose `Edit Card`, use `Cards -> Edit Current Card`, or press `e`. Cosimo opens the same editor used elsewhere, saves the card text, and returns you to the post-response rating step. The scheduling decision is still made only after you choose the recall feedback rating.

## Review Audio

Review audio is optional and currently supports WAV files only. Configure it in `File -> Options -> Audio during reviews`:

- `No audio`: Cosimo ignores card audio.
- `Manual`: if the current prompt or response has audio, Cosimo labels it as having audio and shows a `Play/Stop Audio` button.
- `Automatic`: Cosimo plays prompt audio when a prompt appears and response audio when a response appears during ordinary review. The same button can stop or replay the current audio.

`Ctrl+P` activates the same play/stop action when review audio is available. Moving to the next card, revealing the response, finishing the pass, or closing the window stops any current card audio immediately. In exam mode, prompt audio is available while answering the question; response audio is not used during exam grading yet.

Audio files live in the same-stem directory beside the deck. For card `1` in `Indonesian.cosimo-deck`, use `Indonesian/1.prompt.wav` for the prompt side and `Indonesian/1.response.wav` for the response side. Generated reverse cards reuse the parent card’s files with prompt and response swapped.

## How Scheduling Works

Cosimo stores each completed review in the review database. For each card, it looks at the review history and estimates when the card should come back.

In general:

- cards with no review history are due immediately
- missed or wrong cards come back sooner
- hesitant correct cards progress more cautiously than easy correct cards
- confidently correct cards wait longer

Cosimo uses an FSRS-style scheduling algorithm. It tracks each card’s difficulty and stability. Repeated correct answers make the card more stable and lengthen the interval, while missed or wrong answers move the card back toward learning. Cards marked `Again` are scheduled for a short learning or relearning step after about 10 minutes. They are also shown once more at the end of the current pass. When several cards need repeating, those repeats are ordered randomly. If the repeat is still marked `Again`, it is recorded normally but is not added again to the same pass.

The exact interval is automatic. You do not need to manage dates yourself.

The minimum cards per session controls how many cards Cosimo tries to include when you press `Start`. For example:

- if the minimum is `0`, Cosimo reviews only cards that are due
- if the minimum is `10` and only 6 cards are due, Cosimo adds 4 random extra cards
- if 20 cards are due and the minimum is `10`, Cosimo includes all 20 due cards

The minimum is not a maximum. Due cards are not hidden just because there are more of them than the minimum.

When a pass starts, due learning and relearning cards are shown before ordinary review cards, then new cards follow. Within the learning/relearning and review groups, the most overdue cards are shown first. Cards with the same due time, or due times within about one hour of each other, are ordered randomly within that group. New cards are also ordered randomly, so cards added in thematic groups are not reviewed in deck order.

Set the minimum in `File -> Options`.

## Statistics

At the end of a pass, Cosimo shows statistics for that pass:

- how many unique cards were reviewed, not counting repeats
- how many questions were answered in total, including repeats
- total time, time per question, and time per unique card
- counts and percentages for prediction ratings, including responses revealed without a prediction
- counts and percentages for recall feedback ratings

Cards deferred before the answer is revealed are not counted as answered questions in the pass statistics.

Exam passes show a separate exam summary. It reports the number of selected questions, submitted answers, correct answers and percentage, exact matches, accepted non-exact answers, incorrect answers, total time, time per question, and whether the exam ended early. Exam summaries do not change the review database.

Choose `Save Report` to write a text copy of a normal pass summary or exam summary to the `reports` directory beside the executable. Cosimo creates the directory if needed. Normal report filenames use the deck file name without its extension and the pass finish time in UTC, for example `Indonesian-2026-05-03-06-04.txt`. Exam report filenames add `-exam`, for example `Indonesian-exam-2026-05-03-06-04.txt`. If a report with that name already exists, Cosimo adds a numeric suffix instead of overwriting it. The report text includes the full deck path.

Choose `Continue` to return to the ready screen.

## Languages and Translation

Cosimo currently supports English, Spanish, and Galician. Change the language in `File -> Options`.

The language choice is saved and used next time. If no language has been saved yet, Cosimo uses Spanish when the system locale is Spanish, Galician when the system locale is Galician, and otherwise falls back to English. Unknown locales also fall back to English.

Translations are maintained in gettext-style `.po` files, with a small amount of source-code wiring for each new language. If you want to work on a translation, contact David Picón Álvarez first at `@modulux@node.isonomia.net` so the work can be coordinated.

## Tips

- Keep prompts specific. A card should ask for one thing.
- Keep responses short enough that you can judge them consistently.
- Use `Force Start` for extra practice, not as a replacement for the scheduled pass.
- If a card is confusing, edit it before the next pass. If you find a typo or wrong answer after revealing the card, edit it before rating the recall.
- Use `0` when you want to stop a pass early; your completed reviews are still saved.