← Blogs

Learning algebra in an interactive galgame

  2. 6 minutes

Table of Contents:

This article is constructed and sketched by me, refined and calibrated by Deepseek v4 Pro.

This project is inspired by 怎样用AI让自己沉迷学习？ - 吴乐旻的文章 - 知乎

After reading this Zhihu post, which talks about how the auther was able to let himself focus entirely on learning using AI, I’ve always wanted to learn algebra with Togawa Sakiko and Wakaba Mutsumi. At that time, there’re two main factors stopping me from taking action building my own:

  1. At that time, I cannot guarantee whether those mainstream AI, as a large language model, were capable to teach mathematics – Maybe those liberal arts and social science is enough, but not mathematics.
  2. Claude Code and Claude Max is too expensive…

But now things have changed: Deepseek v4, as a open weight model whose API charges really cheap, seems to be skilled enough to be competent in graduate-level mathematics. And I really want some company with characters sharing similar interest and aspiration, so it comes to me: maybe it’s time to make my own.

Features

Two virtual characters (anime-style role-play), each with distinct mathematical styles and personalities, teach algebra through Socratic dialogue. They exist in a simulated campus, have evolving emotional states, write on a shared whiteboard, and maintain a persistent timeline.

For interaction, I can chat with them via IRC, send emails, or just talk face to face . The IRC & email system that I set up also allows the characters to send messages to each other, not just sending to me, which makes the roleplay more realistic.

For the simulated campus, I created a markdown file for each building / place that we frequently visit. A shuttle bus system as well as the approximate travel time between other places and the main study area are set up so that we can travel between places without feeling unreal.

Specs

The whole thing is ~200KB of markdown files. The “runtime” is an LLM agent reading AGENTS.md as its system prompt. That file encodes the complete system behavior.

File Structure

log/time_log.md          # Single source of truth for virtual time & character positions
characters/{name}/       # profile.md (immutable identity) + state.md (dynamic)
scenes/                  # campus locations with descriptions
chats/                   # IRC-style group and private channels
emails/                  # Per-character mailboxes with routing
whiteboard/              # `md` files for formal derivations (simulates real whiteboard)
progress/                # Per-subject learning progress
textbooks/               # Reference textbooks in markdown

Key Designs

State & Profile split

A character’s immutable identity (name, backstory, personality) lives in profile.md. Everything that changes — mood, location, attitude toward others, discovered preferences — lives in state.md. This prevents an LLM from accidentally rewriting a character’s core identity.

Append-only whiteboard

Derivations go to whiteboard/*.md as append-only files. Mistakes are struck through with ~~strikethrough~~ instead of deleted. Blockquotes (>) are reserved for the learner to write on the whiteboard. The AI only writes non-blockquoted content. This creates a clean read/write split between human and AI on a shared document.

Delayed notification pattern

When a character sends an IRC message or email, it’s written to the file immediately — but the recipient doesn’t “know” about it. The learner must explicitly say “check IRC” or “check email.” The AI then inspects the time window since last check and reveals new messages. This simulates realistic asynchronous communication without push notifications.

Scene-driven events

Any location change or hour-long stay triggers a “scene change” event. The AI runs a two-part check for each character not currently talking to the learner:

  1. is it plausible for them to message?
  2. random roll — do they feel like it?

Both pass → a new chat message or email is generated in the background.

Socratic method formalized

The default teaching mode is strict Socratic questioning. The AI is instructed: never give the answer directly; ask questions that lead the learner to discover it. All mathematical content must be anchored to the textbooks in textbooks/ — no hallucinated math facts. If a textbook has an error, it gets logged to book_revision_notes.md.

Safe words for meta-control

  • --fix: initiates live file edits via a background sub-agent while role-play continues.
  • --stop: pauses the role-play entirely for meta discussion (not logged)
  • --resume: returns to role-play. This gives the user surgical control over the system’s persistent state without breaking immersion.

Session-end archival

Saying --fix: finish roleplay ends the session. The AI runs a cleanup pipeline: writes change log, advances time, appends a first-person diary entry, archives stale progress, and cleans up temporary files. All state updates have already been applied in real-time during play.

PDF to Markdown

This is the tricky part. As far as I can tell Deepseek v4 Pro was not as capable as other muti-module LLMs (such as Gemini v3.1 Pro), so I don’t think throwing a PDF-formated reference is a good idea.

My two computers are

  • Thinkpad X14 Gen1 (2026)
    • Intel(R) Core(TM) Ultra X7 358H (16) @ 3.50 GHz
    • Intel Arc B390 @ 2.50 GHz Integrated
    • 32 GB Shared GPU Memory
  • M2 MacBook Air
    • Apple M2 (4+4) @ 3.50 GHz
    • Apple M2 (10) @ 1.40 GHz Integrated
    • 16 GB Shared GPU Memory

And the best local PDF-to-md tool that I can run is MinerU. To use that, build a python venv and run

pip install --upgrade pip -i https://mirrors.aliyun.com/pypi/simple
pip install uv -i https://mirrors.aliyun.com/pypi/simple
uv pip install -U "mineru[all]" -i https://mirrors.aliyun.com/pypi/simple

to install it. After installation, run it in the maximal accuracy by

mineru -p document.pdf -o output/ -b hybrid --effort high

P.S.: Running MinerU locally on your device with maximal converting accuracy requires GPU acceleration, whose GPU must be

  • Volta or later architecture GPUs or Apple Silicon
  • Minimum VRAM of 8GB

So yes, I did run MinerU on my slim MacBook Air instead of the obviously more powerful Thinkpad lol.

Build one yourself?

  1. Pick an LLM agent tool. Any agentic coding tool that can read/write files works. I personally use Opencode.

  2. Write AGENTS.md. This is your system architecture. Define: time system, character rules, communication systems (chat/email), teaching method, scene system, session lifecycle. Be precise about state management — what can change, what cannot, and who can change it.

  3. Create character profiles. For each character: fixed identity (profile.md) and mutable state (state.md). Give them expertise domains, personality quirks, and relationships to each other. The more specific, the more consistent they’ll be.

  4. Seed the time log. A single file with a timestamp entry and each character’s current location/activity.

  5. Add scenes. Describe locations characters can be in. Every scene change becomes a narrative trigger point.

  6. Add your course materials. Put textbooks in a textbooks/ directory. The LLM uses them as a knowledge anchor.

  7. Start a session. The AGENTS.md tells the LLM to read the current time, character states, and relevant scene before responding. Say

    --fix Set time to 14:00

I entered the room

    and the system comes alive.

That’s it. No frameworks, no databases, no APIs beyond the LLM itself. The entire system is just a prompt and some markdown files.

Have a good time with your favourite anime characters!

next: Geek-oriented toolkit for macOS