VaultRecall

VaultRecall is a local-first active recall web app for Obsidian and Markdown vaults.

Point it at a folder of .md files, scan the vault, run study sessions from extracted recall prompts, rate your answers, schedule future reviews, and write session logs back into the vault.

Why

Obsidian is excellent for building a knowledge base, but browsing notes is not the same thing as learning. VaultRecall turns your notes into an active recall workflow without requiring Anki, cloud accounts, or a proprietary format.

Current version

VaultRecall now supports local recall plus optional AI-assisted question generation and answer grading.

Current features:

• Local vault path input
• Markdown/Obsidian vault scanning
• Frontmatter, tags, headings, and wikilink parsing
• Recall prompt extraction from ## Recall prompts sections
• Study sessions from:
  • due reviews
  • weak areas
  • all questions
  • specific folders
• Self-grading with Again, Hard, Good, Easy
• Optional OpenAI-powered question generation from arbitrary notes
• Approval/edit/discard flow for generated questions
• Optional OpenAI-powered answer grading with suggested rating
• Lightweight spaced repetition scheduling
• Local state stored in the vault under .vaultrecall/state.json
• Markdown session logs written to VaultRecall/Sessions/YYYY-MM-DD.md
• Clean local web UI

Vault compatibility

VaultRecall works with any local folder of Markdown files, including normal Obsidian vaults.

For v0.1, the important distinction is:

• VaultRecall can scan and index any Markdown/Obsidian vault.
• VaultRecall can quiz you automatically when it finds explicit recall prompts in your notes.
• VaultRecall can generate draft questions from arbitrary prose if you connect an OpenAI API key.
• Generated questions are stored in VaultRecall app state by default, not written into your Markdown notes.

This app was first built against an Obsidian-style Markdown vault called KnowledgeBank, but it is designed to remain generic.

Recommended note structure

VaultRecall works best when each concept note has a predictable structure. You do not need to use this exact format, but the closer your notes are to it, the more useful the app becomes.

---
type: concept
tags: [ai, rag]
---

# RAG

## One-line definition
Retrieval-augmented generation lets an LLM answer using retrieved external context.

## Why it matters
RAG helps keep answers grounded, current, and inspectable without retraining the model.

## Core ideas
- Index useful source material.
- Retrieve relevant chunks at query time.
- Give retrieved context to the model.
- Evaluate both retrieval quality and answer quality.

## Related notes
- [[Embeddings]]
- [[Evaluation]]
- [[Inference and Serving]]

## Recall prompts
- Q: What problem does RAG solve?
  A: It lets an LLM answer using retrieved external context instead of relying only on model weights.
- Q: When would you prefer fine-tuning over RAG?
  A: When you need behavioural/style adaptation or task-specific patterns rather than factual retrieval.

Minimum useful structure

If you only do one thing, add this section to notes you want to study:

## Recall prompts
- Q: Your question here?
  A: Your expected answer here.

Recommended conventions

• Use one Markdown file per concept, paper, or topic.
• Use clear note titles, e.g. RAG.md, System Design.md, Attention Is All You Need.md.
• Use Obsidian wikilinks for related ideas: [[Embeddings]], [[Evaluation]].
• Put recall prompts under a heading named exactly ## Recall prompts.
• Use Q: for questions and A: for answers.
• Keep answers short enough to review quickly, but specific enough to be useful.
• Prefer practical prompts over trivia.

Good prompt:

- Q: A RAG system returns plausible but wrong answers. What are three likely failure points?
  A: Retrieval may be missing relevant chunks, ranking may be poor, or the generation step may be ignoring/overtrusting context.

Less useful prompt:

- Q: What is RAG?
  A: Retrieval-augmented generation.

FAQ

Can VaultRecall do active recall on any Obsidian vault?

Yes, if the vault is local and made of Markdown files. VaultRecall can scan the notes, folders, frontmatter, tags, headings, and wikilinks.

Without AI, it needs explicit ## Recall prompts sections to create quiz questions. With an OpenAI API key connected, it can generate draft questions from ordinary notes and let you approve/edit/discard them.

Does my vault need to be created in Obsidian?

No. Any folder of .md files can work. Obsidian compatibility is useful because wikilinks, folders, and note-per-concept conventions make the vault easier to study.

Will VaultRecall modify my notes?

VaultRecall does not rewrite your existing notes by default. Generated questions are stored in app state unless a future write-back feature is explicitly added/enabled. It writes local state to:

.vaultrecall/state.json

And it writes session logs to:

VaultRecall/Sessions/YYYY-MM-DD.md

Does VaultRecall use AI?

Only if you configure an OpenAI API key and click an AI action. Scanning, self-review, scheduling, and ordinary recall sessions work locally without AI.

Can it generate questions from notes that do not already have recall prompts?

Yes. Connect an OpenAI API key, choose a note, generate draft questions, then approve/edit/discard them. Approved generated questions are stored in .vaultrecall/state.json by default.

Should I commit .vaultrecall/state.json to Git?

Usually no. That file is personal review history. If you use Git, consider adding .vaultrecall/ to your vault's .gitignore unless you intentionally want to sync review state across machines.

Getting started

Prerequisites

• Node.js 20+
• npm
• An Obsidian or Markdown vault

Install

git clone https://github.com/Prawal-Sharma/VaultRecall.git
cd VaultRecall
npm install

Run locally

npm run dev

Open:

http://localhost:3000

Enter the absolute path to your vault, for example:

/Users/you/Documents/KnowledgeBank

Then click Scan vault.

How to use it

1. Scan your vault.
2. Check the dashboard counts.
3. Start with Due reviews if you have history, or All questions for a new vault.
4. Answer the question before revealing the expected answer.
5. Reveal the answer, or optionally click Grade with AI.
6. Rate yourself, or accept the AI-suggested rating:
   • Again — I missed it.
   • Hard — I barely got it.
   • Good — I got it.
   • Easy — I knew it cold.
7. VaultRecall schedules the next review.
8. At the end of a session, a Markdown log is written back into your vault.

Data and privacy

VaultRecall is local-first.

• It reads Markdown files from the vault path you provide.
• It writes review state to .vaultrecall/state.json inside your vault.
• It writes session logs to VaultRecall/Sessions/ inside your vault.
• It sends note content to OpenAI only when you explicitly use AI generation or AI grading.
• API settings are stored in local vault state for now; do not commit .vaultrecall/state.json if it contains private keys.
• It has no accounts, cloud sync, or telemetry.

Project structure

app/                  Next.js app and API routes
lib/vault/            Markdown vault scanner
lib/recall/           Study session selection
lib/store/            Local vault state and session logs
app/globals.css       UI styling

Roadmap / next TODOs

v0.2

• Better recall prompt parser for more Markdown styles
• Session history dashboard
• Better weak-area analytics
• Search/filter notes and questions
• Export/import review state
• Safer handling for very large vaults

v0.3

• Optional AI grading for free-text answers
• AI-generated questions from notes
• Provider abstraction: OpenAI, Anthropic, Ollama
• Study paths based on Obsidian MOCs / linked notes
• Better Obsidian write-back reports

v0.4

• Local graph view of note/question relationships
• Project/checkpoint mode
• Multi-vault support
• Desktop packaging with Tauri or Electron

Design principles

• Markdown stays the source of truth.
• The app should help you study, not trap your data.
• No mandatory cloud service.
• No Anki dependency.
• Obsidian compatibility matters.
• Active recall beats passive browsing.

License

MIT