Reference: source https://github.com/riceissa/spaced-inbox Spaced Inbox Documentation This system provides spaced repetition for your notes written in plain text files, using a simple command-line interface and your favorite text editor. It aims to surface the most relevant and “exciting” notes at optimal intervals for long-term retention, while providing flexibility and control over your review process. 1. Note Format Write your notes in a plain text file (e.g., notes.txt). New Note Delimiters: Two blank lines, or a line containing at least three equals signs (and nothing else) like ======, signifies the start of a new note. 2. Defining Inbox Files inbox_files.txt: Create a file named inbox_files.txt to tell the script where your notes are located. Format: Each line should follow this structure: <short name><tab><file path>. Example: personal_notes /path/to/my/notes.txt <short name>: A user-defined identifier for your inbox file, used by the script to distinguish between different inbox sources. 3. Initializing and Updating the Database Initialization: Running script.py for the first time creates a SQLite database (data.db) and imports your notes into it to manage the review schedule. Subsequent Runs: script.py performs the following actions on each subsequent execution: Import new notes: Detects and adds new notes from your inbox files that haven’t been imported previously. Update note locations: If you’ve edited your inbox file and moved notes around (e.g., by adding or deleting lines), the script updates the corresponding line numbers in the database to ensure accurate navigation during review. Handle soft-deletions: If you remove a note from an inbox file, the script detects its absence and marks it as “soft-deleted” in the database. This prevents the deleted note from appearing in future reviews unless you add it back to the inbox file. 4. Daily Review Process Start a Review Session: Run script.py to initiate a review session. The script will analyze your notes based on due dates, note states, and overdueness to select the most appropriate note for review. Note Display: The script displays the beginning of the selected note along with its corresponding line numbers within the inbox file. This allows you to easily locate the note in your text editor. Review in Editor: Open your preferred text editor. Navigate to the indicated line numbers to find the full note content. Review the note, make edits if necessary, or delete the note entirely from the inbox file if you no longer need it (this will trigger a soft-deletion on the next script.py run). Record Your Response (in script.py’s prompt) [e]xciting: Use this command if the note is particularly valuable, stimulating, or if you want to ensure you review it more frequently, even if it’s not the most overdue. The script prioritizes “exciting” notes for selection, especially when they are overdue. The more overdue they get, the more likely they are to be chosen. [i]nteresting, [y]eah, [l]ol, [m]eh, [c]ringe, [t]axing: These commands represent varying degrees of positive or neutral feedback. They trigger the standard spaced repetition interval increase according to the SM2 algorithm, but they don’t influence the note’s priority in the selection process beyond its regular due date. The note state is recorded, which could potentially be used for refined note selection logic in future versions. again: If you failed to recall the note’s content effectively, use this command. The review interval will be shortened (multiplied by 0.9), giving you another chance to learn it sooner. The note state remains unchanged as an “again” response is considered a failure to recall, preventing a proper judgment of its emotional impact. [r]eroll: If you want to skip the currently displayed note without reviewing it, use this command to request a different note. [q]uit: When you’re finished with your review session, use this command to exit the script. 5. Spacing Algorithm Simplified SM2: The core of the scheduling algorithm is a simplified version of the Anki/SM2 algorithm, widely recognized for its effectiveness in spaced repetition learning. Initial Interval: The default starting interval for new notes is 50 days. Subsequent Intervals: Future review intervals are dynamically calculated based on your review responses (using the ease factor) and the SM2 algorithm. Specifically, the good_interval function calculates the new interval by multiplying the current interval by the ease factor (which is always 300 in this implementation) and dividing by 100. Note Prioritization (Not just due-date based): “Exciting” notes: Notes marked as “exciting” are highly prioritized for review, especially when they become overdue. The more overdue an exciting note is, the more likely it is to be selected for review. This is achieved through a weighted probability selection process in the get_exciting_note function, where the weight is proportional to the square of the number of days the note is overdue. Newly created notes: To reinforce initial learning, newly created notes that have not yet been reviewed receive a probability boost for selection during the 50-100 day period after their creation. This ensures you encounter new notes relatively soon after adding them. This is implemented in the get_recent_unreviewed_note function. Regular reviewed notes: For notes that have been reviewed at least once (and are not marked as “exciting”), the script uses a weighted probability based on overdueness. The more overdue a note is, the higher the chance it will be selected for review. This helps ensure you don’t completely neglect notes even if you skip reviews for a period of time. This is implemented in the get_all_other_note function, similar to how “exciting” notes are prioritized. Ease Factor: The ease factor, a measure of how easily you recall a note, starts at 300% and remains constant throughout the note’s lifecycle in this implementation. “Again” Interval Adjustment: When a note is marked as “again”, the again_interval function is used to calculate the new interval, which is simply the current interval multiplied by 0.9. Benefits Flexibility: Use your preferred text editor and any plain text format or markup language you like for your notes. Control: You decide when and how many notes to review each day – there are no strict daily review quotas. Intelligent Note Selection: The script’s note prioritization logic helps you focus on the most relevant and “exciting” notes, making your review sessions more efficient and engaging. Editor Integration: Seamlessly use your text editor of choice to review and edit notes. (The optional --external-program emacs flag provides even deeper integration with Emacs, allowing automatic navigation to the selected note). Non-Destructive: The script only reads from your inbox files and does not modify them in any way. Your notes remain entirely under your control.