-
-
Intro
-
First Impression
-
Knowledge map from chat
-
Reasoning Route from chat
-
Quizzes Section
-
Study Plan Section
-
Knowledge Map Section
Inspiration
Most AI tutors are very good at giving answers, but that can easily turn learning into copying. I wanted to build something that helps students reach the answer themselves.
That became SocraticMap: an adaptive AI learning platform built around Socratic tutoring, where AI uses questions, hints, targeted explanations, and learner evidence instead of immediately revealing the solution.
The key idea is simple: the tutor should not only understand the problem, but also maintain a model of what the learner has actually demonstrated so far.
What it does
SocraticMap analyzes the learner's task, identifies the main concepts and learning objective, and then guides the learner Socratically.
Depending on the response, it can ask a question, provide a hint, scaffold the next step, correct a misconception, or explain a missing concept.
At the same time, it maintains a live Knowledge Map that updates from evidence in the learner's own reasoning. The system also maintains a global Knowledge Map across sessions, so concepts can accumulate evidence over time instead of each conversation being isolated.
Concepts can progress through states such as:
- To study
- Seen
- Emerging / Developing
- Strong / Mastered
SocraticMap also includes a Study Plan for organizing subjects, exams, assignments, deadlines and study sessions, plus AI-generated quizzes and practice activities connected to the learner's recent progress.
It supports multimodal interaction through text, screenshots, images and voice input with AI speech-to-text.
How I built it
SocraticMap is built with Next.js, React, TypeScript, Firebase and the Google Gemini API.
The main AI architecture separates conversational tutoring from learner-state evaluation.
A tutoring turn roughly follows this flow:
React UI
↓
Next.js API
↓
Gemini streaming response
↓
Structured learner-state analysis
↓
Signed session update
↓
Knowledge Map
The first Gemini call focuses on generating the Socratic response and streams the result to the browser as it is produced.
A second, smaller structured call evaluates what changed in the learner model and returns only the relevant concept updates, instead of regenerating the entire state.
The structured output can include:
- current learning objective
- target concept
- concept mastery
- confidence
- learner evidence
- completion state
- reason for the next tutoring intervention
This separation is important because the tutor can internally understand much more than it should immediately reveal. The model's knowledge is used to decide how to teach, rather than simply to output the answer.
State-Augmented Generation and learner memory
SocraticMap does not use a traditional RAG pipeline with embeddings and vector search.
Instead, it uses a state-augmented generation architecture.
Rather than retrieving semantically similar text chunks, the system retrieves structured learner state such as:
- mastery
- confidence
- learner evidence
- current learning objective
- previous concept observations
- Study Plan context
- recent quiz performance
That relevant state is then injected into later Gemini calls.
The global Knowledge Map therefore acts as a form of structured long-term memory.
Socratic sessions
│
▼
Learner responses
│
▼
Evidence extraction
│
▼
Concept-level observations
┌─────────┼─────────┐
▼ ▼ ▼
Mastery Confidence Evidence
└─────────┼─────────┘
▼
Global Knowledge Map
│
┌───────┴────────┐
▼ ▼
Study Plan Quiz performance
│ │
└───────┬────────┘
▼
Relevant learner state
│
▼
Compact Gemini context
│
▼
Adaptive tutoring / practice
This is different from conventional RAG because the important question is not "Which old text is similar to this prompt?" but rather "What has this learner already demonstrated about this concept?"
That makes the memory system more directly useful for education.
Evidence-based learner modeling
A central rule in SocraticMap is:
Tutor output is not learner evidence.
If the AI explains a concept correctly, that does not mean the student understands it.
The Knowledge Map therefore updates from evidence found in the learner's own reasoning. The system tracks concept-level signals such as mastery, confidence and supporting evidence.
This creates a lightweight form of student modeling using structured LLM inference, persistent state and deterministic application logic.
Context and token optimization
SocraticMap does not resend an unlimited conversation history on every AI request.
Instead, Gemini receives a compact context containing the original task, current objective, relevant concept state, recent messages and current attachments.
This helps reduce:
- token usage
- unnecessary repeated context
- latency
- inference cost
Gemini 3.7 → Gemini 3.1 Flash-Lite
One of the biggest technical changes during development was moving from Gemini 3.7 to Gemini 3.1 Flash-Lite.
This was an intentional optimization.
SocraticMap performs multiple AI operations during an interactive session, so latency and API efficiency became just as important as raw reasoning capability.
Instead of relying on a larger model for every operation, more intelligence was moved into the surrounding architecture:
- structured schemas
- compact context
- persistent learner state
- evidence aggregation
- smaller specialized AI calls
- deterministic state-management logic
- streaming generation
In other words, the optimization shifted complexity from model size into system design.
Voice input and speech-to-text
SocraticMap also supports voice input directly inside the chat.
The flow is:
Microphone
↓
Browser MediaRecorder
↓
/api/transcribe
↓
Gemini multimodal transcription
↓
Transcript
↓
Chat composer
This makes the tutoring experience more accessible and closer to a natural conversation.
AI-generated practice
The quiz system also uses structured Gemini outputs.
Instead of asking the model for arbitrary text, SocraticMap provides a schema describing the expected structure of each exercise.
The generated practice can include question type, prompt, answer options, expected answer, explanation, hint and concept relationships.
Quiz generation can also use learner evidence, Study Plan information and recent quiz performance, so practice is connected to the same learner model.
Persistent state
For signed-in users, Firebase Authentication and Firestore are used to persist learner information and the global Knowledge Map.
Important pedagogical session state is also signed server-side so it cannot simply be modified in the browser before the next tutoring turn.
Challenges
One of the hardest challenges was making the system work across very different types of learning.
A mathematics problem may follow a clear reasoning sequence, while a biology concept such as natural selection requires a completely different conceptual route.
The system therefore had to generate task-specific concepts and tutoring decisions instead of relying on generic steps.
Another major challenge was deciding what counts as real understanding.
The AI explaining something is not evidence that the learner understands it, so I had to separate tutor output from learner evidence.
Performance was also a major challenge. Moving from Gemini 3.7 to Gemini 3.1 Flash-Lite required improving context management, structured outputs, persistent state and smaller AI calls so the application remained responsive.
Finally, maintaining a long-term learner model required merging evidence from multiple sessions without turning the Knowledge Map into a copy of the full chat history. The final design stores compact concept observations and aggregates them over time.
What I learned
The biggest lesson was that building an AI tutor is very different from building an AI chatbot.
A useful tutoring system needs more than a convincing response. It needs a representation of the task, a model of the learner, explicit evidence of understanding, persistent state and a strategy for deciding what should happen next.
I also learned that AI architecture is much broader than model selection.
A large part of SocraticMap's behavior comes from the system surrounding Gemini: structured outputs, context engineering, learner modeling, persistent memory, knowledge graphs, evidence aggregation and deterministic state logic.
Using a larger model for every operation is not necessarily the best solution. Combining a faster model with better architecture can produce a more responsive and practical product.
I also learned that traditional RAG is not the right solution for every memory problem.
For SocraticMap, retrieving structured information about what the learner understands is more useful than retrieving semantically similar old text.
What's next
The next step is to continue developing the learner model across longer periods of time so students can build a richer Knowledge Map across subjects, courses and academic years.
I also want to build a dedicated Android application so SocraticMap is easier to access from a phone.
Another major goal is external calendar integration. Study sessions, exams, assignments and deadlines could synchronize with Google Calendar and, on Apple devices, Apple Calendar.
Future versions could also include teacher-facing analytics for recurring misconceptions and learning gaps, as well as better recommendations based on the global Knowledge Map.
The long-term goal is to make SocraticMap more than an AI chat interface.
Make AI less of an answer machine and more of a system that helps students learn how to reason for themselves.
Demo video
The project demo video was edited using Microsoft Clipchamp.
Log in or sign up for Devpost to join the conversation.