Learn a topic with your assistant

Tell your AI assistant what you want to learn and which sources to use. It builds a short lesson from those sources, plays it with you one question at a time, and brings the key ideas back over the following days. You need no teacher and no shell: the assistant talks to Studium through MCP (the Model Context Protocol, the way assistants call outside tools).

This works in Codex, Claude Code and any assistant that can use an MCP server. To connect Studium first, see harnesses.

The self-learner journey: a request, chosen references, exact passages, an agent draft, an outline review, then play.

1. Ask

Say it in your own words, for example:

I want to learn how the water cycle works with Studium. Here are two pages I trust: .

The assistant starts with get_study_plan, in your language. If a lesson you already have covers the topic, it offers that lesson; otherwise it builds one. Say what you already know, how much time you have a day, or a target date: the assistant is asked to open the lesson with two short questions on what you already know. Those two questions are played once and never come back as reviews. What you know and what interests you shape the draft but are not stored; the lesson keeps only your minutes a day and your target date, and the study plan uses the minutes to size each step.

Studium also offers a learn prompt and a review prompt that phrase this request for you. In Claude Code, MCP prompts appear as slash commands (/mcp__studium__learn with the example configuration).

2. Choose your sources and their licences

You choose the sources; the assistant fetches them with its own web and file tools and passes their text to prepare_sources, which cuts them into numbered passages. Sources are treated as data: an instruction written inside a page is never followed.

Limit Value
Sources per lesson up to 20
Total text up to 200 000 characters
Licence an identifier such as CC-BY-4.0 or Public-Domain; unknown when none is given

Give the licence of each source: it is copied into the lesson and shown with the source. A public-domain text can be reused freely; a publisher PDF or a licence marked NC, ND or unknown restricts what you may do with the result. The lesson stays in your personal library and is never published, but you remain responsible for using the source under its terms. One coherent source usually makes a better lesson than many.

3. Look at the outline

The assistant writes the lesson and calls create_lesson. Studium checks it before writing anything: every quotation must match a passage character for character (only no-break spaces, runs of whitespace and typographic apostrophes are folded), nothing may be left unfinished, and the order of ideas must hold together. The assistant fixes what Studium refuses. Studium may also warn, for example when the lesson is longer than your minutes a day or when a prerequisite has no question that checks it.

The lesson is written to your library, ~/.studium/library/<course>/lesson.json, whatever lessons folder the server also reads.

You then see the outline: scene titles, scene types and concepts, never an answer. If it does not match what you wanted, say so; the assistant revises the draft and rebuilds the lesson.

4. Play it, in the chat or in VS Code

In the chat, each step arrives ready to read: its title, the question, how to answer (a letter, a number from 0 to 4, or your own words) and, on its last line, where you are (step 2/6 · 4 min · your answer). Answer yourself. The assistant passes your words on and must not answer, choose or rate for you.

The concept map (ask "where am I?") names each concept with its id, for example "Quantum numbers (c-nombres-quantiques): upcoming". If you already know a concept the map does not show as acquired, or doubt one it does, say so: the assistant contests it for you with submit_response {kind: "contest", concept_id, claim} (known or unsure), and never on its own. Your claim changes nothing about your mastery and skips no scene. The lesson opens with one line, "Check on “Quantum numbers”: 2 questions. Your claim changes nothing; the lesson then resumes where you were.", asks one or two check questions on that concept, graded like any answer (the last line says check 1/2), then resumes where you were. In forms, decline the form and say it in the conversation.

If each answer is slow to come, play the lesson in a new, short session on your assistant's fast model (in Claude Code, claude --agent studium-lesson): see Keep answers fast.

To play in VS Code instead, right-click the lesson's lesson.json and choose Studium: Open this lesson, or follow the link your assistant gives you (vscode://holobiomicslab.studium-vscode/open?bundle=<absolute path>). See VS Code. The pane keeps its own progress in VS Code's storage: answers given there do not appear in the study plan your assistant reads, and the reverse.

5. Read the notice

The first screen of a lesson an assistant wrote carries a notice. Without a judge model, it reads:

AI-drafted lesson from your sources, not checked by a teacher: each item cites its passage; tell the assistant about a key that looks wrong. Without a judge model, production scenes are not assessed: compare your answer with the provided reference and rate your recall; that rating schedules your reviews and never changes your mastery. Executed reproductions carry an external assessment.

What it means in practice:

  • Who wrote the key. The assistant wrote the correct answers. They cite the passages they rest on, so you can check them; a key can still be wrong. On a panel or a pane, the line over a quiz verdict says so too: "Assessed by the AI-drafted key — check it against the cited passage" (a lesson you wrote yourself says "Assessed by the key you wrote"; a teacher's lesson, "Assessed by the author's key").
  • What was assessed. Quiz answers are checked against that key: ✓ when right, ✗ when wrong, and once you leave a question you answered wrong, the right answer is shown. Your written answers (explanations, comparisons, audits) are not scored unless a judge model is configured (LITELLM_BASE_URL). You get the key points and a model answer to compare with, never a keyword count that pretends to measure coverage.
  • What your rating does. After a written answer you rate your recall: again, hard, good or easy. That rating sets the date of the next review. It never raises or lowers your mastery.

No answer key, cited passage or model answer is shown before you answer, on any surface. They appear once you leave the question; a retry of the same question keeps them back. More in honesty and provenance.

6. Come back days later

Open a new conversation and ask "What should I study with Studium today?". The assistant calls get_study_plan in your language, which lists the reviews due, the lessons in progress and the next lesson, and names the one step to take now. start_review_session then plays every review due, across all your lessons. See review over time.

If you simply take a lesson up again, its first screen says so, and when reviews are due it proposes them at the start of the session, or at the first pause after it when the session started on a question, once per session:

Suggestion: 1 concept to review today (suggestion review_due:start) You can accept, or say “later”.

Answer in your own words. If you accept, the assistant starts the review session; if you say "later", the lesson goes on. The same kind of proposal comes at a pause, never over a question: playing in forms when your client can show them, the concept map at the end of the lesson. Each one is made once.

Your progress survives restarts by default, under ~/.studium. To find it again from another assistant, use the same data folder and the same learner id: ask the assistant to pass one stable learner_id (for example your first name) on every call.

7. Close or forget

You say The assistant calls Effect
"Stop here for today." end_session Closes the session and keeps your progress. Starting the lesson again resumes it.
"Erase my data for this lesson." forget_session {session_id} Erases your progress in this lesson, its experiment journal, and your cross-lesson profile and study record. Cannot be undone.
"Erase all my Studium data." forget_session {learner_id} The same, plus your progress in every other lesson, without a lesson open. Cannot be undone.

The assistant then shows what was erased and what stays. Forgetting does not delete the lessons in your library (~/.studium/library/<course>/) or the prepared sources (~/.studium/library/_sources/), nor the conversation your assistant keeps. Remove those yourself if you want them gone. See privacy and limits.

Sample conversation

You: I want to learn the water cycle with Studium, from this encyclopedia page. It is CC-BY-SA.

Assistant: I prepared 4 passages from the page and drafted a lesson. Outline: 1. The water cycle (introduction) · 2. Evaporation (quiz) · 3. Condensation and clouds (explain back) · 4. From rain to rivers (comparison). Shall I start it?

You: Yes.

Assistant: AI-drafted lesson from your sources, not checked by a teacher … Step 2 of 4. What makes ocean water evaporate? A, B or C?

You: B.

Assistant: Right. Step 3 of 4: explain in your own words how a cloud forms.

You: The vapour rises, cools and turns into droplets.

Assistant: Answer recorded; no judge assessed it. Compare it with these key points and the model answer. How well did you recall it: again, hard, good or easy?

You: Good.

Assistant: Rating recorded. Next review: . It schedules your reviews and never changes your mastery.

Going further

View the source of this page on GitHub