MindTrain

MindTrain is an open-source knowledge-training platform for Codex and other AI clients. Learn through a natural conversation: ask follow-up questions, challenge an answer, or request a hint at any time. MindTrain handles the question bank, deterministic grading, learning history, and spaced-review scheduling behind the scenes.

• Stay in the conversation: ask about an unfamiliar concept without accidentally submitting the current question.
• Own your data: self-host a single-user instance with your question bank and learning history stored in PostgreSQL.
• Close the learning loop: review old questions, generate new ones on demand, record mistakes, and control daily new-question and review backlogs.
• Initialize a knowledge catalog: plan domains and topics through an AI conversation, or organize a knowledge tree from a local reference directory. Nothing is saved until you preview and confirm it.

MindTrain Core is domain-independent. Each private instance manages its own training domains, knowledge trees, and questions.

Preview

How it works

• Training Core is the source of truth for questions, sessions, attempts, review state, and configuration.
• Trainer MCP calls Core APIs and never accesses the database directly.
• The Skill orchestrates teaching and tools but stores no authoritative application data.
• A temporary AI-generated question is validated and persisted before display. It can be rejected and physically deleted before answering; once answered, it becomes a regular review question.

See the architecture overview for design decisions and data boundaries.

Training flow

A training round is more than revealing an answer. The scheduler first selects due and new questions according to the configured budget. You may ask unlimited follow-up questions before submitting. Core grades only after you explicitly submit an option set and then appends the learning record. If the question bank is insufficient, Core returns a structured generation request; Codex generates a candidate and Core validates and stores it before display.

Round size, review and new-question budgets, backlog pause rules, and temporary-question lifetime are database-backed settings available from the Web admin page.

Train, ask, and review in Codex

Live demo: https://mindtrain.jianyutan.com/ (public sample statistics are available; training requires your own private instance)

Why MindTrain

Available today: Training Core, Trainer MCP, MindTrain Web, Codex Plugin, and weighted scheduling. Anki / FSRS Provider is planned.

Get started in 5 minutes

Prerequisites

• Git
• Docker and Docker Compose
• Codex CLI or Codex App for the AI-coach experience

1. Install and start MindTrain

git clone https://github.com/shigella520/MindTrain.git
cd MindTrain/deploy/core-only
cp .env.example .env

Edit .env and replace at least these two values:

POSTGRES_PASSWORD=replace-with-a-random-database-password
MINDTRAIN_BOOTSTRAP_TOKEN=replace-with-a-long-random-token

You can generate a random value with openssl rand -hex 32. MINDTRAIN_BOOTSTRAP_TOKEN protects both Codex → Trainer MCP and Trainer MCP → Core. Never commit or publish it.

docker compose up -d --build
docker compose ps

After all four containers become healthy, open:

• Web: http://127.0.0.1:4173
• Core health: http://127.0.0.1:8080/actuator/health
• MCP health: http://127.0.0.1:8787/actuator/health

PostgreSQL is not exposed to the host. Core, MCP, and Web listen on 127.0.0.1 by default.

2. Configure the Codex Plugin

Install the MindTrain Plugin:

codex plugin marketplace add shigella520/MindTrain --ref main
codex plugin add mindtrain@mindtrain

Create a new Codex task and enter:

$mindtrain configure my MindTrain instance

Provide the following when prompted:

1. MCP URL. Use http://127.0.0.1:8787/mcp locally, or your own HTTPS URL for a remote instance.
2. The MINDTRAIN_BOOTSTRAP_TOKEN from .env.

Configuration stays in your local user configuration directory and is never written to this repository. See Codex Plugin deployment for installation, upgrades, and troubleshooting.

3. Create a training domain

Before the first training session, tell MindTrain what you want to learn. A private instance can contain multiple training domains, and each domain can contain multiple root topic trees.

The simplest path is to let Codex plan a domain from your learning goal:

Use $mindtrain to create a training domain for [my learning goal]. Show me the complete topic tree first and save it only after I confirm.

Replace [my learning goal] with a concrete goal, for example: “Prepare for a Kubernetes operations interview, focusing on Pods, Deployments, Services, and troubleshooting.” If the goal is missing, MindTrain asks about the subject, scope, and desired depth before producing the tree.

If you already have learning material, point MindTrain at a local directory:

$mindtrain use /path/to/notes to create a backend-notes reference library,
organize training domains and topics, preview them, and save only after I confirm

In both flows, Codex first displays the complete domain information and topic tree. MindTrain writes it atomically to Core only after explicit confirmation. For local references, the Plugin creates a private parsing environment and full-text index in its local cache. Core never receives the original files, absolute paths, or local index. The initial PDF implementation extracts text only and does not perform OCR.

After creation, use the Web Knowledge Catalog to browse topic trees, search topics, and inspect question coverage and mastery. See Knowledge Catalog for details.

4. Start your first training session

Create a new task and enter:

$mindtrain start training

If your instance has one training domain, MindTrain selects it automatically. If it has multiple domains, Codex or Web requires you to choose one, for example: $mindtrain start training in ai-agent. A session draws questions from exactly one selected domain and never mixes domains randomly.

During any question, you can say:

What exactly does this concept mean?
Why is B incorrect?
Give me a hint without revealing the answer.
This question does not fit the topic. Give me another one.

An Attempt is created only when you explicitly submit an option set. Follow-up questions do not consume the current question.

Private cloud deployment

MindTrain targets private, single-user deployments. We recommend exposing only Web and Trainer MCP through a reverse proxy:

https://mindtrain.example.com/     -> http://127.0.0.1:4173/
https://mindtrain.example.com/mcp -> http://127.0.0.1:8787/mcp

A remotely exposed MCP endpoint must use HTTPS and a Bearer Token. Never expose PostgreSQL; Core does not need a public port either.

See Deployment and operations for Nginx, Caddy, Cloudflare Tunnel, health checks, backup and restore, upgrades, and full configuration.

Upgrade MindTrain

Upgrade the server and Codex Plugin separately. Back up PostgreSQL first: training domains, questions, attempts, and application settings live in the dat