DeepTutor: 27K‑Star Open‑Source AI Tutor with Agent‑Native Architecture and Auditable Memory

Limitations of existing AI learning tools

Typical tools provide direct answers, lose context when switching modes, fabricate references for research queries, and require cloud uploads that expose private data.

DeepTutor core innovations

Double‑loop reasoning architecture

Instead of a single pass that returns a complete answer, DeepTutor executes two loops:

Analysis loop – automatically parses the problem, retrieves relevant personal knowledge, identifies weak points, and decomposes the question.

Solve loop – guides the user through progressive questioning, offering step‑by‑step reasoning and source citations.

Three‑layer auditable memory

All interactions are recorded in three visualizable layers:

L1 – Raw trace – complete logs of dialogues, document reads, and problem‑solving steps.

L2 – Summary – automatically extracted key points, errors, and weak concepts, editable by the user.

L3 – Integrated knowledge graph – a consolidated knowledge map forming a personal learning dossier.

The Memory Graph lets users trace any AI judgment back to the original document or question.

Feature‑rich workspace

DeepTutor provides nine integrated modules that replace separate search‑question apps, reference managers, note‑taking tools, and quiz systems:

Chat – unified entry point for all six capabilities; supports PDF, Word, Markdown, PPT, and Excel uploads.

Solve – step‑by‑step problem solving with source citations.

Quiz – clone real exams and generate personalized practice tests.

Visualize – interactive dynamic visualizations for complex math or algorithms.

Research – deep literature review that produces structured reports with traceable references.

Mastery Path – adaptive learning path that blocks progression until knowledge points are mastered.

Co‑Writer – dual‑pane Markdown editor with native LaTeX support, AI‑assisted rewrite, and diff‑based approval.

Book – compiles textbooks, notes, or papers into interactive e‑books with embedded quizzes, flashcards, and animations.

Knowledge Center – multi‑engine RAG system (LlamaIndex, GraphRAG, LightRAG, Obsidian) for local document indexing and retrieval.

Extensible AI partners

DeepTutor can connect to 15 instant‑messaging platforms (e.g., Feishu, Telegram, Slack, DingTalk, QQ, WeChat Work). Each partner runs as an independent AI persona with its own knowledge base and isolated memory, enabling private‑assistant interactions without opening a web browser.

My Agents – custom sub‑agents

Users can import local large models or historic dialogues as separate sub‑agents, allowing on‑demand code analysis, paper summarization, or complex mathematical reasoning without copying context.

Deployment options

DeepTutor runs on Windows, macOS, and Linux with Python 3.11+ and Node.js 20+.

Docker (one‑click, ~30 s startup)

docker run -d --name deeptutor \
  -p 127.0.0.1:3782:3782 \
  -p 127.0.0.1:8001:8001 \
  --add-host=host.docker.internal:host-gateway \
  -e LLM_MODEL=gpt-4o \
  -e LLM_BINDING_API_KEY=YOUR_KEY \
  -e LLM_BINDING_HOST=https://api.openai.com/v1 \
  -e EMBEDDING_MODEL=text-embedding-3-large \
  -e EMBEDDING_BINDING_API_KEY=YOUR_KEY \
  -e EMBEDDING_BINDING_HOST=https://api.openai.com/v1 \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/config:/app/config:ro \
  ghcr.io/hkuds/deeptutor:latest

Access the UI at http://localhost:3782 and the API docs at http://localhost:8001/docs.

PyPI (one‑click install)

mkdir my-deeptutor && cd my-deeptutor
pip install -U deeptutor
deEPTutor init   # interactive config for ports, models, keys
deEPTutor start   # launch backend and frontend

Source deployment (developer mode)

git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
cd web && npm ci --legacy-peer-deps
deEPTutor init
deEPTutor start

CLI‑only (headless server mode)

git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor/packaging/deeptutor-cli
python -m pip install -e .
deEPTutor init --cli
deEPTutor chat

Common CLI commands include creating knowledge bases, solving equations, viewing memory, and installing community skills.

Common pitfalls and fixes

Ollama container cannot reach host model – Docker’s internal https://localhost differs from the host; add --add-host=host.docker.internal:host-gateway and set the model URL to http://host.docker.internal:11434/v1.

Port conflicts (3782/8001) – Use netstat -ano | findstr "3782" on Windows or lsof -i :3782 on macOS/Linux to free the port.

Local models < 13B parameters fail – The Agent loop requires sufficient model capacity; use ≥13B models locally or cloud‑based GPT‑4o/Claude‑3 for stability.

PDF parsing crashes – Delete the problematic document directly from the knowledge‑base panel instead of rebuilding the entire index.

LLM vs. embedding API keys mixed up – Keep separate keys for chat models and embedding models.

Windows uvloop errors – Run PowerShell as administrator or adjust the event‑loop configuration.

IM partner messages not received – Install required dependencies (e.g., libolm for Matrix encryption).

Horizontal comparison

DeepTutor – fully offline, three‑layer auditable memory, unified Agent core, exam cloning, interactive visualizations, four RAG engines, 15 IM integrations, Apache‑2.0 open source.

ChatGPT/Claude – cloud‑only, session cleared on exit, fragmented functionality, no exam generation, static charts, no local RAG, no IM integration, paid.

NotebookLM – cloud‑only, no long‑term memory, single‑purpose Q&A, no exam module, no interactivity, fixed retrieval, closed source.

Typical local RAG tools – offline but lack layered memory, guided solving, exam module, visualisation, and multi‑engine RAG.

Mini‑search AI apps – cloud‑based, no learning record, direct answers only, no mock exams, text‑only output, no document store.

Target user groups and core use cases

Students (K‑12, university, exam prep) – upload textbooks and past exams, generate same‑difficulty mock papers, visualize complex problems, track weak points with Mastery Path, export review outlines from the three‑layer memory.

Developers / self‑learners – import technical docs, use My Agents with local Claude Code for code analysis, generate interactive algorithm flowcharts, compose technical notes with Co‑Writer and compile them with Book.

Researchers / graduate students – batch import papers, use GraphRAG to map literature relationships, run Deep Research mode for structured reviews with source citations, keep unpublished work entirely offline.

Teachers / corporate trainers – upload lecture materials, auto‑create quizzes and mock exams, assign isolated knowledge bases per student, share interactive e‑books via web links.

AI enthusiasts / local‑model hobbyists – run the entire stack on Ollama for zero cloud cost, develop custom EduHub skills, automate batch processing with CLI scripts.

Project repository

https://github.com/HKUDS/DeepTutor