Cosimo

Cosimo User Guide
Login

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:

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:

Set review database backups in File -> Options:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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