> ## Documentation Index
> Fetch the complete documentation index at: https://docs.evermind.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# AI Tutor
> Build a personalized learning assistant that tracks progress and adapts across study sessions
Build an AI tutor that remembers student progress, surfaces knowledge gaps, and
personalizes each session. EverOS gives the tutor long-term memory that persists
across study sessions, so the second session knows what happened in the first.
## Architecture
* **Episodes** capture what happened: explanations given, quiz results, topics
the student struggled with. Available within seconds of extraction.
* **Profile** captures who the learner is: learning style, pace, goals. Built up
in the background over many sessions.
## Setup
```bash theme={null}
pip install everos-cloud
export EVEROS_API_KEY="your_api_key"
```
```python theme={null}
from everos_cloud import EverOS
client = EverOS() # reads EVEROS_API_KEY
```
## Store tutoring interactions
Each exchange is stored into the student's session. The student's messages carry
their `student_id`; the tutor's use a tutor sender id.
```python theme={null}
def store_exchange(student_id: str, subject: str, student_msg: str, tutor_msg: str):
client.add(
session_id=f"tutor_{subject}_{student_id}",
messages=[
{"sender_id": student_id, "role": "user", "content": student_msg},
{"sender_id": "tutor", "role": "assistant", "content": tutor_msg},
],
)
```
## Record assessments and gaps
Store quiz results and struggles as natural interactions. EverOS extracts them
into searchable episodes. Write **specific, actionable** notes; they retrieve far
better than vague ones.
```python theme={null}
def record_assessment(student_id: str, subject: str, topic: str,
score: int, total: int, notes: str = ""):
pct = round(score / total * 100)
tutor_msg = f"Assessment on {topic}: {score}/{total} ({pct}%). {notes}"
store_exchange(
student_id, subject,
f"I just finished the {topic} assessment.",
tutor_msg,
)
record_assessment("student_emma", "calculus", "derivatives", 7, 10,
"Struggled with chain rule applications.")
```
## Identify knowledge gaps
Search the student's memory for topics they've struggled with, then feed those
into the next session.
```python theme={null}
def knowledge_gaps(student_id: str) -> list[str]:
results = client.search(
"struggled, difficult, needs review, missed concepts, scored low",
user_id=student_id, method="hybrid", top_k=10,
)
return [ep.episode for ep in (results.episodes or [])]
def strengths(student_id: str) -> list[str]:
results = client.search(
"mastered, understood well, high score, excellent",
user_id=student_id, method="hybrid", top_k=10,
)
return [ep.episode for ep in (results.episodes or [])]
```
## Complete adaptive tutor
```python theme={null}
from everos_cloud import EverOS
client = EverOS()
class AITutor:
def __init__(self, subject: str):
self.subject = subject
def _session_id(self, student_id: str) -> str:
return f"tutor_{self.subject}_{student_id}"
def _store(self, student_id: str, student_msg: str, tutor_msg: str):
client.add(
session_id=self._session_id(student_id),
messages=[
{"sender_id": student_id, "role": "user", "content": student_msg},
{"sender_id": "tutor", "role": "assistant", "content": tutor_msg},
],
)
def _context(self, student_id: str, query: str) -> str:
results = client.search(
query, user_id=student_id, method="hybrid",
top_k=6, include_profile=True,
)
parts = [f"[Learner profile] {p.profile_data}" for p in (results.profiles or [])]
parts += [f"[History] {e.episode}" for e in (results.episodes or [])]
return "\n".join(parts) if parts else "New student, no history yet."
def _generate(self, student_message: str, context: str) -> str:
prompt = f"""You are a patient tutor for {self.subject}. Adapt to the
student's demonstrated level and revisit topics they struggled with.
WHAT YOU KNOW ABOUT THE STUDENT:
{context}
STUDENT:
{student_message}"""
# Replace with your LLM call.
return "[Adaptive tutor reply grounded in the student's history]"
def study_session(self, student_id: str, student_message: str) -> str:
context = self._context(student_id, student_message)
reply = self._generate(student_message, context)
self._store(student_id, student_message, reply)
return reply
def record_assessment(self, student_id: str, topic: str,
score: int, total: int, notes: str = ""):
pct = round(score / total * 100)
self._store(
student_id,
f"I just finished the {topic} assessment.",
f"Assessment on {topic}: {score}/{total} ({pct}%). {notes}",
)
tutor = AITutor("calculus")
# Set learning goals. EverOS will consolidate these into the profile over time
tutor.study_session("student_emma",
"My goals: pass the AP exam and really understand derivatives and integrals.")
# A session, then an assessment, then a later session that recalls the struggle
tutor.study_session("student_emma", "I'm having trouble with derivatives — can you explain?")
tutor.record_assessment("student_emma", "basic derivatives", 7, 10,
"Struggled with the chain rule.")
print(tutor.study_session("student_emma", "Can we practice more derivative problems?"))
# The last reply is informed by the recorded chain-rule struggle.
```
## Best practices
```python theme={null}
# Good: specific and searchable
"Scored 85% on integration by parts. Struggled choosing u and dv."
# Weak: too vague to retrieve usefully
"Did okay on the integration quiz."
```
Let EverOS build the learner profile from natural statements rather than
setting fields manually.
```python theme={null}
for pref in [
"I learn better with visual examples.",
"I prefer practicing problems before theory.",
"My goal is to pass the AP Calculus exam.",
]:
client.add(session_id="tutor_calculus_student_emma",
messages=[{"sender_id": "student_emma", "role": "user", "content": pref}])
```
Call `client.flush(session_id)` when a study session ends so the next
session can immediately recall it.
## Next steps
How MemCell, episodes, and profiles work under the hood.
Production patterns for learning applications.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.