🧠 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

👉 daily-english-mission-ten.vercel.app 👈

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

Daily English Mission

---

🏛️ 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.