WeSmartFlow: an agent-native learning framework with a personal knowledge graph and pluggable exploration worlds

What WeSmartFlow is built for

The project describes itself as an agent-native adaptive learning framework, and the premise is stated plainly in the README: real learning is rarely one question and one answer. It involves curiosity, getting stuck, trial and error, forgetting, and the moment something suddenly clicks. So the framework organises around five abilities: understanding the goal and where you currently are, accompanying practice with explanations, follow-up questions, cards, visualisations and quizzes, remembering growth in a personal knowledge graph, adjusting the path based on feedback from dialogue and practice, and putting knowledge into situations such as stories, experiments and real tasks. The audience splits in two. Learners get four entry modes, and developers get a reusable education agent stack with the agent core, the backend services, the frontend and the standalone learning worlds separated into their own directories.

The tutoring loop and the tools behind it

Tutoring is a ReAct agent that picks education tools as a conversation needs them, and the tool table in the README is the clearest description of what that means in practice. Knowledge node creation and update recognises new concepts and fills in descriptions, tags and relations. Mastery update changes the mastery value for the relevant node based on performance. The HTML knowledge card tool turns a point into a readable, saveable card. EduViz produces an interactive visualisation with animation, parameters and manipulable objects. An instant quiz tool generates single choice, fill in the blank, true or false and open questions with feedback. Graph retrieval pulls back material already studied so sessions do not start from zero, multi-source search supplements material through Tavily, arXiv and DuckDuckGo, and speech explanation generates audio narration where the environment supports it.

Graph memory and what it actually stores

The memory design is the part that separates this from a chat transcript. Each knowledge node carries a mastery_level that records how understanding changes over time. Relations between concepts fall into four types, prerequisite, related, extends and contrasts, which is a small enough vocabulary to be usable and rich enough to express that one idea builds on another or competes with it. Review scheduling uses SM-2 parameters, the same spaced repetition family behind Anki, so the graph decides what to bring back rather than leaving that to the learner. The same personal graph is shared across free tutoring and immersive courses, and a separate user profile memory accumulates preferences and background from long-term interaction. A second, public knowledge graph is managed independently under backend/kg/ through a kg_facade, with Graph RAG, observation records and proposal review kept apart from personal learning state.

Multi-agent course generation and the content tools

Immersive courses are produced by a pipeline rather than a single prompt. The README lays the agents out as a tree: a planning agent breaks the topic into chapters and a learning path, a research agent gathers and organises material, a writing agent produces chapter courseware, an illustration agent generates images, a speech agent produces audio narration, and a quiz agent builds exercises and feedback, with the output being PDF plus audio plus exercises plus knowledge graph nodes. On the content tools themselves, the project is candid about the failure mode. HTML cards use a unified layout component set. EduViz generates JavaScript through an SDK, is checked, and is then repaired against specific problems; a browser check looks for runtime problems and a model review checks core correctness, and the README states that passing those checks does not mean the visual result or the teaching content has been fully verified. That is the right kind of disclaimer for generated interactive content.

Installing it and wiring in a new exploration world

The repository uses Git LFS for PNG and MP4 assets, so the clone step is not the usual one liner, and the README recommends the Conda environment in the repository, which prepares Python, Node.js and the backend dependencies. Generating immersive PDF courseware additionally needs XeLaTeX, latexmk and the SimplePlus Beamer theme.

git lfs install
git clone https://github.com/Tencent/WeSmartFlow.git
cd WeSmartFlow
git lfs pull

For developers, the most interesting seam is the exploration mode. Topics are loosely coupled to the main site and can be built with Vue, React, Svelte, Canvas, Three.js or plain HTML, and there are only three stable contracts between the site and a topic: the content contract at examples/explore-catalog.json, the build contract of a build:wesmartflow command plus agreed environment variables, and the service contract of a same-origin static path with an optional relative /api path. Adding a topic means creating the app under examples/, providing that build command, registering its category, entry and description in the catalog, then running directory validation and the build check.

cd frontend
npm run validate:examples
npm run build:examples -- --only your-topic-id

Six topics are listed as live: Magic English Town for eight to sixteen year olds where a local state machine handles locations, tasks, rewards and completion conditions while the agent handles understanding and character replies, Walk Into the Math Garden, BingeMate for learning expressions from real drama dialogue, a chemistry lab where the agent judges the result of combining substances and conditions, a topic that returns to the moments scientific knowledge was created so you can talk with scientists and redo classic experiments, and Generated World History where a period becomes an argumentative, queryable world.

WeChat through WeClaw and the other entry points

One integration is worth calling out because it changes where learning happens. Through WeClaw, a WeChat clawbridge, the edu-agent is attached as a messaging channel so WeChat conversations are answered by the same tutoring service. Binding is by QR code on the web assistant page, and each user binds their own bot. The transport is a multi-tenant long poll with one async httpx long polling coroutine per bot, scheduled by a ChannelManager, which the README describes as roughly one idle long connection rather than a thread, so a single machine can carry many online bots. Messages go straight to TutorService, so WeChat shares the same ReAct tutoring, knowledge graph and user profile as the web side. HTML cards, interactive visualisations and quiz cards are rendered to images with a headless browser, Playwright, and sent with a link back to the interactive version on the web.

Limits, licence and upkeep

Start with the content verification boundary already quoted: browser checks find runtime problems and a model review checks core correctness, but passing does not mean the visuals or the teaching content are fully validated, so generated EduViz output needs a human look before it goes in front of a class. The hosted site runs on a credit model rather than being free in the ordinary sense: registering with GitHub or email grants five million credits, starring the repository and verifying the bound GitHub account grants another five million, and from the following month the balance is topped up by up to one million per month toward five million, with the README noting that usable time varies with the chosen model, study frequency and content length. Self-hosting avoids that but means running the Python backend, the Vue 3 frontend and the model access yourself, and the last push was on 2026-09-15. On licensing, the README carries an MIT badge and the repository ships a LICENSE file at the root, while GitHub reports the licence as one it does not recognise, so anyone clearing this for organisational use should read the file rather than trust either signal. That matters here because the repository is not one program: it is an agent core, a backend, a frontend, an examples directory of independently authored worlds and a public knowledge graph module, and the README states that course authors retain their own code structure, design language and update process. The update log records an August 2026 exploration mode redesign and a free credit programme started on 2026-08-31, and there is a README_EN.md alongside the Chinese README plus an online experience at wesmartflow.cn.

Compared with a plain chat tutor

The obvious alternative is a general chat assistant with a well written system prompt. It needs no deployment, no Git LFS, no Conda environment, and for a single focused question it is faster to reach. What it cannot do is persist structured state: there is no mastery_level per concept, no typed relations between ideas, no SM-2 schedule deciding what to review next, and no graph shared between a free-form question and a structured course. WeSmartFlow adds all four, plus a multi-agent pipeline that produces courseware, audio and exercises from one topic, and a contract that lets someone else build an entire learning world and register it. The cost is real: a FastAPI backend, an agent core with tool and MCP plumbing, a frontend build and model access. Choose the chat assistant for one-off explanations and this framework when the point is continuity across weeks.

Editorial conclusion

Use WeSmartFlow if you want a tutor that remembers: mastery_level per knowledge node, four relation types between concepts, and SM-2 spaced repetition shared between free tutoring and immersive courses. Use it as a framework rather than a product if you want the ReAct core, the DAG workflow layer and the tool and MCP plumbing under backend/agent_core/. Do not take it if you only need chat, because the graph, the multi-agent course pipeline and the exploration shell are the parts that cost you a Python and Node deployment. Before building a topic, read the three contracts, since a world only has to supply examples/explore-catalog.json, a build:wesmartflow command and a same-origin static path.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Tencent/WeSmartFlow on GitHub