Mnemosyne — Architecture

The humanistic learning and cultural intelligence platform

Mnemosyne is the Oshun domain responsible for every facet of lifelong humanistic study: spaced repetition, language acquisition, classical pedagogy, art history, mythology, cultural heritage preservation, history, and archaeology. The name comes from the Greek Titaness of memory — mother of the nine Muses — which captures the domain's mission: making the memory-intensive work of humanities study tractable and rewarding over years.

The domain lives entirely in libs/mnemosyne/ within the Oshun Nx monorepo. It ships as 19 independent TypeScript libraries under the @mnemosyne/<name> naming convention, each declared private: true so they are consumed only through an orchestrating application layer. There is no database, no HTTP server, and no network client inside the domain — every package is a pure, in-memory computation library whose only runtime dependency is zod.

This architecture document describes how those 19 packages are organized, how they relate to one another, and what the most important packages contain.

Library Organization#

The 19 packages span three broad concerns: a core learning science foundation (core, knowledge-graph, experience, gamification-plus), a language and linguistics cluster (polyglot, phonetics, pronunciation, writing, linguistics, classical-tools, philology, immersion, community), and a humanities knowledge cluster (aesthetics, mythology, heritage, temporal, rhetoric, platform).

libs/mnemosyne/
├── core/              # @mnemosyne/core           — Foundation: memory science, SRS, assessment, knowledge graph, AI
├── platform/          # @mnemosyne/platform       — Data I/O, external integration, multi-platform, content management
├── polyglot/          # @mnemosyne/polyglot       — Multi-language engine: vocabulary, grammar, CEFR, reading
├── linguistics/       # @mnemosyne/linguistics    — Linguistic analysis tools
├── phonetics/         # @mnemosyne/phonetics      — IPA, phoneme inventory, minimal pairs, tone systems, prosody
├── pronunciation/     # @mnemosyne/pronunciation  — Pronunciation training and assessment
├── writing/           # @mnemosyne/writing        — Writing systems and script pedagogy
├── classical-tools/   # @mnemosyne/classical-tools — Alpheios-style reader and DCC-style annotated texts
├── philology/         # @mnemosyne/philology      — Etymology, semantics, stylometrics, corpus analysis
├── rhetoric/          # @mnemosyne/rhetoric       — The Trivium: grammar, logic, rhetoric; disputation, oratory
├── aesthetics/        # @mnemosyne/aesthetics     — Art history and visual analysis
├── mythology/         # @mnemosyne/mythology      — Comparative religion, folklore, sacred text studies
├── heritage/          # @mnemosyne/heritage       — Cultural heritage preservation and digital archives
├── knowledge-graph/   # @mnemosyne/knowledge-graph — Domain knowledge graph operations
├── temporal/          # @mnemosyne/temporal       — History, archaeology, anthropology
├── immersion/         # @mnemosyne/immersion      — Comprehensible input and immersion infrastructure
├── experience/        # @mnemosyne/experience     — Adaptive learning, gamification, social, analytics
├── gamification-plus/ # @mnemosyne/gamification-plus — Advanced league/competition/streak/seasonal systems
└── community/         # @mnemosyne/community      — User-generated content, peer learning, forums

Dependency Layering#

Understanding how these packages relate to each other is important for knowing where to add new code and where to look for shared types. In practice, the packages are almost entirely independent: each package's package.json declares exactly one runtime dependency — zod — and vitest as a dev dependency. The only cross-package dependency that exists in code is @mnemosyne/polyglot importing shared types (CEFRLevel, LearnerId) from @mnemosyne/core.

@mnemosyne/core              Foundation: memory science, SRS, IRT/CAT,
                             knowledge graph, AI infrastructure.
                             Runtime dependency: zod only.

@mnemosyne/polyglot          Imports type-only symbols from @mnemosyne/core.

all other packages           No @mnemosyne/* dependency. Each is a
(17 packages)                self-contained library depending only on zod —
                             including phonetics, linguistics,
                             classical-tools, philology, rhetoric,
                             aesthetics, mythology, heritage, temporal,
                             knowledge-graph, pronunciation, writing,
                             immersion, experience, gamification-plus,
                             community, and platform.

@mnemosyne/core is the conceptual foundation — it defines the shared learner / SRS / assessment model — but only @mnemosyne/polyglot currently imports from it. The remaining packages each define their own local types where needed (for example @mnemosyne/phonetics and @mnemosyne/classical-tools each declare their own LanguageCode / PartOfSpeech types rather than importing core's). This means there is no import cycle risk, but also no enforced layering today. A future refactor that wires all domain packages onto @mnemosyne/core would introduce the strict layer hierarchy this document otherwise implies.

Core Package Architecture (@mnemosyne/core)#

@mnemosyne/core is the foundation package and contains the most critical algorithms. It is organized into five source files, each covering a distinct sub-domain of learning science:

core/src/
├── types.ts             — All shared type definitions, enums, constants
│                           (LearnerProfile, SRSCard, CEFRLevel, IRTParameters,
│                            KnowledgeItem, LearningPath, Curriculum, Feedback, etc.)
├── memory-science.ts    — SRS algorithms: Ebbinghaus, SM-2, FSRS, HLR, LECTOR
│                           Cognitive load, interleaving, circadian, sleep-aware scheduling
├── knowledge-graph.ts   — KnowledgeGraph class, graph queries, similarity calculation
├── assessment.ts        — IRT (1PL/2PL/3PL), CAT, rubric evaluation, portfolio,
│                           peer assessment, self-assessment, certification, proctoring
├── ai-infrastructure.ts — LLM client types, prompt templates, RAG pipeline,
│                           Socratic dialogue, hint sequences, misconception detection,
│                           AQG, cloze generation, semantic cards, learning analytics
└── index.ts             — Public API barrel export (all types, values, and classes)

Memory Science Module — Key Exports#

The memory science module implements several distinct algorithms for scheduling reviews, each making different assumptions about how memory works. The table below lists each public function, its type, and what it computes.

Assessment Module — Key Exports#

The assessment module covers both psychometric measurement (IRT and CAT) and richer qualitative approaches (rubrics, portfolios, peer review). The classes represent stateful workflows; the functions are pure computations.

Polyglot Package Architecture (@mnemosyne/polyglot)#

@mnemosyne/polyglot is the multi-language mastery engine. Unlike the single classical-tools.ts monolith, it splits its surface area across ten source files so each language-learning concern can be read and modified independently.

polyglot/src/
├── language-database.ts      — Language metadata registry (ISO 639 codes, families, typology)
├── vocabulary.ts             — VocabularyItem, word families, frequency lists, cognates
├── grammar.ts                — GrammarRule, paradigms, syntactic patterns, exercises, contrastive analysis
├── reading.ts                — Text difficulty analysis, comprehension skills and questions, reading metrics
├── skills-extended.ts        — Extended CEFR skill descriptors and proficiency assessment
├── vocab-grammar-extended.ts — Thematic modules, mnemonic keywords, vocabulary coverage analysis
├── cefr.ts                   — CEFR/ILR/ACTFL descriptors and cross-framework mapping
├── phonetic.ts               — Word→IPA transcription, phonetic similarity, language detection
├── frequency-bands.ts        — Corpus frequency-band profiling (data/ JSON for en, es)
├── language-resources.ts     — Capitalization, punctuation, and other per-language orthographic resource features
├── types.ts                  — Shared type definitions
└── index.ts                  — Public API barrel export

Classical Tools Package Architecture (@mnemosyne/classical-tools)#

@mnemosyne/classical-tools supports assisted reading and annotation of ancient texts in seven languages. The ClassicalLanguage union names those languages, and the package provides the parsing, display, and progress-tracking primitives a reading environment needs.

Classical languages are represented by the ClassicalLanguage union (Latin, Ancient Greek, Sanskrit, Classical Arabic, Biblical Hebrew, Old Church Slavonic, Classical Syriac). The core abstractions implemented in classical-tools.ts include:

• MorphologicalForm / MorphologicalAnalysis plus describeMorphForm and createMorphologicalAnalysis — Alpheios-style morphological parsing that identifies every grammatical attribute of a clicked word in context.
• Paradigm builders: buildLatinFirstDeclensionParadigm, buildGreekThematicVerbParadigm (ParadigmTable / ParadigmCell) — for generating the full conjugation or declension table of any word form.
• Dictionary lookups: DictionaryEntry, DictionarySource, buildDictionaryLookupUrl — constructing URLs to external lexicons (Lewis and Short, LSJ, Monier-Williams).
• Treebank syntax: TreebankToken, TreebankAnnotation, SyntacticRelation, getTokenDependents, getTokenPath — dependency-tree navigation following the AGDT/PROIEL treebank format.
• DCC-style annotated reading: TextAnnotation, AnnotationLayer, createTextAnnotation, generateStudyGuide, generateQuizFromAnnotations, collaborative annotation editing, and ClassicalReadingProgress / recordWordLookup progress tracking.
• Passage difficulty: assessPassageDifficulty, PassageDifficultyAssessment.

Platform Package Architecture (@mnemosyne/platform)#

@mnemosyne/platform is a pure interchange-and-integration library. Its role is to let a consuming application move data in and out of external tools (Anki, LMS systems, library catalogs, museum APIs) and to declare the REST surface that a hosting application could expose. It builds request URLs and parses payloads, but performs no network I/O itself.

parseAnkiDeck operates on a simplified Anki deck JSON export (an .apkg deconstruction), not on the binary .apkg archive. The package does not implement a running server, EPUB/PDF parsing, or TTS/STT.

Key Design Patterns#

Algorithm-First Implementation#

The Mnemosyne domain is built around domain-correct algorithms rather than generic CRUD operations. @mnemosyne/core contains genuine implementations of Ebbinghaus forgetting curves, SM-2 intervals, FSRS v4 stability/difficulty updates, Half-Life Regression, LECTOR semantic scheduling, IRT 1PL/2PL/3PL probability models, full CAT loops, and circadian-phase scheduling. All core functions are pure and deterministic wherever possible, which makes them straightforward to unit-test against known correct outputs. Bayesian Knowledge Tracing (BKT) and Deep Knowledge Tracing (DKT) are the exception — they live in @mnemosyne/experience, not in @mnemosyne/core, because they require stateful learner modelling rather than per-card computations.

Branded ID Types#

All entity IDs use branded types (TypeScript nominal typing) to prevent accidental assignment between different entity types. For example, a LearnerId and a SRSCardId are both strings at runtime, but the TypeScript type system treats them as incompatible. @mnemosyne/core defines a Brand<T, B> helper and applies it to twelve ID types:

type Brand<T, B extends string> = T & { readonly __brand: B };
type LearnerId = Brand<string, 'LearnerId'>;
type KnowledgeItemId = Brand<string, 'KnowledgeItemId'>;
type SRSCardId = Brand<string, 'SRSCardId'>;
// … KGNodeId, KGEdgeId, LearningPathId, CurriculumId, ExerciseId,
//    AssessmentId, AchievementBadgeId, TestItemId, DeckId

Bloom's Taxonomy Integration#

The AI infrastructure module integrates Bloom's six-level taxonomy (BLOOM_LEVELS, BLOOM_ACTION_VERBS) for question generation and scaffolding. Bloom's taxonomy orders cognitive tasks from recall at the bottom through creation at the top. Scaffolding levels (SCAFFOLDING_LEVELS) separately control how much AI assistance is provided for a given interaction, ranging from full scaffolding for beginners down to none for independent learners.

Circadian and Sleep-Aware Scheduling#

Scheduling algorithms in @mnemosyne/core/memory-science.ts account for the fact that memory consolidation is not uniform across the day. sleepAwareSchedule adjusts review intervals to avoid scheduling difficult items immediately before sleep (where consolidation occurs) or during predicted low-performance circadian phases. circadianEfficiency provides a 0–1 multiplier that drops to 0.1 during sleep hours.

Modular Gamification#

Gamification is deliberately split across two packages to keep core motivational mechanics separate from the more advanced competitive layer:

• @mnemosyne/experience owns foundational gamification: XP, levels, badges, leaderboards, a virtual-currency shop, and avatars — plus adaptive-learning models including Bayesian Knowledge Tracing (BKT) and Deep Knowledge Tracing (DKT).
• @mnemosyne/gamification-plus adds the Duolingo-style competitive layer: six-tier leagues with weekly promotion/demotion, streak freezes and insurance, seasonal events, community goals, and team leagues. It is a self-contained library with no code dependency on @mnemosyne/experience.

Technology Stack#

Mnemosyne is implemented entirely as pure TypeScript libraries. No package contains a database schema, cache client, or LLM provider binding — each package's only runtime dependency is zod. This design means any consuming application can inject whatever infrastructure it needs without the domain libraries prescribing a particular stack.

Persistence (PostgreSQL, Redis), embedding services, and LLM provider wiring are the responsibility of a consuming application and are not part of this domain.

Cross-Domain Boundaries#

Mnemosyne's packages declare no @oshun/*, @sophia/*, or @metis/* dependency. This boundary is intentional: the domain is a library of pure learning-science and humanities-knowledge functions, not a service that calls out to other Oshun domains.

If a consuming application wants to combine Mnemosyne's learning infrastructure with, say, Sophia's knowledge enrichment or Metis's subject-matter content, it assembles those dependencies itself. The data that would cross the boundary is typically a LearnerProfile or a KnowledgeItem carrying a domain identifier — the consumer maps those into whatever Sophia or Metis expects. Nothing inside libs/mnemosyne/* makes that call.

Phase Reference#

Mnemosyne libraries are implemented across phase 39 of the Oshun TODOS.md migration plan. The table below maps phase sub-sections to the libraries they cover.