VaultRecall Spaced Repetition

Beta spaced repetition built into Obsidian desktop. Review your notes on a schedule using SM-2 and optionally generate AI quizzes from note content. Notes stay untouched: scheduling data lives in the plugin's internal .obsidian/plugins/vaultrecall/data.json.

Beta notice: VaultRecall is in beta. Errors may occur, especially with large vaults, sync conflicts, unusual Markdown, or AI provider responses. Back up your vault before relying on it for important review history. Please report bugs on GitHub Issues, ideally with diagnostics from VaultRecall Spaced Repetition: Copy diagnostics.

Installation

Once approved, install it from Settings → Community plugins → Browse by searching for VaultRecall. Until then, download main.js, manifest.json, and styles.css from the latest GitHub release into .obsidian/plugins/vaultrecall/ in your vault, then enable the plugin.

Usage

Starting a session

Right-click any folder in the file explorer and choose Start review session or Start AI quiz session. Right-click a single Markdown note and choose Start AI quiz on this note to quiz yourself on just that file. You can also click the graduation-cap ribbon icon to start a session in your configured default folder, or use the command palette.

Navigate mode

Notes open one at a time in reading mode (so keyboard shortcuts don't accidentally type into your content). A bar at the bottom shows your progress and the current note name.

Rate each note after reading it:

Key	Rating
1	Again - forgotten, reschedule to tomorrow
2	Hard - interval grows slowly (x1.2)
3	Good
4	Easy
u	Undo last rating
Esc	End session (asks for confirmation)

Rating keys are disabled while a modal (quiz or confirmation) is open. In AI quiz mode, the same 1-4 keys rate the note directly from the quiz modal once questions have loaded.

Notes without an internal review record are treated as new. Each session includes due cards up to your daily due review limit plus up to your configured new-card limit.

AI quiz mode

Same as navigate mode, but after each note opens, a modal generates questions from the note's content. Rate the note directly from the modal once you're done. Requires an API key in settings (see below).

The first time you use AI quiz mode, VaultRecall asks you to confirm plaintext key storage and note-excerpt sharing. It also asks you to confirm the destination host. Non-local API URLs must use HTTPS. HTTP is allowed only for localhost-style development endpoints such as local Ollama.

Status bar and statistics

The status bar shows how many notes are due and new in your default folder. Run VaultRecall Spaced Repetition: Show statistics from the command palette to see today's reviewed count.

Settings

Setting	Description
Default folder	Folder used by the ribbon icon and status bar
Review order	Due-date first or random
Daily due review limit	Max due cards per session (0 = no limit)
New cards per session	Max unseen notes introduced per session
Leech threshold	Notes that fail this many times trigger a warning (0 = off)
API key	Your OpenAI-compatible key
API base URL	Chat completions endpoint
Model	Model name sent to the API
Custom quiz prompt	Replaces the default quiz instructions

VaultRecall is currently desktop-only. Mobile support needs separate QA for the review HUD, modals, and provider networking before it should be enabled.

Review data and backups

Review history is stored in .obsidian/plugins/vaultrecall/data.json, keyed by each note's vault-relative path. Include that file in vault syncs and backups if you want scheduling history preserved.

This also means review history does not travel with a single Markdown note. If you copy one note to another vault, its content moves but its spaced repetition state does not.

If you review on multiple devices while offline, whichever synced data.json wins last may overwrite the other device's recent scheduling changes. Sync that file carefully if you review from more than one machine.

If you used an older version that stored review fields in YAML frontmatter, run VaultRecall Spaced Repetition: Import legacy frontmatter review data from the command palette once. The importer copies existing review state into data.json and does not edit your notes.

After importing, you can run VaultRecall Spaced Repetition: Remove legacy frontmatter review data to strip sr-due, sr-interval, sr-ease, and sr-lapses from notes. This command asks for confirmation before editing files.

Renaming files or folders while the plugin is enabled updates internal review records. Deleting files does not immediately delete review history; this avoids permanent data loss from transient sync deletes. Use VaultRecall Spaced Repetition: Show orphaned review records to inspect stale records and VaultRecall Spaced Repetition: Prune orphaned review records to remove them from data.json.

API key security

Keys are stored in plaintext at .obsidian/plugins/vaultrecall/data.json. This is how Obsidian plugin storage works - there's no encrypted keychain. A few things to keep in mind:

• Set a spending cap on the key you use here
• If your vault syncs to a shared location or cloud storage, be aware that data.json goes with it
• The key, model name, quiz prompt, and note excerpts are sent only to the endpoint you configure and confirm
• Changing the endpoint clears the trust confirmation and asks again before sending data
• AI quiz output is displayed as inert text after HTML, embeds, Markdown links, and wiki links are stripped

The plugin uses Obsidian's built-in requestUrl for API calls, which means requests go directly from your machine to your endpoint with no intermediary.

Run VaultRecall Spaced Repetition: Copy diagnostics when reporting an issue. It copies plugin/app versions, non-secret settings, review-record counts, and default-folder scan counts. It never includes your API key or note content.

Permissions and privacy

VaultRecall runs locally and makes no network requests except AI quiz calls to the endpoint you configure. The Obsidian review scanner flags two capabilities; here is exactly how they are used:

• Vault enumeration. The review queue, status bar, and statistics list Markdown files only inside your chosen review folder. The whole vault is enumerated only when you run Import legacy frontmatter review data or Remove legacy frontmatter review data, which need to find every note with sr-* frontmatter. File paths never leave your device.
• Clipboard. The plugin only writes to the clipboard, and only when you run Copy diagnostics. It never reads the clipboard. The diagnostics contain no API key or note content.

Verifying releases

Release assets are built by GitHub Actions and carry artifact attestations. To verify a downloaded file was built from this repository:

gh attestation verify main.js --repo chrisnmorrison/vaultrecall-sr

Contributing

Bug reports and pull requests are welcome. Please report beta issues at github.com/chrisnmorrison/vaultrecall-sr/issues. The source is plain TypeScript with no runtime dependencies beyond the Obsidian API.

npm install
npm run dev     # watch mode, rebuilds on save
npm run build   # type-check + production build
npm run lint

Copy main.js, styles.css, and manifest.json into your vault's plugin folder to test. After each rebuild, use Reload app without saving in Obsidian to pick up changes.

License

0-BSD

Releasing (maintainers)

Releases are automated by .github/workflows/release.yml. To publish a new version:

1. Add a ## [x.y.z] section to CHANGELOG.md.
2. Run npm version patch (or minor / major). This updates package.json, manifest.json, and versions.json together and creates a local commit and tag.
3. Push the commit: git push (the local tag is not needed; the workflow creates it).

On every push to main, the workflow checks whether a GitHub Release exists for the version in manifest.json. If not, it verifies that package.json, manifest.json, and versions.json agree, builds, lints, tests, and publishes a release named after the version with main.js, manifest.json, and styles.css attached.