The lesson is over. Your memory isn't.
Most AI classrooms are one-shot: generate a course, finish it, forget where it went.
SpiralMAIC gives the classroom an afterlife. It remembers what the course was about,
lets those memories fade naturally, and brings you back when a review would actually help.
Then comes the plot twist: the AI stops teaching. You take the teacher seat.
Your AI classmates are ready to be difficult
In a Reverse Challenge, you explain a sparse review deck in your own words. The AI
classmates listen, ask follow-ups, make deliberate mistakes, and request a fresh example.
If things get stuck, an AI assistant can step in—just enough to get the room moving again.
It all happens inside the real classroom player, not in a lonely quiz form or a generic chat box.
No answer on the slide. No multiple-choice escape hatch. Just you, the idea, and a few
suspiciously curious AI students.
It still starts with a proper AI classroom
You still get slides, quizzes, interactive scenes, PBL, whiteboard, speech, editing, and
exports. SpiralMAIC simply refuses to let all of that disappear after “Complete.”
One loop looks like this
- Take the course. Start from a topic, PDF, or other source material.
- Come back later. The course card quietly shifts as estimated recall fades.
- Switch seats. Open Reverse Challenge and teach the review deck back.
- Let the room push back. Questions, misconceptions, transfer examples, and bounded rescue.
- See what held up. Get a report for clarity, doubt resolution, transfer, and correction.
- Do the next useful thing. Review later, replay the room, or spin up a focused study artifact.
The little things that make the loop work
- Memory that breathes — every concept gets its own half-life instead of a blunt course-level checkbox.
- A real cast — each classroom carries its own generated students and assistant into the challenge.
- Evidence, not vibes — feedback points back to the conversation, passed pages, and factual mistakes.
- A Study Studio — make a visual briefing, mind map, study guide, FAQ, flashcards, or quiz.
- Post-class overtime — ask one more good question and turn it into a new lesson page.
- A demo time machine — fast-forward memory decay without messing up your real learning history.
Run it
You need Node.js >= 22.19 < 23, pnpm 10, PostgreSQL, and one model provider (cloud or local).
git clone https://github.com/YizukiAme/SpiralMAIC.git
cd SpiralMAIC
corepack enable
pnpm install
cp .env.example .env.local
cp openmaic.example.yml openmaic.yml
pnpm db:up
Set the local database URL in .env.local:
DATABASE_URL=postgres://openmaic:[email protected]:5432/openmaic
Before starting, put your provider key in .env.local:
OPENAI_API_KEY=sk-...
In openmaic.yml, pick your model under slots.llm:
providers:
openai:
preset: openai
apiKey: ${OPENAI_API_KEY}
slots:
llm: openai:gpt-5.5
Want more models in the picker? Add them to that provider's models list. Server-provided
keys can only use listed models or models assigned to a slot.
Or skip the YAML file and set up model services in the app. Settings now live on the server,
so your next browser gets the same workspace configuration—without carrying API keys in requests.
pnpm dev
Then open http://localhost:3000, make a classroom, and start the loop.
If this browser has courses or learning records from an older version, SpiralMAIC asks before
copying them to this server. You can choose Later and return from Settings. The browser
originals are kept; a partial import can resume without creating duplicate courses.
There are plenty of other options—Gemini, Anthropic, Bedrock, DeepSeek, Qwen, Kimi,
MiniMax, GLM, Xiaomi MiMo, OpenRouter, Ollama, Lemonade, and more. The always-current list
lives in openmaic.example.yml and .env.example.
Classroom chat and teach-back now run on Pi. Pick a Classroom model with tool calling;
for Gemini, use the native Google provider. Remove the old NEXT_PUBLIC_PI_CHAT_ENABLED
switch if you kept it from an earlier setup.
Build and run the production app:
pnpm build
pnpm start
Or use Docker:
docker compose up --build
Docker Compose includes PostgreSQL by default. The isolated MP4 render service is optional.
Courses generate on the server and keep going when the tab closes; use a long-running Node
process or container. Back up both PostgreSQL and data/, including instance-secret.key,
which protects saved provider keys. Mount your openmaic.yml into the container if using one.
See the storage guide and
render-service guide.
The current server-backed app does not support Vercel's serverless Next.js deployment.
Use a long-running host for generation and learning records.
Shared deployments should set ACCESS_CODE. Local instances remain open when it is unset;
when enabled, a verified browser stays signed in for up to seven days before asking again.
See the v0.4 upgrade guide for compatibility and rollback notes.
For slow networks, Docker builds accept ALPINE_MIRROR (an Alpine mirror hostname) and
NPM_REGISTRY (a complete npm registry URL):
ALPINE_MIRROR=mirrors.tuna.tsinghua.edu.cn \
NPM_REGISTRY=https://registry.npmmirror.com \
docker compose up --build
Use public mirrors only; Docker may retain build arguments in image metadata.
The Spiral-specific layer is intentionally easy to find:
| Path | What's inside |
|---|
app/classroom/[id]/revisit/ | The Reverse Challenge classroom |
components/revisit/ | Review panel, report, Study Studio, artifact viewers |
lib/revisit/ | Memory, blueprints, evidence, judging, and formal/Demo storage |
lib/overtime/ | Post-class follow-up lessons |
eval/revisit-judge/ | Report stability evals |
Useful checks:
pnpm check
pnpm lint
pnpm typecheck
pnpm typecheck:e2e
pnpm check:i18n-keys
pnpm test
pnpm build
License
MIT. SpiralMAIC is based on OpenMAIC; its original notices and attribution are preserved.
