A systematic tour of the ideas that make Cortex trustworthy: grounding, pedagogy, a clean course model, a fast player, two coaches, and the platform underneath.
The big picture
Cortex is an AI curriculum studio: a subject-matter expert turns raw material into a real, playable course. AI does the heavy lifting, but a human is always in the loop — and every AI output is grounded in the expert's own material.
The clearest mental model is two halves on one platform. First, a self-contained course platform — an admin builder and a learner player, with 8 activity types, progress tracking, and JSON import/export. Second, an AI authoring layer on top: knowledge systems, AI Compose, a knowledge map, a grounded text coach, and a realtime voice coach.
The seam between the two halves is deliberately narrow. The AI layer never writes course tables directly. Every AI flow ends by producing a portable cortex-course/1 JSON spec, which is handed to the same importCourse() a human uses. In other words, AI is a content author — not a privileged path — so everything it produces is reviewable and editable exactly like hand-authored content.
A fork, on purpose
Cortex is a fork of the Academy LMS with its own app_cortex__* tables, its own routes under /cortex, its own cortex.manage permission, and its own data client @pm/database/cortex — zero shared runtime code. The two apps can evolve independently.
The guiding principle is “the simplest robust thing that works.” Relationships between ideas are lightweight — embedding similarity plus optional manual links, not a heavy prerequisite graph. Nano-lessons are the retrieval unit, so there is no separate chunk table. And all text, embeddings, and JSON run on the existing Google Gemini stack.
Knowledge & grounding
Knowledge is organized into knowledge systems — buckets like “Leadership & People Management.” They are the trust boundary; distillation is how raw material earns its way across it.
Ingestion runs in three stages, turning a messy document into small, vetted, single-idea units.
1
Extract text
PDFs are read with unpdf, DOCX with mammoth, and transcripts are cleaned of timestamps — so the model sees clean prose, not layout noise.
2
Chunk
The text is split into roughly 2,500-word chunks so each piece comfortably fits the model’s context window.
3
Distill
Gemini breaks each chunk into nano-lessons — atomic, self-contained units of about 80–350 words, each carrying a single idea. The distillation prompt is dedup-aware and is commanded to stay faithful to the source and not invent facts. A human then reviews and accepts the proposed nano-lessons.
Every accepted node’s title, summary, and body is embedded with gemini-embedding-001 (768 dimensions, HNSW cosine index). After each write, up to five “similar” edges are recorded above a 0.62 cosine floor — lightweight relationships computed in code, no hand-drawn dependency graph required.
The knowledge map: nano-lessons as nodes, with similarity edges revealing how ideas cluster and connect.
Why grounding matters
An ungrounded language model will confidently invent plausible-but-wrong curriculum. Forcing every AI step to draw from a vetted corpus turns the model from an author of facts into a re-structurer of the expert’s facts. That single constraint is what makes a Cortex course trustworthy.
AI Compose & pedagogy
AI Compose is a wizard with a human decision at every gate — grounded in your knowledge, augmented by fact-checked web research when that knowledge is thin, and shaped by pedagogy, not just facts.
The flow moves from a one-line idea to a real draft course, checkpoint by checkpoint.
1
Suggest systems
AI proposes which knowledge systems to use, filtered to real ids; a human confirms the selection.
2
Suggest pedagogy
AI recommends a teaching approach from the catalog (you can override it).
3
Research gaps (when thin)
If the selected knowledge covers the idea poorly, Compose researches the open web: an LLM expands the topic into several precise Brave Search queries, an LLM synthesizes the hits into atomic nano-lessons, and a second LLM pass fact-checks each against its sources — dropping unsupported claims. The vetted results are embedded into a shared Web Research system, becoming first-class, reusable knowledge that grounds the rest of generation. The web only fills gaps; your knowledge is preferred, and the whole path is fail-soft — no key or any error simply means no extra grounding, never a broken course.
4
Generate outline
The idea is embedded as a retrieval query; the top ~16 nano-lessons are retrieved and injected as a numbered grounding block. The model returns sections → items, each tagged with the node_ids it draws from.
5
Iterate
Rewrite the whole outline or regenerate a single item — each pass re-retrieves fresh grounding so edits stay anchored.
6
Generate course
Every item is expanded to full content, assembled into a cortex-course/1 spec, and handed to importCourse(), which creates a real draft.
Expansion is engineered to be robust so the course always assembles — bad items simply arrive as drafts to fix, rather than failing the whole run:
Only text, quiz, flashcards, matching, and sequencing are AI-generatable; asset types (video, embed, download) degrade to draft placeholders.
Failed retrieval degrades to ungrounded content rather than erroring out.
Text uses a markdown prompt (no JSON envelope), so a reading can’t corrupt on a parse hiccup.
Structured types are coerced by zod schemas that never throw; any invalid published activity is demoted to draft.
Expansion runs with bounded concurrency (4) to stay within limits.
A 13-approach pedagogy catalog — Gagné, 5E, Explicit Instruction, Rosenshine, Merrill, Kolb, UbD, PBL, and more — injects a concrete teaching directive into the outline and expansion prompts.
Why grounded + pedagogy-shaped beats freeform
Grounding fixes factual drift (and honestly names coverage gaps when the knowledge is thin). Pedagogy fixes pedagogical mush: measurable objectives, hook-first sections, an early worked example, no more than 3–4 new ideas per chunk, a check after every reading, at least 40% active practice, and scenario-based quizzes with explanations.
The course model
Underneath the AI layer is a plain, well-shaped course platform — the same one a human authors by hand.
The data is a three-level tree: courses → sections → activities, plus enrollments → activity_progress. Activities carry a denormalized course_id so course-wide queries and the progress rollup can skip a join, and each activity’s slug is unique per course (it drives the player URL). New activities start as draft; only published courses and activities reach learners.
8 activity types
text, video, embed, quiz, download, flashcards, matching, sequencing — defined in a pure module (activity-types.js + schemas.js) so the same metadata, validation, and quiz grading run in the editor, the save path, and the player.
Zod as the source of truth
The zod schemas validate content before save and publish, and they coerce or repair AI output into a valid shape — one definition, trusted everywhere.
One definition, three consumers
Because the type metadata, validation, and grading live in one pure module, the editor, the save path, and the player can never drift out of sync — and AI output is held to exactly the same bar as hand-authored content.
The fast player
The learner player lives at /cortex/[courseSlug]/[activitySlug], with a persistent sidebar of sections, a progress bar, and completion ticks. It is built to feel instant.
The performance goal is simple to state: the first lesson is interactive immediately, while the rest of the course loads quietly behind the scenes. Four moves make that true.
1
Ship small first
The page sends only a lightweight curriculum (titles, types, slugs) for the sidebar, plus the one current activity’s full body — so first paint is tiny.
2
Warm the cache in the background
On mount, a single background request to GET /api/cortex/courses/[id]/content streams every remaining lesson’s body into an in-memory cache.
3
Navigate instantly
A sidebar click, Next/Prev, or the arrow keys become an instant client-side swap via history.pushState — no server round-trip.
4
Fall back gracefully
A cache miss, deep link, or hard refresh falls back to normal server navigation, covered by an instant loading skeleton.
Progress is just as direct: each completion POSTs to /api/cortex/progress, a database trigger rolls the completed-vs-required count up onto the enrollment, and gated activity types auto-complete on success.
The coaches
Two coaches share one thesis — answer only from the knowledge — but serve different people in different modes.
Text coach (authors)
Lives in the admin. It runs retrieval over the chosen knowledge systems, streams its answer, and cites the nano-lessons it used. It answers only from the knowledge, and says so plainly when a question falls outside it.
Voice coach (learners)
Lives in the player as a speech-to-speech coach over OpenAI Realtime (WebRTC). A short-lived token is minted server-side at /api/cortex/coach/realtime/session, and the coach runs the same retrieval via /api/cortex/coach/realtime/search — grounded in the course plus the whole knowledge base.
The one place a second provider appears
The voice coach is the only feature that uses OpenAI. Everything else in Cortex — text, embeddings, JSON — runs on the Gemini stack. Same grounding thesis, either way.
Platform foundations
Cortex doesn't reinvent the plumbing — it rides on the monorepo's shared platform patterns.
App Registry
One declaration drives the home grid, route gating, and the admin Apps page. Cortex has a status (draft / live) and an access level (public / protected).
Frictionless auth
Anonymous users interact freely. On an auth-required action, an AuthModal opens over the intact work and auto-continues — never a redirect to /login.
RBAC
The server is the boundary. cortex.manage gates the studio; the client-side mirror is UX-only.
API envelope
Every route returns one shape: ok(data) on success, fail(code, message) on error.
Three Supabase clients
A browser client (RLS applies), a cookie-bound server client, and a service-role admin client that is server-only.
RLS & migrations
Row-level security is on every table. Migrations are applied over the Supavisor pooler — the Supabase CLI is not used.
AI model registry
A configured fallback chain over the Gemini stack keeps AI calls resilient.
