How Graspful Works
Graspful is an adaptive learning engine. You define content as YAML. The engine handles diagnostics, mastery tracking, spaced repetition, task selection, and gamification. This page is the one-page overview of the entire system.
1. Knowledge Graph
Every course is a directed acyclic graph (DAG) of concepts. Each concept represents one teachable idea that can be tested independently. Concepts are connected by two types of edges: prerequisite edges ("you must master A before starting B") and encompassing edges ("practicing B implicitly exercises A"). Prerequisite edges enforce ordering. Encompassing edges let the spaced repetition engine give implicit review credit when a student practices advanced material that exercises foundational skills. Together, these edges turn a flat list of topics into a structured learning path.
2. Adaptive Diagnostics
When a student starts a course, a diagnostic session maps what they already know in 20-60 questions. The engine uses Bayesian Knowledge Tracing (BKT) to maintain a probability estimate of mastery for every concept. It selects questions using MEPE (Maximum Expected Posterior Entropy) — always asking the question whose answer would reduce uncertainty the most. The session stops when the information gain per question drops below a threshold, so strong students finish fast and weaker students get a more thorough assessment. The result is a complete mastery map: every concept is marked as mastered, in progress, or unstarted.
Glossary: Diagnostic Session · Glossary: BKT · Glossary: MEPE
3. Mastery-Based Progression
Graspful never advances a student to a new concept until all its prerequisites are mastered. The set of concepts a student can work on at any moment is called the knowledge frontier: the unmastered concepts whose prerequisites are all mastered. This guarantees students always have the foundation they need. If a student gets stuck (two or more consecutive failures), the engine detects a plateau and automatically identifies the weak prerequisite causing the block. It then assigns remediation — targeted practice on that prerequisite — before returning the student to the original concept.
Glossary: Knowledge Frontier · Glossary: Plateau Detection · Glossary: Remediation
4. The Learning Staircase
Each concept is broken into 2-4 knowledge points (KPs) that form a progressive staircase. KP1 is recognition: can you identify the concept? KP2 is guided application: can you use it with support? KP3 is transfer: can you apply it to a novel scenario? Each KP has its own instruction text, worked example, and practice problems. Students climb one step at a time, and the engine only advances to the next KP after mastery of the current one (two consecutive correct answers). This staircase structure prevents the common problem of presenting complex material before the student is ready for it.
5. Spaced Repetition
Once a concept is mastered, the engine schedules reviews using the FIRe algorithm (Fractional Implicit Repetition). FIRe is a spaced repetition system with a twist: it grants implicit review credit through encompassing edges. If a student practices "closures" and "closures" has an encompassing edge to "variables" with weight 0.7, then "variables" gets 70% of a repetition credited automatically. This means students review foundational concepts for free while working on advanced ones, reducing the total review burden. Each concept tracks a memory value (P(Learned), 0-1) that decays over time, and a repetition number that determines the next review interval.
Glossary: FIRe · Glossary: Encompassing Edge · Glossary: Memory
6. Intelligent Task Selection
Every time a student opens a session, the engine decides what to do next. It uses a priority-based system: (1) remediation tasks for blocked students come first, (2) overdue spaced repetition reviews come second, (3) new learning on the knowledge frontier comes third. Within each category, tasks are ranked by urgency — the most overdue review or the highest-priority frontier concept wins. The student never has to decide what to study. They just press "next" and the engine serves the optimal task.
7. Gamification
Consistent engagement is what separates students who finish from those who drop off. Graspful drives engagement with three mechanics: XP (experience points calibrated to ~1 XP per minute of study), streaks (consecutive days of practice), and leaderboards (weekly and all-time rankings per course). XP is earned for completing practice problems, finishing KPs, passing section exams, and completing reviews. The calibration is deliberate: students can estimate their study time by looking at their XP total.
The Two-YAML Workflow
Every Graspful product is defined by two files. A course YAML defines the knowledge graph, concepts, knowledge points, and practice problems. A brand YAML configures the product: theme, landing page copy, pricing, SEO, and custom domain. Import both, and you have a live white-label learning product with adaptive diagnostics, spaced repetition, and Stripe billing. No code required.
# 1. Create and import the course
graspful create course --topic "JavaScript Fundamentals" -o js-course.yaml
graspful import js-course.yaml --org my-org --publish
# 2. Create and import the brand
graspful create brand --name "JS Mastery" --domain js.graspful.com -o js-brand.yaml
graspful import js-brand.yamlSee the full schemas: Course Schema · Brand Schema
Architecture
The backend is built with NestJS and follows Domain-Driven Design with seven bounded contexts: Knowledge Graph, Student Model, Diagnostic, Learning Engine, Assessment, Spaced Repetition, and Gamification. Each context owns its domain logic and database queries. The frontend is Next.js with Tailwind CSS and shadcn/ui. Authentication is handled by Supabase Auth. The monorepo is managed with Turborepo and bun.
For AI agents: The system exposes two integration surfaces — a CLI (@graspful/cli) and an MCP server. Both accept YAML as input and return structured JSON. The fastest path to creating a course is: create → fill → review → import.