DeepTutor: your own AI tutor that remembers what you are learning

Most AI tutors forget you the moment you close the tab. DeepTutor keeps a visible, editable memory of what you are learning — and this guide installs it, wires it to a free local model, and runs a real tutoring session with no account, no API key, and no GPU.

• Who: DeepTutor (HKUDS/DeepTutor on GitHub), Apache-2.0, from the University of Hong Kong group behind LightRAG; roughly 48,000 stars on October 29, 2026, after about 1,600 stars on October 28 and a place on GitHub's daily Trending list.
• What: an agent-native learning workspace: chat, quiz generation, research, problem solving, course study, video learning, and a mastery path, sharing one session context, with knowledge bases, inspectable layered memory, and a CLI designed to be driven by agents.
• When: core package verified here as 1.7.0 from PyPI (October 29, 2026); Ollama 0.40.13; model qwen3:0.6b (522 MB).
• Requirement: Linux or macOS, Python 3.11–3.14. No account, no API key, no GPU for anything in this guide; a provider key only if you skip the local model for a hosted one.

Why this is blowing up now

Every AI tutor you have used so far forgets you. You close the tab, and the next session starts from zero: it does not know what you already understood, what you got wrong last time, or which explanation finally clicked. DeepTutor is built around the opposite idea — a tutor that keeps a visible, editable memory of the learner across sessions — and it is the reason a university research project is suddenly one of the fastest-rising repositories on GitHub.

The numbers: HKUDS/DeepTutor, from the University of Hong Kong group behind LightRAG, sat at roughly 48,000 GitHub stars on October 29, 2026, after gaining about 1,600 stars on October 28 alone and more than 5,000 over the previous week, with a place on GitHub's daily Trending list. It is Apache-2.0 licensed, written in Python, and its own description is "an agent-native learning workspace that connects tutoring, problem solving, quiz generation, research, visualization, and mastery practice in one extensible system." The latest release tracked in secondary sources is v1.6.15, from October 19 — but the version verified here, installed from PyPI on October 29, is newer: 1.7.0. This guide uses 1.7.0 throughout, and every command below was run against it.

What makes it different from a chatbot with a study prompt is the memory design. DeepTutor describes its personalization as inspectable: layered traces, summaries, and synthesis that make what the tutor believes about you visible and editable, with a Memory Graph that traces summary claims back to the evidence behind them. Around that core it packs several learning modes — chat, quizzes, research, problem solving, course study, video learning with timestamp-grounded discussion, and a mastery path — sharing one session context, plus knowledge bases you build from your own documents and a command-line interface designed to be driven by agents. The catch, stated plainly in its own docs, is that you bring your own model: setup asks for a provider, a base URL, and a key — or, as this guide does, a local model through Ollama, which costs nothing and needs no account at all.

That last point is what this guide verifies end to end. Everything below ran on an ordinary Linux machine with no API key, no account, and no GPU: the package install, the workspace setup, the diagnostics, the local model download, the provider configuration, and two real tutoring turns — a chat explanation and a generated quiz — answered by a small model running on the same machine. The web app is described from the project's docs and clearly labelled where it was not run here; everything else is output copied from runs on this machine.

What you'll need

• A Linux or macOS machine with a terminal. This guide ran on Linux x86_64, Python 3.12. Windows users should use WSL2.
• Python 3.11–3.14 and Node.js 20+ on your PATH for the full web app; the CLI path verified here needs Python only.
• No account, no API key, and no GPU for anything in this guide. The local model is a 0.6-billion-parameter model that runs on CPU; it is slow and small, and this guide says so where it matters.
• About 200 MB for the DeepTutor package and its dependencies, plus room for Ollama and the model (the Ollama bundle is large — roughly 1.5 GB downloaded — because it ships GPU libraries you will not use on a CPU-only machine; the model itself is about 500 MB).
• A provider API key only if you skip the local model and point DeepTutor at a hosted model instead. That step is outside this guide, and it is the only step that costs anything.

Step 1 — Install DeepTutor from PyPI

DeepTutor's core module ships as a plain PyPI package, which makes the CLI install refreshingly boring. Create a virtual environment first — the package pulls in a long dependency list, and you do not want it in your system Python — then install:

python3 -m venv .venv
source .venv/bin/activate
pip install deeptutor

Expected result, exactly as verified on October 29, 2026: pip reports Successfully installed ... deeptutor-1.7.0 ... alongside its dependencies (Typer, Rich, Pydantic, the OpenAI SDK, tiktoken, and others — no model weights, no GPU libraries). Confirm the CLI answers:

deeptutor --help

Expected output (trimmed): a command list headed "DeepTutor CLI – agent-first interface for capabilities, tools, and knowledge", with doctor, init, run, start, stop, serve, chat, skill, plugin, config, session, provider, workspace, and module. There is no --version flag — it errors — so the version to quote is the pip one: 1.7.0.

Two things worth knowing about this step. First, the PyPI package is the core module: the full web app comes from the full or server extras, and video learning, graph retrieval, and math animation are separate optional modules. This guide stays on the core CLI, which is the documented "CLI Only" path and needs no frontend build. Second, if your install fails with "No space left on device" or "Disk quota exceeded" while the disk looks fine, check whether your home directory is under a quota — that exact failure happened twice during this guide's verification, on a filesystem reporting tens of gigabytes free, and the fix was to build the virtual environment outside the quota'd tree. The package itself is small; the failure is environmental, not the package's fault.

Step 2 — Initialise a workspace and read the diagnostics

DeepTutor keeps its settings under data/user/settings/ in the directory you launch from (or under a --home you pass explicitly). Initialise a CLI-only workspace without prompts:

mkdir -p my-deeptutor && cd my-deeptutor
deeptutor init --cli --non-interactive

Expected output, exactly as verified:

INFO    deeptutor.services.setup.init - Created default settings: .../data/user/settings/interface.json
INFO    deeptutor.services.setup.init - Created default settings: .../data/user/settings/main.yaml
INFO    deeptutor.services.setup.init - Created default settings: .../data/user/settings/agents.yaml
INFO    deeptutor.services.setup.init - Seeded default personas: peer, research-assistant, teacher
{
  "ok": true,
  "status": "initialized",
  "runtime_home": ".../my-deeptutor",
  "next_step": "deeptutor config apply setup.json"
}

Now run the diagnostics before configuring anything, so you can see the starting state clearly:

deeptutor doctor

Expected output: two FAIL lines — "LLM configuration: No active LLM model is configured" and "LLM credentials: No credentials are configured for openai" — plus two PASS lines — "LLM endpoint: https://api.openai.com" (the default provider's endpoint, not a connection test) and "Runtime storage: Writable" — and two SKIP lines — "RAG prerequisites: Knowledge module is unavailable" (the core package does not include the knowledge-base module) and "Provider response: Not requested. Use --online to send a small model request." The FAILs are the correct starting state, not a broken install: nothing is configured yet. The next steps fix them in order.

Check the current configuration the same way:

deeptutor config show

Expected defaults: backend port 8001, frontend port 3782, LLM provider openai with an empty model and base URL https://api.openai.com/v1, API key "(not set)", embedding "not_configured", search provider duckduckgo with status ok (web search falls back to DuckDuckGo when no search provider is configured), and tools exec and web_search. Step 4 replaces the LLM block with a local model; nothing else needs to change for a first session.

Step 3 — Install Ollama and pull a small local model

DeepTutor's provider list includes Ollama at http://localhost:11434/v1 with local authentication — no key — so a local model is the free path. Install Ollama with its official script, then start the server:

curl -fsSL https://ollama.com/install.sh | sh
ollama serve

Keep that server running in its own terminal. Then, in another terminal, pull a small model. This guide uses Qwen3 0.6B — the smallest model in the Qwen3 family that still follows instructions — because the point here is to prove the wiring, not to win benchmarks:

ollama pull qwen3:0.6b
ollama list

Expected output: qwen3:0.6b listed at 522 MB. Two honest warnings from the verification run. First, the Ollama Linux bundle is large — the download measured about 1.5 GB, because it ships GPU libraries alongside the CPU binary — so budget disk space and download time accordingly, even though the model itself is only half a gigabyte. Second, if the installer fails with "This version requires zstd for extraction", your system lacks the zstd tool and the package manager has no copy (that exact failure happened here). The workaround that worked: install Python's zstandard package, download the bundle directly, and extract it with Python —

pip install zstandard
curl -fsSL https://ollama.com/download/ollama-linux-amd64.tar.zst -o ollama.tar.zst
python3 -c "
import tarfile, zstandard
with open('ollama.tar.zst', 'rb') as f:
    with zstandard.ZstdDecompressor().stream_reader(f) as r:
        with tarfile.open(fileobj=r, mode='r|') as tf:
            tf.extractall('ollama')
"
./ollama/bin/ollama serve

Before wiring DeepTutor in, prove the model itself answers through the same OpenAI-compatible endpoint DeepTutor will use:

curl http://127.0.0.1:11434/v1/chat/completions -H 'Content-Type: application/json' -d '{"model":"qwen3:0.6b","messages":[{"role":"user","content":"What is the derivative of x cubed? Answer in one short sentence."}],"max_tokens":80}'

Expected result: a JSON chat completion from model qwen3:0.6b (in the verification run it arrived in about 15 seconds including model load). Note that Qwen3 thinks before it answers: with a small token limit the reply can be all reasoning and no final sentence, which is why the DeepTutor runs below do not set a tiny limit — the tutor's own loop manages the turn.

Step 4 — Point DeepTutor at the local model

DeepTutor applies configuration from a setup JSON file, without prompts. Write one naming the Ollama provider and the model:

cat > setup.json <<'EOF'
{"llm": {"provider": "ollama", "model": "qwen3:0.6b"}}
EOF
deeptutor config apply setup.json

Expected output: {"ok": true, "status": "applied", "sections": ["llm"]}. (Validate first without writing anything with deeptutor config apply --check setup.json, which returns "status": "validated".) Confirm what changed:

deeptutor config show
deeptutor doctor
deeptutor doctor --online

Expected configuration: provider ollama, provider mode local, model qwen3:0.6b, base URL http://localhost:11434/v1, API key shown masked. Expected doctor output, exactly as verified: "LLM configuration: Active model: qwen3:0.6b (ollama)", "LLM credentials: The selected local provider does not require an API key", "LLM endpoint: http://localhost:11434", "Runtime storage: Writable", "RAG prerequisites: SKIP (Knowledge module is unavailable)", and finally "Required checks passed." The --online run adds "Provider response: PASS — The model returned a response." That last line is the moment the setup stops being configuration and starts being a working tutor.

Step 5 — Run your first tutoring session

DeepTutor's agent-first entry point runs one capability in a single turn. Ask it something with a checkable answer — seasons, not opinions — and request JSON output so you can see the turn's structure:

deeptutor run chat "Explain in two short sentences why the seasons change." --format json

The turn completed with exit code 0 after 445 streamed JSON events — a session record, a "responding" stage, 317 thinking chunks, 112 content chunks, and a result record marked completed, with one agent-loop round and zero tool steps. The answer, quoted exactly from the result record:

"The seasons change because the Earth's axis is tilted at approximately 23.5 degrees relative to its orbital plane. This tilt causes the Sun to reach different parts of the Earth at different times of the year, resulting in variations in daylight hours and temperature. When the tilt is at its maximum, the Northern Hemisphere experiences summer, and when it's at its minimum, the Southern Hemisphere does so. This axial tilt cycle is the primary driver of seasonal changes."

Read that answer like an editor, not a fan. The core claim is correct — the roughly 23.5-degree axial tilt is what makes seasons — and the answer names the mechanism (different daylight and temperature through the year). But the middle sentence is sloppy: the tilt does not swing between a maximum and a minimum through the year. The tilt stays near 23.5 degrees; what changes is which hemisphere leans toward the Sun as Earth orbits. That is the honest limit of a 0.6-billion-parameter model doing its own reasoning on a CPU: broadly right, imprecise in exactly the place a learner would repeat. The tutorial value here is not that the small model is brilliant — it is that the whole loop works, privately, for free, and you can see where it is weak instead of taking it on faith.

Expect this to be slow. On the two-core verification machine the turn took several minutes: DeepTutor's agent loop sends a long system prompt, the small model thinks out loud before answering, and CPU inference is unhurried. That slowness is the price of the free path, and it is worth stating plainly: if you want fast answers, point the same configuration at a larger local model on a machine with a GPU, or at a hosted provider — the setup, the workspace, and the session history all stay the same, only the model line in setup.json changes.

For a second turn, try a different capability on the same setup — quiz generation:

deeptutor run ask_questions "Ask me two quiz questions about why the seasons change, one at a time." --format json

Verified output, quoted exactly: two questions, both answered in the same turn despite the "one at a time" instruction — the small model ignored the pacing. Question 1: "Why does the sun appear to move in the sky?" Answer: "The Earth's axis is tilted, causing the sun to move across the sky as we rotate." Question 2: "Why does the sun have a different position in the sky during different seasons?" Answer: "The Earth's axial tilt causes the sun to shift position in the sky, which is why seasons change." Question 2 is broadly right. Question 1's answer is muddled: the Sun's daily apparent motion comes from Earth's rotation, not from its tilt — the answer blends the two causes. Same lesson as Step 5: the loop works, the model is small, and you check its answers before you trust them.

One correction worth making explicit, because the help text invites the mistake: deeptutor run --help lists capability examples including deep_solve, deep_research, visualize, math_animator, and mastery_path, but the core package installed here only resolves two capabilities — chat and ask_questions. Asking for deep_question fails fast with "Unknown capability `deep_question`. Available: ask_questions, chat". The other capabilities live in optional modules you install separately; do not copy capability names from the help examples without checking them against your own install.

Step 6 (optional) — The web app, and where the CLI stops

Everything above is the CLI path, which the project documents as a first-class option ("CLI Only (no web UI)"). The full web app — chat, quizzes, research, video learning, and knowledge bases in a browser at http://127.0.0.1:3782 — comes from the full or server extras (pip install "deeptutor[full]", then deeptutor start, which launches backend and frontend together) and needs Node.js 20+ on your PATH for its packaged frontend server. This guide did not run the web app — the CLI verification above is the verified path — so treat the web UI as documented, not demonstrated, here. One limit to know before you go further: the core package does not include the knowledge-base module, which is why doctor reports "RAG prerequisites: SKIP". Building a knowledge base from your own documents needs one of the parsing extras and an embedding model configured in Settings; that is a second tutorial's worth of setup, not a flag you forgot.

When to use this vs alternatives

Use DeepTutor when you want a tutor that accumulates knowledge about you over weeks — a course you are working through, a subject you revisit, a set of your own documents to learn from — and you want that memory inspectable rather than locked inside a chat history. Its knowledge bases, quiz generation, and mastery path are built for sustained study, not one-off questions.

Use LearnHarness instead — the blog's earlier tutorial on amosblomqvist/learnharness, a diagnostic-first desktop tutor — when your priority is a single session that measures exactly where your understanding stops before teaching anything; it plans one lesson from that measured point, where DeepTutor plans a longer arc. Use plain Ollama (see the blog's Ollama hands-on guide) when you only need a local model to chat with and do not need tutoring modes, memory, or quizzes at all. Use a hosted chatbot when you need the strongest available model and do not mind an account, a key, and your study data leaving your machine — that is the one trade DeepTutor's local path refuses to make, at the cost of a much smaller model.

Do not use DeepTutor as a replacement for a textbook or a teacher on high-stakes material without checking its answers: the local model in this guide is tiny, and even a large model can be confidently wrong. Treat its explanations as a first pass, and verify anything that matters against your own sources.

The takeaway

DeepTutor's pitch is not a smarter chatbot — it is a tutor with a memory you can inspect, running on your own machine, on a model you control. Installed from PyPI in one command, initialised without prompts, diagnosed honestly by its own doctor command, and pointed at a free local model through Ollama, it gives you a working, private study companion with no account and no key. The small local model is the honest limit of the free path: answers are short and sometimes shallow, and you will outgrow it on hard material. But the workspace, the configuration, and the memory design all carry over unchanged when you later point the same setup at a larger local model or a hosted provider — and that upgrade path, from free to serious without reinstalling anything, is the reason to start here.

Sources: the HKUDS/DeepTutor repository and documentation at deeptutor.info (install paths, CLI commands, provider list, and capability names, read October 29, 2026), the deeptutor 1.7.0 package from PyPI installed and run for this guide (init, doctor, config, chat, and ask_questions outputs shown), Ollama 0.40.13 with model qwen3:0.6b (522 MB) run locally for the two tutoring turns, and GitHub tracking figures (roughly 48,000 stars, about 1,600 gained on October 28, 2026, daily Trending placement) from the trackers cited in the text. Star counts are the trackers' figures, not re-measured here; every command, version, and quoted model answer in Steps 1–5 is from runs on the verification machine. The web app path in Step 6 is described from the project's docs and was not executed here.