One Brain, Eight Learning Modes — What You Switch Is Just the Goal

DeepTutor's core design: chatting, solving problems, generating questions, researching, visualizing, and mastery practice all run on the same agent loop. What you switch is what you want to do this turn — the underlying engine and context stay the same the whole time.

Official system architecture diagram: the feature panels on top share the underlying agent runtime and shared context. Image from the official HKUDS repo.

How Chat Becomes a Full Tutoring Session: It Thinks First, and Asks You Back When Unsure

Chat is the default entry point, where most work begins. A single conversation thread can hold a normal chat, call tools, "ground" its answers against a selected knowledge base, read attachments, generate images, consult other agents, write to a notebook, and carry the same context across many turns.

Official Chat agent loop diagram: think, act, observe, until an answer is reached; ask_user hands control back to you whenever it's unsure. Image from the official HKUDS repo.

Toggleable tools include brainstorm, web_search, paper_search, reason (deep reasoning), and geogebra_analysis (math plotting analysis); once a generation model is configured, imagegen and videogen are also available. Chat is also the jumping-off point into its other capabilities: Quiz (question generation), Research (cited reports), Visualize (chart animations), Solve (detailed reasoning), and Mastery Path (study planning) all branch off from here.

What It Remembers, What It Forgets: Two Clearly Separated Kinds of Context

How It Gets to Know You So Well: Every Layer of Memory Is Clickable

DeepTutor's personalization doesn't rely on some vector database hidden in the backend — it's a three-layer memory system backed by files, one you can read, edit, and audit. Because every conclusion at one layer cites evidence from the layer below it, any line in your profile can be clicked all the way back to the original event. The diagram below is clickable: click a layer to see what it actually stores, and where it came from.

The official docs split this memory into three layers: L1 is a workspace mirror plus an append-only event trace; L2 is the curated facts from each panel; L3 is the cross-panel synthesis. Because L2 cites L1 and L3 cites L2, anything in your profile can be traced back through the chain to its source. The product's Memory Graph draws out the whole pyramid: L3 synthesis at the center, L2 in the middle ring, and L1 traces on the outer ring.

Memory overview: readable, organizable, auditable.

Three-layer memory graph: any conclusion can be traced back to the original event.

Both images above are from the official HKUDS repo.

Companionship, Writing, Book-Making, Research: the Remaining Modules in One Pass

The modules below are secondary but genuinely useful. They all run on the same brain — covered briefly here, each with an official screenshot.

Partners: A Persistent Companion With a Persona and a Phone Number

Partners are persistent companions with their own personas, model strategies, resource libraries, memory, and channels. Every message coming in from the web or an IM platform becomes a normal conversation turn in that partner's dedicated workspace. The channel layer is config-driven, connecting to 15 entry points including Feishu, Telegram, Slack, Discord, DingTalk, WeCom, WhatsApp, and Teams. A partner can also be consulted as a sub-agent from a regular chat — that's "My Agents": you can connect live to a local Claude Code or Codex instance, or import your existing conversation history into a searchable, resumable, named agent.

Partners workspace overview. Image from the official HKUDS repo.

Click to see the Partners architecture diagram

Partners architecture: inbound messages are uniformly converted into conversation turns in the partner's workspace. Image from the official HKUDS repo.

Co-Writer: Select a Passage and Let It Rewrite — Nothing Lands Until You Approve

A split-pane Markdown writing space with live rendered preview (including math formulas and charts). Its core is "surgical editing": select a passage and have it rewritten, expanded, or condensed. The editing agent can back its changes with knowledge-base or web evidence, showing every edit as an accept-or-reject diff — nothing actually gets written into the document until you click approve.

Co-Writer workspace overview. Image from the official HKUDS repo.

Book: Turn Your Material Into a "Living Book"

Book turns your selected sources into an interactive living book — a reading environment built from typed blocks. When creating one, it first gives you a chapter outline to review, rather than dumping a black-box finished product on you. Each chapter compiles into blocks — text, callouts, quizzes, flashcards, timelines, code, charts, interactive components, animations, concept maps — and every page has its own Page Chat. Blocks can be individually inserted, moved, regenerated, or swapped for another type, without rewriting the whole chapter.

Book library overview. Image from the official HKUDS repo.

Quiz block

Manim animation block

Interactive component block

Knowledge Center: You Pick the Retrieval Engine

A knowledge base is the document collection behind RAG (looking things up before answering), grounding Chat, writing, books, and Partner conversations. What's distinctive is that you can choose the retrieval engine: LlamaIndex (the default — local vector plus keyword), PageIndex (with page-level citations), GraphRAG and LightRAG (knowledge-graph retrieval), or you can link an Obsidian vault directly and let the tutor read and write to it in place. Each knowledge base is bound to one engine, and re-indexing keeps the old version around instead of breaking the one currently in use.

Knowledge Center overview. Image from the official HKUDS repo.

Learning Space: Skills, Personas, and Reusable Context

This is the resource library and personalization layer. It stores chat history, notebooks, and question banks (every saved question keeps your answer, the reference answer, and the explanation), along with mastery paths, personas (behavioral presets like "companion," "research assistant," "teacher"), and skills (SKILL.md playbooks the model reads on demand). You don't have to write every skill yourself — you can pull one straight from the EduHub community catalog.

Learning Space overview. Image from the official HKUDS repo.

Three Commands to Run — and Other AIs Can Call It as a Tool

The smoothest path is a PyPI install: it sets up a complete local web app plus a CLI tool, no need to clone the code. Requires Python 3.11+ and Node.js 20+.

pip install -U deeptutor
deeptutor init
deeptutor start
# open 127.0.0.1:3782

docker run --rm --name deeptutor \
  -p 127.0.0.1:3782:3782 \
  -v deeptutor-data:/app/data \
  ghcr.io/hkuds/deeptutor:latest

There are four installation paths in total: PyPI (above), source (for modifying code), Docker (a single container running the full app), and CLI-only (for headless servers, agent harnesses, or scenarios like Claude Code / Codex — no web interface). Authentication is off by default and it runs single-user by default; once multi-user is enabled, the first person to register becomes the admin, and everyone else gets an isolated workspace and a redacted settings page that never exposes raw API keys. Configuration is plain JSON / YAML throughout.

It's Not Just for People — It's for Other Agents Too

The DeepTutor CLI has two modes: an interactive REPL (deeptutor chat), and structured JSON output for other agents (add --format json, streamed as NDJSON turn by turn). It runs "headless-safe": with no terminal present, an ask_user pause auto-resolves with an empty reply instead of hanging. The repo root ships with a roughly 150-line SKILL.md handoff document that Claude Code, Codex, and OpenCode recognize automatically — one read tells them how the whole system works, and deeptutor run can be wrapped as a tool inside a LangChain or AutoGen loop.

deeptutor skill search "socratic tutor"
deeptutor skill install socratic-tutor

Every skill imported from EduHub passes through the same security gate: a registry safety check, defensive archive extraction, stripping out any "always" field in the skill (a downloaded skill can't force itself into every system prompt), and writing its provenance to .hub-lock.json for auditing.

How These Features Twist Into One Rope: a Paper Lays Out the Mechanism Behind It

The pile of modules above can look like a list of features. What actually keeps them from scattering apart — what turns them into a system that gets to know you better the more you use it — is a paper the HKUDS team published alongside the release: "DeepTutor: Towards Agentic Personalized Tutoring." It answers one specific question: why can a weakness diagnosed during tutoring directly determine what question comes next, and why does performance on that question in turn improve the next explanation?

SKG and DPM are the most abstract pair of concepts in this paper — let's first use a comparison card to tell them apart:

Trace Forest: A Layered Medical Chart for Every Tutoring Session

The trace forest is DPM's ledger. Each complete tutoring conversation is recorded as a tree: Level 1 stores session-level input and a global summary, Level 2 stores the intermediate planning from task decomposition, and Level 3 stores the finest-grained execution record, including tool outputs, evidence, and verification results. Every node carries a vector encoding, so it can be retrieved by semantic similarity across the whole forest. The system browses it with a toolkit called TraceToolkit, which has only three actions: find similar by semantics (SearchTrace), enumerate filtered by time or topic (ListTraces), and read a node in full along with its ancestor path (ReadNodes).

The profile isn't generated by passively summarizing the latest conversation. Every time a new trace comes in, three dedicated memory agents actively query TraceToolkit, comparing the latest behavior against old patterns across sessions, then update three parts of the profile: a summary of session history, an evidence-backed list of recurring points of confusion, and teaching reflections that guide future sessions. Personalization is therefore built on traceable evidence, not some crude "mastery score."

Putting It Together: How the Loop Actually Turns

Put the two together: static knowledge and personal memory are first synthesized into a "personalized context" inside the hybrid personalization engine, then fed into two pipelines at once. Problem-solving tutoring goes through three steps — "investigate first, guide step by step, then write the explanation at the student's level" (beginners get a scaffolded step-by-step derivation, proficient students get a concise summary of just the key insight). Question generation goes through two steps — "map concepts from this student's perspective to pick a question, then have an independent verifier check it's correct." Once the student finishes this round, the result is written back into the trace forest and refreshes the profile.

Paper authors: Bingxi Zhao, Jiahao Zhang, Xubin Ren, Zirui Guo, Tianzhe Chu, Yi Ma, Chao Huang (The University of Hong Kong, HKUDS). v1 submitted 2026-04-10, v2 on 2026-05-08.

Does It Actually Deliver: The Results After 270 Tasks

To measure personalized tutoring, the paper built its own student-centered benchmark, TutorBench: college textbooks and papers are indexed into a knowledge base, then 3 student profiles at different levels are constructed for each knowledge base. Each profile is assigned source-grounded knowledge gaps (in three categories — misconceptions, incomplete understanding, missing knowledge), and each profile keeps exactly 3 interactive tasks that pass validation.

How It's Scored: An AI Student Takes the Class

The evaluation uses an AI-based student simulator to interact with each system under test: the simulator turns knowledge gaps into first-person statements like "I thought…", asks for a custom practice set after several rounds of tutoring, and the resulting full conversation transcript is scored against a personalization rubric. Scoring covers two groups of five criteria each, on a 1-to-5 scale. Tutoring side: source faithfulness, personalization, applicability, engagement, logical depth. Practice side: relevance, evidence sufficiency, diversity, answer quality, cross-concept coverage. The evaluation covers all 270 tasks, with Gemini-3-Flash driving both the student simulator and each system's backbone, and Claude Sonnet 4.6 acting as the judge.

The Three Dimensions With the Biggest Gains

Bar length is scaled against a maximum score of 5.

Five Systems Side by Side

All four baselines share the same retrieval tools and backbone model, differing only in whether they add chain-of-thought, self-refinement, or ReAct-style tool calling. Their scores cluster tightly, which shows that adding these alone isn't enough to catch up with a system that truly adapts to the learner.

Taking It Apart: SKG and DPM Each Carry Their Own Weight, Neither Is Dispensable

Ablation experiments remove each component separately to see which metrics collapse:

Removing both together causes the largest overall drop. This proves SKG and DPM are complementary mechanisms: SKG anchors "what the tutor says," DPM shapes "how it adapts to you" — neither can substitute for or be dropped in favor of the other.

An Unexpected Finding: With Personalization Fully Off, the Scaffolding Alone Still Delivers

The paper also tested one more thing: is DeepTutor's "investigate, solve, write" scaffolding useful only for personalized tutoring, or does it also help with general problem-solving? So the whole hybrid personalization engine (SKG and DPM both disabled) was turned off, leaving only the bare solver, and the improvement in first-attempt accuracy (Pass@1) was measured across five public benchmarks (HLE, GPQA-Diamond, the LiveBench reasoning subset, GAIA, and AA-LCR).

All five backbone models improved, with average relative gains ranging from 25.69% to 32.03%. Personalization, SKG, and DPM were all switched off for this run, so this gain points to the general-purpose value of the "investigate, solve, write" scaffolding itself.

The Boundaries the Paper Draws for Itself — and What You Can Use Right Now

The paper doesn't overstate its case. It's explicit about what has been validated and what hasn't been tested.

In the paper's own words: system extensions like the Book Engine and TutorBot (Partners, in the current product) are "architectural instances" — deployment mechanisms for long-term personalized tutoring — not interventions validated by this evaluation. Their effects on retention, engagement, and real learning outcomes require longitudinal human studies. Chat, Book, and Memory are features you can install and use right now, but whether "using it long-term actually helps people learn better" is something the paper itself hasn't tested — that's left for the future. The interactive evaluation relies on an AI student simulator and rubric-based judging, which inherently carries a gap between "controlled simulation" and "real learners"; the multi-stage pipeline also trades higher inference cost for stronger controllability. The paper's recommendation: in real use, treat generated tutoring content as an aid rather than an authority, and verify important claims against trustworthy course materials or a human teacher.

What an Ordinary Person Can Do With It Right Now

DeepTutor's approach is to build all eight learning modes — chat, problem-solving, question generation, research, note-taking, mastery practice, and more — on the same "brain," paired with a memory that grows alongside you. What you switch is just what you want to do this turn; the underlying engine and context stay the same throughout.

But a system that remembers you and writes its own questions — why should you trust that it teaches correctly and picks fitting questions? The answer is a closed loop you can see in one diagram.

What supports all of this is a "hybrid personalization engine" from the team's accompanying paper. Two things mesh together inside it: one handles "is it teaching correctly" (checking curriculum content line by line — called SKG in the paper), and the other handles "does it fit you" (remembering how you learn and where you keep making mistakes — called DPM in the paper). Turning together, the two connect tutoring and question generation into one loop.

Follow XiaoHu through one loop: he keeps getting the calculus chain rule wrong → tutoring logs this weakness in his learner file → the system generates a chain-rule question specifically → his performance on it feeds back into the next explanation. Every step of the record can be clicked open to see its source — personalization isn't locked in a black box. This is what the paper calls the "closed tutoring loop," and why it gets to know you better the more you use it.

The official improvement numbers are all scores — hard to feel as an ordinary person. Here's another way to put it: take a batch of tasks that require an AI to research and complete in multiple steps on its own, and see how many more it gets done with this scaffolding versus without.

All scores and improvement figures above come from the HKUDS team's own paper. Tutoring quality was scored by an AI student simulator, and there has been no independent third-party replication so far.