Vellum

Inspiration

I kept noticing the same problem in my own studying: every planner app tracks what you plan to study, but none of them track what actually happens — whether I finished it, struggled with it, or skipped it entirely. And when I got a question wrong, no app ever told me why. I'd just see "incorrect" and move on, making the same mistake again a week later.

I wanted to build something that treats studying the way a good tutor would — someone who remembers your actual patterns, tests what you really know instead of what you think you know, and tells you exactly what to fix next.

What it does

Vellum is an AI study agent built around one loop: study → test → diagnose → understand → predict → recommend → study again.

• Adaptive daily planning that reasons over your actual history, not just a fixed schedule
• Retention Forecast — a real spaced-repetition decay model, not a guess:

$$\text{retention}(t) = \text{start} \times e^{-t/\text{stability}}$$

where start reflects how well your last review or quiz went, and stability grows the more you've reviewed a topic

• Topic Dependency Map — the AI infers prerequisite structure between topics (e.g. Equations of Motion depends on Acceleration) and uses it to catch root causes, not just symptoms
• Concept Autopsy — when you get a quiz question wrong, it diagnoses why: a formula mix-up, a genuine misunderstanding, or a careless slip
• Ghost Knowledge Detection — compares your quiz score (recognition) against your Teach It Back score (recall) to catch the gap between recognizing an answer and actually understanding it
• Photo-to-flashcards — take a picture of your handwritten notes, and Vellum reads the entire page and generates as many flashcards as the content actually needs
• Exam Readiness Meter and a Recommended Action card that ties everything together into one clear next step
• What-If Simulator and a Minimum Study Optimizer for time-boxed, highest-impact study sessions
• A lightweight shared Study Room and simulated study pod for peer accountability

How I built it

I started small and deliberately kept the first version simple — a single adaptive planner with memory — before layering in the diagnostic and predictive systems one at a time, so each piece stayed genuinely functional instead of decorative. Every AI-powered feature calls a real language model for reasoning (planning, diagnosis, grading explanations), while the retention math, readiness scoring, and study-time optimization run on real formulas underneath, not just prompts pretending to compute something.

Originally the prototype ran inside a sandboxed AI chat environment. To make it something anyone could actually open and use — no login required — I rebuilt it as a standalone deployment: a static front end, a small serverless backend function that safely holds the API key server-side, and free-tier hosting with persistent storage for both personal progress and the shared Study Room.

Challenges I ran into

• Getting real deployment working without a budget. I don't have a card of my own, so I had to find a genuinely free AI API tier and route the whole app through it instead.
• A subtle retention bug. My first version of the decay formula only accounted for time since review, not the quality of that review — so a bad quiz score didn't lower retention immediately, only its future decay rate. Scoring 1 out of 5 on a quiz still showed high retention, which was clearly wrong. Fixing it meant rethinking what "evidence of learning" should actually mean in the model.
• Model and API changes mid-build. The model I initially used got deprecated for new users partway through, and a newer model's internal "thinking" step was silently eating the entire output budget, truncating every AI response before it could finish. Both took real debugging — reading raw API error messages, not just guessing — to track down.
• Learning deployment from zero. GitHub, environment variables, serverless functions — I'd never touched any of it before this project. Getting comfortable with that pipeline, including a few honest mistakes along the way (uploading the wrong file into the wrong place more than once), was its own real learning curve.

What I learned

That a good idea and a working product are separated by a lot of unglamorous debugging — and that reading the actual error message, instead of guessing, is almost always faster than it feels. Mostly, I learned that scope discipline matters: the strongest version of this project came from picking one sharp, connected loop and building it properly, rather than trying to build everything I could imagine all at once.

Accomplishments that we're proud of

• Getting a genuinely working, no-login, publicly deployable AI product live — not just a demo that only runs inside a chat sandbox
• Building AI features that actually connect to each other: a quiz result feeds retention, retention feeds the recommended action, a weak prerequisite gets flagged on the dependency map — it behaves like one system, not eight separate tools bolted together
• Catching and fixing a real logic bug in the retention formula by questioning a number that looked wrong instead of accepting it
• Debugging a full deployment pipeline — GitHub, environment variables, serverless functions, a live third-party API — completely from scratch
• Shipping the photo-to-flashcards feature, which reads an entire page of real handwritten notes and generates however many flashcards the content actually needs, not a fixed number

What's next for Vellum

• Real accounts and cross-device sync, so progress isn't tied to a single browser
• Real peer matching instead of a simulated study pod, so the social layer is genuinely collaborative
• A deeper Learning DNA profile built from real, evidence-backed usage patterns over time — not a one-time quiz, but something that sharpens the longer you use it
• An Academic Early Warning system that detects declining study patterns early enough to actually help
• Native mobile app, so features like focus timers and reminders can work at the device level, not just inside the browser

Built With

• css3
• gemini-api
• generative-ai
• github
• google-gemini
• html5
• javascript
• netlify
• netlify-functions