Open Source Project #189: DeepTutor — Agent-Native Lifelong Learning Workspace, 3-Layer Memory + Multi-Engine RAG + Partners, 33k Stars

Introduction

"One runtime for every mode — switch the objective, not the engine."

This is article #189 in the "One Open Source Project a Day" series. Today's project is DeepTutor — an agent-native learning workspace from HKUDS (HKU Data Intelligence Lab), 33,468 Stars, Apache-2.0, built on Python 3.11+ and Next.js 16.

DeepTutor's core claim: Chat, Quiz, Research, Visualize, Solve, and Mastery Path all run on the same agent loop — you switch the objective, not the engine, and context travels with the learner. The memory system is a three-layer auditable architecture where every synthesized claim traces back to a raw event; knowledge bases support six retrieval engines; Partners have their own soul, model policy, and channels that connect to 15 IM platforms.

What You'll Learn

• DeepTutor's core architecture: single agent loop and major functional modules
• Three-layer memory (L1/L2/L3) design and auditability
• Multi-engine knowledge bases: LlamaIndex, GraphRAG, LightRAG, Obsidian, etc.
• Partners: AI companions, IM channels, subagent mode
• My Agents: driving local Claude Code/Codex as subagents
• Four installation options: PyPI, source, Docker, CLI-only

Prerequisites

• Basic terminal experience
• General familiarity with RAG (Retrieval-Augmented Generation) helps for the knowledge base sections
• Python basics (if you want to modify source code)

Project Background

Overview

DeepTutor is an agent-native learning workspace, not a simple ChatGPT wrapper. Its architectural signature: all functional modes (Chat, Quiz, Research, Visualize, Solve, Mastery Path) run on the same ChatOrchestrator agent loop, with tools mounted on demand, rather than each mode being an independent code path.

From the HKU Data Intelligence Lab, with an accompanying paper at arXiv:2604.26962.

Author / Team

• Organization: HKUDS — HKU Data Intelligence Lab
• Primary languages: Python 3.11+ (backend) + Next.js 16 / React 19 (frontend)
• License: Apache-2.0
• Website: deeptutor.info
• Paper: arXiv:2604.26962

Project Stats

• ⭐ GitHub Stars: 33,468+
• 🍴 Forks: 4,321+
• 📄 License: Apache-2.0
• 📅 Created: 2025-12-28 (10k Stars in 39 days)

Quick Installation

Four installation paths — PyPI is recommended:

# Option 1: PyPI install (no clone required, recommended)
mkdir my-deeptutor && cd my-deeptutor
pip install -U deeptutor
deeptutor init     # configure ports, LLM provider, optional embedding
deeptutor start    # start backend + frontend
# Open http://127.0.0.1:3782

# Option 2: Source install (for development)
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 && cd ..
deeptutor init && deeptutor start --dev

# Option 3: Docker (single container)
docker run --rm --name deeptutor \
  -p 127.0.0.1:3782:3782 \
  -v deeptutor-data:/app/data \
  ghcr.io/hkuds/deeptutor:latest
# Only port 3782 needs publishing; internal proxy forwards /api/* and /ws/*

# Option 4: CLI-only (no Web UI)
pip install -e ./packaging/deeptutor-cli
deeptutor init --cli
deeptutor chat

deeptutor init prompts for: backend port (default 8001), frontend port (default 3782), LLM provider / Base URL / API key / model name, and an optional embedding provider.

Core Architecture: Single Agent Loop

The key design in DeepTutor: all learning modes run on the same agent loop.

User input → ChatOrchestrator → (mode-specific tools mounted) → LLM reasoning → tool calls → ... → final reply

The difference between modes is which tools are mounted, not a different engine:

Switching modes doesn't switch context: in one session, going from Chat to Quiz to Research, the history and knowledge bases follow you.

Tool mounting rules:

• Sticky session context (subagent, knowledge bases, persona, model): set on the composer toolbar, persists across turns
• One-time references (files, chat history, books, notebooks): added via the + menu, active for that single turn

The ask_user tool is a deliberate design: when the agent isn't sure, it can pause the current turn, pose a structured clarifying question, and resume once you answer — rather than guessing or staying silent.

Three-Layer Memory System

One of DeepTutor's most valuable engineering designs: memory is file-backed, three-layer, and fully auditable — not a hidden vector store.

data/memory/
├── trace/          ← L1: append-only event traces (JSONL per surface per day)
├── L2/             ← L2: curated facts per surface (Markdown)
└── L3/             ← L3: cross-surface synthesis (profile/recent/scope/preferences)

• L1 (event traces): trace/<surface>/<date>.jsonl — append-only, covers chat/notebook/quiz/kb/book/cowriter surfaces
• L2 (surface summaries): L2/<surface>.md — curated facts; each L2 record cites an L1 raw event
• L3 (cross-surface synthesis): L3/{profile,recent,scope,preferences}.md — user profile synthesized across surfaces; each L3 claim cites L2

Memory Graph: visualizes the whole pyramid — L3 synthesis at the center, L2 in the middle ring, L1 events on the outside. Trace any synthesized claim to the exact raw event behind it. No black box.

deeptutor memory show    # view L2/L3 memory documents
deeptutor memory clear   # clear L1 or all memory

Also manageable from the CLI; Settings → Memory lets you tune the consolidator's Update/Audit/Dedup budgets.

Multi-Engine Knowledge Bases

DeepTutor supports six retrieval engines; each knowledge base is bound to one engine:

Document parsing engines (configured in Settings → Knowledge Base): Text-only, MinerU, Docling, markitdown, PyMuPDF4LLM.

Version control: rebuilding an index writes a new version-N directory and keeps prior ones — a working index is never destroyed mid-rebuild. Individual failed documents can be removed from even an error-state base without rebuilding the whole thing.

deeptutor kb create my-kb --doc textbook.pdf
deeptutor kb add my-kb --doc chapter2.pdf
deeptutor kb search my-kb "gradient descent mechanics"
deeptutor kb list

Knowledge bases are reusable across Chat, Partners, Co-Writer, and Book.

Partners: Persistent AI Companions

Partners are persistent companions with their own soul, model policy, knowledge bases, memory, and IM channels.

Architecturally, a Partner is not a separate bot engine: every inbound IM message becomes a normal ChatOrchestrator turn inside a partner-scoped workspace. A partner is "a chat that has a personality and a phone number."

Each Partner has:

• SOUL.md: persona/behavior definition
• Independent model selection
• Own knowledge bases, skills, and notebooks
• Own memory (reads the owner's memory, writes its own)
• Channels: connections to IM platforms

Supported IM platforms (depending on installed extras): Feishu, Telegram, Slack, Discord, DingTalk, QQ/NapCat, WeCom, WhatsApp, Zulip, Mattermost, Matrix, Mochat, and Microsoft Teams.

Partners can also act as subagents, callable from any Chat turn via the consult_subagent tool.

My Agents: Drive Local Coding Agents

My Agents lets DeepTutor call local coding agents:

Connect a live agent: Wire in a Claude Code, Codex, Gemini, Kimi, opencode, or MiMo Code CLI running on your machine, or one of your Partners, and consult it from inside a chat turn. DeepTutor actually runs the other agent and streams its work into the Activity panel via the consult_subagent tool. Select it with the Agent chip (or type @), and set how many rounds the consult may take.

Import past conversations: Bring in your existing Claude Code and Codex conversation history as named, searchable, resumable agents. Choose which days to import; refreshing re-syncs the latest content. Reference an imported conversation from any chat turn via + → My Agents — DeepTutor reads it as a third-party transcript, keeping it as their conversation, not DeepTutor's own voice.

Co-Writer: Selection-Aware Markdown Drafting

Co-Writer is a split-view Markdown workspace for reports, tutorials, notes, and long-form learning artifacts. Documents autosave with live preview (KaTeX math, diagram fences), and can be saved back into notebooks when a draft becomes reusable context.

The defining idea is surgical editing: select a span and ask DeepTutor to rewrite, expand, or shorten it. The edit agent can ground the change in a knowledge base or web evidence, keeps a full trace of its tool calls, and shows every change as an accept/reject diff — nothing lands until you approve it.

Book: Living Books from Your Materials

Book compiles selected sources (knowledge bases, notebooks, question banks, chat history) into an interactive living book — not a static PDF, but a reading environment built from typed blocks.

The creation flow proposes a chapter outline before generating content, so you review the structure rather than accepting a blind one-shot output.

Each chapter compiles into typed blocks: text, callouts, quizzes, flashcards, timelines, code, figures, interactive HTML, animations, concept graphs, deep dives, and user notes — with every page having its own Page Chat. Blocks are individually editable: insert, move, regenerate, or switch a block's type without rewriting the whole chapter.

CLI and Agent-Native Interface

DeepTutor is designed to be driven by other agents:

# Interactive REPL
deeptutor chat
 
# Single run, human-readable
deeptutor run deep_research "Survey 2026 RAG advances" --config mode=report
 
# Machine-readable (NDJSON streaming)
deeptutor run deep_solve "Find d/dx[sin(x^2)]" --tool reason --format json
 
# Stateful multi-turn sessions
SID=$(deeptutor run deep_research "RAG survey" --format json \
  | jq -r 'select(.type=="done").session_id')
deeptutor run deep_question "Quiz me on that" --session "$SID" --format json

With --format json, each turn outputs NDJSON: content, tool_call, tool_result, done events, each line tagged with session_id. With no TTY, ask_user pauses auto-resolve with an empty reply rather than hanging — safe for CI/CD.

The root SKILL.md is a ~150-line handover document that teaches any tool-using LLM the entire CLI surface in one read. Claude Code, Codex, and OpenCode pick it up automatically; it can also be used to wrap deeptutor run as a tool in LangChain or AutoGen pipelines.

Full CLI Command Reference

Resources

Official Links

• 🌟 GitHub: HKUDS/DeepTutor
• 🌐 Website: deeptutor.info
• 📄 Paper: arXiv:2604.26962
• 📦 Docker image: ghcr.io/hkuds/deeptutor
• 💬 Discord: discord.gg/eRsjPgMU4t

Summary

Several engineering decisions in DeepTutor are worth noting:

Single agent loop drives all modes: Chat/Quiz/Research/Visualize aren't separate code paths — they're the same loop with different tools mounted. Context doesn't get lost when you switch modes, and tools can be freely combined in a single turn (RAG retrieval plus web search, simultaneously).

Three-layer auditable memory: The L1→L2→L3 citation chain ensures every synthesized claim traces back to a raw event. This addresses a fundamental problem with personalized AI tools: users don't know what the system "remembers" or where those memories came from. The visual Memory Graph makes this transparent.

Partners as scoped chat workspaces: A Partner isn't an independent bot — it's a chat scope with a soul and IM channels. This abstraction lets the same RAG, memory, and tool-calling mechanisms be reused for any IM platform's companion scenario without maintaining multiple code paths.

Agent-native CLI design: NDJSON output, headless-safe ask_user auto-resolution, and a root SKILL.md as agent handover document — these details show the project was designed from the start to be driven by other agents, not bolted on as an afterthought.

If you need a self-hostable, auditable-memory, multi-RAG-engine AI learning workspace that connects to IM platforms, DeepTutor is one of the most complete options in the open-source community right now.

Explore PrimeSkills — a curated marketplace of AI agents and skills, each validated against real enterprise workflows. No hype, just what actually works.

Visit my personal site for more insights and interesting products.