🧠 Engineer Learning OS
The Evidence-Grounded, Local-First Learning Operating System for Software Engineers
🎬 Watch the 100-second presentation — French voice-over, captions included
🚀 Live Demo
No sign-up required — your learning data is stored locally in your browser (IndexedDB). Optional cloud sync only runs after you explicitly sign in.
💡 What is Engineer Learning OS?
Traditional e-learning platforms rely on passive video watching, superficial badges, and arbitrary completion percentages that fail to build real engineering intuition.
Engineer Learning OS is a local-first platform designed to turn engineering course materials and technical challenges into verifiable mastery. It combines zero-hallucination document extraction, grounded academic quizzes, spaced error retrieval, and integrated technical English into a distraction-free modular monolith — and it can follow you to your phone through a local AI tutor (Hermes Agent over MCP) on Telegram and WhatsApp.
⚡ Core Philosophy: No fake progress. Every competency level (NOT_SEEN ➔ PRACTICED ➔ VERIFIED) is derived purely from auditable, reproducible evidence records.
⚡ Traditional EdTech vs. Engineer Learning OS
| Feature | ❌ Traditional EdTech / LMS | ✅ Engineer Learning OS |
|---|
| Progress Metric | Arbitrary percentages (e.g. "78% completed") | Evidence-derived competency states backed by auditable attempts |
| Quiz Grounding | Generic LLM hallucinated questions | Exact citation matching & deterministic page anchoring |
| Error Handling | "Wrong answer, try again" | Pattern detection & automated spaced retrieval scheduling |
| Document Processing | Proprietary cloud lock-in | Local PDF.js + offline Docling extraction pipeline |
| Privacy & Storage | Cloud tracking, vendor data harvesting | IndexedDB authority with optional RLS-protected sync of explicitly allowed metadata |
| Language Practice | Disconnected flashcard drills | English-in-the-Loop with audio recordings & technical feedback |
✨ Key Features
📑 1. Grounded Academic Workspace (academic-workspace)
- Deterministic Grounding: Ingests real course slides (e.g., Computer Networking INF3050) and validates quizzes strictly against exact text segments and page numbers.
- Adaptive Remediation: If a question is missed, learners are offered contextual remediation: targeted explanations, conceptual flashcards, or section re-ingestion.
🔍 2. Dual Document Extraction Engine (document-extraction)
- Fast Text Ingestion: Powered by Mozilla PDF.js (6.2) for fast local parsing.
- Deep Structural Parsing: Powered by Docling (2.121) for complex multi-column layouts, tables, and mathematical formulas via a sandboxed local process bridge.
- Zero Cloud Leak: Enforces
HF_HUB_OFFLINE=1 and TRANSFORMERS_OFFLINE=1.
🔄 3. Spaced Error Retrieval (review-engine)
- Error Pattern Memory: Tracks meaningful conceptual mistakes (e.g., TCP vs UDP confusion, PDU encapsulation hierarchy, CSV delimiter edge cases).
- Spaced Review Loop: Automatically schedules overdue items with dynamic intervals based on retrieval success.
🎙️ 4. Technical English in the Loop (technical-english)
- Microphone & Audio Store: In-browser audio recording with local blob persistence.
- Concise Feedback: Provides tightly bounded lexical and grammatical feedback (capped at 3 actionable points) without hallucinating progress.
- On-Device Speech Recognition (opt-in): Whisper runs inside the browser (WebAssembly) to transcribe your spoken English and score your pronunciation word by word. Your voice is never uploaded; the only network access is a one-time ~80 MB download of the open-source model from Hugging Face.
🏭 5. Industrial Problem Scenarios (professional-scenarios)
- Realistic Workplace Cases: Scenario solving based on synthetic industrial telemetry data.
- Multidimensional Rubrics: Validates factual accuracy, hypothesis vs fact separation, and actionable next steps.
- AI-Assistance Tagging: Explicitly separates independent student writing from AI-assisted text.
🧭 6. Evidence-Informed Pedagogical Policy (scientific-pedagogy)
- Inspectable Decisions: Six scientific decision records connect claims to legal sources, limitations, and measurement plans.
- Context-Aware Practice: Confidence calibration, bounded assistance, semantic self-explanation, transfer evidence, and curated concept relations inform the next action.
- Canonical Shadow Projection: The policy reads privacy-safe IndexedDB event metadata without rewriting EventIds or independently awarding mastery.
📚 7. Learning Studio (learning-studio) — /studio
- Your own courses, on your device: import PDF, Markdown or text files; text is extracted with PDF.js in the browser, and scanned PDFs are read by on-device OCR (tesseract.js, French model vendored — no upload).
- Cited answers only: questions are answered with sentences quoted from your sources (page or section), or the Studio says the sources do not contain the answer. A Socratic mode gives graduated hints instead.
- Study material from the sources: flashcards, quizzes, revision sheets, mind maps, prerequisite paths, an audio overview read by a local voice, annotations, and timed mock exams — all marked
DERIVED_MATERIAL, never mastery.
- Scheduling: Leitner ladder by default, with an optional FSRS-4.5 scheduler (evaluated by replay on real public review logs, where it beat Leitner on log-loss).
- Programme import with quality audit: a pedagogical base export (courses, exercises, flashcards) becomes a course map; an automatic audit blocks guessable multiple-choice banks (correct answer always the longest, generic distractors) and copy-pasted flashcards.
- Offline: a service worker keeps the app usable without a network.
🗣️ 8. Daily English Mission (daily-english) — /daily-english
- 150 words in 5 packs (core, networking, cybersecurity, meetings, career) with Leitner spaced review and a daily mission.
- Hand-written professional roleplays (stand-up, incident report, apprenticeship interview) evaluated locally, plus on-device Whisper transcription and a full local backup / restore.
🤖 AI Agent Integration (Hermes + MCP)
Engineer Learning OS ships a local Model Context Protocol server (mcp/elos-server.ts) so a personal agent such as Hermes Agent can tutor you — including from Telegram and WhatsApp on your phone.
| Tool | What the agent can do |
|---|
elos_ask_sources | Answer only with quoted sentences from your course files (page citations), or a Socratic question with hints |
elos_study_pack | Flashcards, quiz, revision sheet, audio overview script, prerequisite paths |
elos_course_map | Programme map: objectives, prerequisites, worked example, analogy, frequent mistakes, quality audit |
elos_course_exercise | Multiple-choice questions built from your own course files for a chapter, with citations; answer revealed only after your attempt; missed questions come back first (retry) |
elos_today · elos_progress · elos_exam_plan | What to study today, progress, exam countdown with spaced sessions (read-only snapshot) |
elos_correct_english · elos_roleplay · elos_vocabulary | Local English correction, roleplays, vocabulary |
elos_compare_schedulers | Replay review logs: FSRS-4.5 vs Leitner |
- Daily rhythm: a morning coach at 8:00 and an evening review at 19:00 (missed questions to redo) are delivered to Telegram/WhatsApp by Hermes cron jobs — deterministic messages, no model involved.
- Two-way, read-only by design: the app shares a minimal snapshot (
elos-state.json); the agent writes back practice counts per chapter (elos-practice.json), shown in the app as assisted practice that never changes a mastery level.
- Guard rails: course files are read only from
ELOS_SOURCES_DIR; knowledge-private/, secrets and path traversal are refused; answer keys are kept outside the folder the agent browses (npm run mcp:split-base); scanned PDFs are OCR'd on the Mac with Apple Vision and cached outside the shared folder.
Setup, privacy notes and cron recipes: docs/integrations/HERMES.md.
🖼️ Product Tour
| Daily Dashboard | Learning Paths |
|---|
| |
| Multi-Subject Academic Space | Evidence-Based Progress |
|---|
| |
🏛️ Architecture
The codebase follows a Clean Modular Monolith architecture. Domain modules are decoupled from Next.js, UI frameworks, and storage adapters.
flowchart TD
subgraph UI ["🖥️ Presentation Layer (Next.js 16 / React 19)"]
Dashboard["/ (Today Dashboard)"]
Learn["/learn (Missions & Scenarios)"]
Subjects["/subjects (Academic Courses)"]
Sources["/sources (Provenance Explorer)"]
Review["/review (Spaced Retrieval)"]
Evidence["/evidence (Audit Trail)"]
Progress["/progress (Competency Matrix)"]
Studio["/studio (Learning Studio)"]
English["/daily-english (Missions & Roleplays)"]
end
subgraph Agent ["🤖 Local Agent Bridge"]
MCP["mcp/elos-server.ts\n(MCP stdio, 11 tools)"]
Hermes["Hermes Agent\n(Telegram · WhatsApp · cron)"]
end
subgraph Core ["🧠 Pure Business Modules (src/modules/)"]
AW["academic-workspace\n(Grounded Quizzes & Remediation)"]
SE["source-engine\n(Canonical Sources & Bundles)"]
DE["document-extraction\n(PDF.js & Docling Bridge)"]
RE["review-engine\n(Error Pattern Memory)"]
LR["learning-records\n(Competency Derivation)"]
PS["professional-scenarios\n(Industrial Cases)"]
TE["technical-english\n(Audio Evidence)"]
DM["deep-mastery\n(Mental Model Invariants)"]
MR["mission-runtime\n(Active Time & Session Engine)"]
SP["scientific-pedagogy\n(Evidence-Informed Policy)"]
LS["learning-studio\n(Cited Answers, Exams, Programme Audit)"]
SN["learner-snapshot\n(Agent Bridge & Coach)"]
end
subgraph Infra ["🔌 Infrastructure & Local Storage"]
PDF["PDF.js 6.2 (Apache-2.0)"]
Docling["Docling CLI 2.121 (MIT)"]
Zustand["Zustand LocalStore (Browser)"]
IndexedDB["IndexedDB (Canonical History)"]
SQLite["SQLite / Prisma 6"]
WebAudio["Web Audio / MediaRecorder API"]
end
UI --> Core
Core --> Infra
Hermes --> MCP
MCP --> Core
🚀 Quick Start
Prerequisites
- Node.js
>= 24 (a clean-clone run was verified with Node 26.8.1)
npm (the committed package-lock.json is the reference lockfile)
1. Clone & Install
git clone https://github.com/eulogep/Engineer-Learning-OS.git
cd Engineer-Learning-OS
npm ci
2. Run the Development Server
npm run dev
Open http://localhost:3000 in your browser. The application is local-first: learner state lives in the browser, so no database or account is required to start.
3. Check the Project
npm run typecheck # tsc --noEmit
npm run lint # eslint
npm test # node:test suites, no extra flag needed
npm test runs the unit and integration suites with Node's built-in test runner. A small resolver (tests/register-loader.mjs) is registered automatically, so the command works as written from a fresh clone.
4. Optional: connect a local agent
npm run mcp:elos # MCP server over stdio (see docs/integrations/HERMES.md)
npm run mcp:ocr # pre-OCR scanned PDFs on macOS (Apple Vision), cached locally
npm run mcp:split-base -- <base> <private dir> # move a pedagogical base's answer key out of the shared folder
5. Build for Production
npm run build
The build creates a standalone Next.js server under .next/standalone.
Sample data
The semester registry (src/modules/current-semester/registry.ts) and the source index (knowledge/index.json) ship with placeholder data. Real course planning and the list of your own documents stay in ignored, local-only files and are never committed.
📦 Operational Modules Map
src/modules/
├── academic-workspace/ # Course registry, grounded quiz validation, adaptive remediation
├── source-engine/ # Canonical vs derived source records, provenance graph, mission bundles
├── document-extraction/ # Unified extraction pipeline (PDF.js adapter + Docling local bridge)
├── learning-history/ # Canonical IndexedDB event history, recovery, and guarded metadata sync
├── learning-records/ # Immutable evidence ledger & deterministic competency derivation
├── review-engine/ # Error signal detection, error patterns, spaced retrieval engine
├── professional-scenarios/ # Synthetic industrial cases & multidimensional rubrics
├── deep-mastery/ # Deliberate practice on fundamental invariants (CSV, encodings)
├── scientific-pedagogy/ # Evidence-traceable scheduling, assistance, calibration, transfer policy
├── technical-english/ # Spoken/written technical English & audio evidence persistence
├── learning-studio/ # Source library, cited answers, OCR import, mock exams, programme audit, chapter practice
├── learner-snapshot/ # Agent snapshot, practice summary from the agent, morning & evening coach messages
├── daily-english/ # 150-word vocabulary, Leitner review, roleplays, local correction, backup
├── local-speech/ # On-device Whisper transcription & pronunciation feedback
└── mission-runtime/ # Multi-step interactive mission runner & active time tracking
🗺️ Application Routes
| Route | View | Purpose |
|---|
/ | Aujourd’hui | Daily priority overview, active missions, and due reviews |
/learn | Apprendre | Learning path catalog (Excel Foundations, Technical English, Deep Mastery, Industrial Scenarios) |
/subjects | Matières | Multi-subject academic portal (Computer Networking INF3050 pilot) |
/sources | Sources | Canonical source catalog, license classifications, and provenance graph |
/review | Réviser | Spaced retrieval session tackling recorded error patterns |
/evidence | Preuves | Auditable chronological evidence stream of learner attempts |
/progress | Progression | Honest competency graph derived strictly from verified evidence |
/daily-english | Daily English | Daily interactive speaking and vocabulary practice |
/daily-english/roleplay | Roleplays | Professional English roleplays evaluated locally |
/studio | Learning Studio | Your own course files: cited answers, flashcards, quizzes, mock exams, audio overview |
/data | Données | Backup / restore and the local agent (Hermes) bridge with practice done on your phone |
/presentation | Présentation | 100-second product video with captions |
🛡️ Privacy, Security & Data Safety
- 🔒 Bounded data flow: Proprietary documents, internal spreadsheets, private audio, and credentials stay outside Git and remote sync; only metadata classified
SYNC_ALLOWED can enter the guarded outbox.
- 🧱 Local automation is opt-in: the NotebookLM browser-automation bridge (
POST /api/notebooklm/execute) answers 404 and starts nothing unless ELOS_NOTEBOOKLM_AUTOMATION=ENABLED is set in the server environment. Even then it only accepts same-origin JSON requests addressed to localhost, and it refuses hosted platforms and proxied requests. Never enable it on a deployed instance.
- 🧪 Synthetic Fixtures Only: All automated tests use 100% synthetic, non-sensitive fixtures (
TRAINING_SYNTHETIC).
- 🤖 Agent boundaries: the MCP server only reads the course folder you configure and refuses private folders and secrets. Anything it returns is sent by the agent to its model provider — the snapshot it shares never contains your sentences, transcriptions, notes or answers.
- 🌐 Offline by Default: Document extraction, audio recording, quiz grading, and competency derivation run entirely on your local machine without mandatory network calls.
🏷️ GitHub Topics & Discovery Tags
learning-os, local-first, privacy-first, edtech, deliberate-practice,
spaced-repetition, fsrs, competency-tracking, technical-english,
english-learning, mcp, model-context-protocol, ai-tutor, ocr, pdfjs,
nextjs, react, typescript, indexeddb, cybersecurity-education
🤝 Contributing
Engineer Learning OS is a proprietary project. External code contributions are not accepted at this time.
Bug reports and feedback are welcome through GitHub issues; for partnerships or licensing, contact @eulogep.
📄 License
Copyright © 2026 Euloge Mabiala. All rights reserved. This software is proprietary; see LICENSE.
Versions up to and including v0.3.0 were published under the MIT License and remain available under those terms.
