LearnGraph

About the project

Inspiration

AI tutors often give generic explanations because they lack a reliable understanding of what a student already knows. Conversation history may show what was discussed, while uploaded notes only show what the student encountered—not what they genuinely understand.

Students also increasingly learn inside general-purpose AI tools instead of dedicated education platforms. We wanted to build a learning-memory layer that could support those existing workflows rather than forcing students into another closed tutoring platform.

LearnGraph gives AI an evolving, queryable model of the learner. It maps concepts and prerequisites, distinguishes claimed knowledge from demonstrated mastery, identifies foundational gaps, and helps an AI explain new material using concepts the student already understands.

What it does

LearnGraph ingests an original collection of linked Markdown notes and transforms them into a personal concept graph.

Concepts initially have a claimed status with no mastery score. Uploading a note is not treated as proof of understanding. Mastery changes only after the learner answers an adaptive flashcard and receives a graded result.

The learning loop is:

Ingest notes and identify concepts.
Build deterministic and GPT-5.6-enriched prerequisite relationships.
Select an adaptive flashcard using mastery, prerequisites, and previous attempts.
Use GPT-5.6 to generate and grade the response.
Classify mistakes and extract evidence from the learner’s own answer.
Update mastery and adapt the next recommendation.
Expose the resulting learner context to AI agents through read-only MCP tools.

The mastery update follows:

New mastery = 0.65 × previous mastery + 0.35 × attempt signal

The attempt signal considers correctness, response time, and error type. Uncertain model judgments receive a smaller update weight, preventing one ambiguous grade from significantly distorting the learner profile.

How we built it

The backend uses FastAPI, Pydantic, SQLAlchemy, and Supabase PostgreSQL. The frontend uses Next.js, React, TypeScript, Tailwind CSS, and react-force-graph-2d.

Our ingestion pipeline combines deterministic Markdown signals—headings, wiki-links, and tags—with optional GPT-5.6 structured enrichment. Relationships retain their origin, confidence, and uncertainty so model-generated edges are never silently presented as unquestionable facts.

GPT-5.6 powers four runtime capabilities:

Structured concept extraction
Prerequisite-edge proposals
Adaptive flashcard generation
Evidence-grounded answer grading

LearnGraph also exposes four focused, read-only MCP tools:

get_learner_context
get_mastery_summary
find_gaps
get_concept

We demonstrated GPT-5.6 invoking these tools through the OpenAI Responses API over a Cloudflare tunnel. The model retrieved live mastery scores and prerequisite gaps that were not included in the user’s prompt.

Codex was our engineering partner throughout the project. We used it to implement and verify the schema, ingestion pipeline, graph traversal, mastery engine, learning loop, MCP server, web interface, tests, and review fixes. Substantial Codex tasks were recorded against their implementation commits to maintain an auditable development history.

Challenges we faced

The hardest conceptual challenge was separating exposure from understanding. Treating every uploaded concept as mastered would make the graph confidently wrong. We addressed this by introducing a pre-evidence claimed state and allowing only graded attempts to establish mastery.

Graph construction created another trust problem. LLM-generated prerequisite relationships can be useful but may be uncertain. We combined deterministic construction with validated GPT-5.6 output, confidence metadata, bounded retries, and explicit uncertainty handling.

Grading also needed safeguards. We required structured output, error classification, and a verbatim evidence quote from the learner’s response. Uncertain grades are damped to prevent unstable mastery changes.

Finally, connecting a local MCP server to a remotely hosted model required a public streaming endpoint. We used FastMCP with Streamable HTTP and Cloudflare Tunnel, then verified the complete GPT-5.6 → MCP → LearnGraph → Supabase path through live learner data.

What we learned

We learned that personalization requires more than retrieval. An effective AI tutor needs structured knowledge dependencies, evidence-backed mastery, and clear boundaries around what the model may change.

We also learned that MCP is a powerful separation layer: the graph and mastery system remain independent of any particular model interface, while compatible AI clients can query the same trusted learner state.

Most importantly, trustworthy educational AI should know the difference between “the student has seen this” and “the student has demonstrated this.”