# Mnemosyne — Systems Deep Dive

> The `libs/mnemosyne/` area: nineteen Nx domain libraries that together form a
> humanistic-learning and cultural-intelligence platform — spaced-repetition
> memory science, psychometric assessment, and deep subject-matter engines for
> languages, philology, history, mythology, art, and heritage.

## What this area is

Mnemosyne (the Greek titaness of memory) is Oshun's **learning and cultural
knowledge** product. The directory is not one package but **nineteen separate Nx
libraries**, each tagged `scope:mnemosyne`, `layer:domain`, `type:lib`, and each
exported under the `@mnemosyne/*` npm scope. Every library is a real, heavily
implemented TypeScript module — the smallest substantive source file is over a
thousand lines and the largest (`linguistics`) is ~6,500 — built around
domain-specific algorithms and curated reference datasets rather than CRUD
scaffolding. None of the nineteen is an empty `.gitkeep` placeholder; all carry
working `src/` implementations with co-located `*.test.ts` suites.

The libraries map onto a large product specification (the section numbers `39.x`
that head most files, e.g. art history is `39.7`, comparative religion `39.9`,
the classical trivium `39.8`). At the centre sits `@mnemosyne/core`
(`libs/mnemosyne/core/src`), the foundation: it owns the branded-ID type system
(`core/src/types.ts`), the memory-science schedulers (Ebbinghaus, SM-2, FSRS v4,
half-life regression in `core/src/memory-science.ts`), Item-Response-Theory and
Computer-Adaptive-Testing psychometrics (`core/src/assessment.ts`), an in-memory
knowledge graph (`core/src/knowledge-graph.ts`), and an AI/ML infrastructure
layer (`core/src/ai-infrastructure.ts`) that is explicitly designed to run with
**or without** a live LLM behind the injectable `LLMProvider` seam.

The other eighteen libraries are subject-matter engines that build on those
primitives. They cluster into a **language family** — `linguistics`,
`philology`, `phonetics`, `pronunciation`, `polyglot`, `classical-tools`, and
`writing` — and a **culture / humanities family** — `temporal` (history,
archaeology, anthropology), `rhetoric` (the trivium), `mythology`, `aesthetics`
(art history), `heritage` (cultural-heritage preservation), and
`knowledge-graph` (semantic/linked-data infrastructure). A third
**learning-experience** cluster — `experience`, `immersion`, `community`,
`gamification-plus`, and `platform` — provides the pedagogy, social, and
integration layers that wrap the subject matter into a usable product.

Each library is internally organised by spec section using banner comments, and
most expose a single flat `src/index.ts` barrel that re-exports one
implementation module (e.g. `aesthetics/src/index.ts` → `aesthetics.ts`).
`core`, `phonetics`, and `polyglot` are larger and split their surface across
several modules behind the barrel.

## How it fits the wider system

These are bottom-of-the-graph domain libraries: they depend on `@mnemosyne/core`
for shared types and on each other across the language cluster, but they hold
the authoritative reference data and algorithms a Mnemosyne service or UI
composes. The boundary is deliberate — the engines are pure and largely
deterministic (scoring formulas, paradigm builders, graph traversals, curated
databases), so the same call produces the same result on any caller. Where
genuine external intelligence is needed, the seam is explicit and honest rather
than faked: `core`'s `LLMProvider` interface carries an `isAvailable()` check
and the AI layer falls back to algorithmic/template generation when no provider
is wired, and `pronunciation` documents that real phoneme boundaries arrive from
an ASR/forced aligner while its scoring functions compute deterministically over
the supplied assessment structures.

Consumers (Mnemosyne BFF/services, web shells, agent loops) import the
`@mnemosyne/*` barrels to drive review scheduling, adaptive assessment, content
analysis, and the subject-matter tooling. Cross-library composition is real:
`polyglot`'s vocabulary tools document that word-segmentation should be done via
`@mnemosyne/philology` first; the language libraries share CEFR conventions; and
`core`'s knowledge-graph and `knowledge-graph`'s RDF/linked-data layer cover
distinct concerns (in-memory prerequisite graphs vs. CIDOC-CRM / SPARQL /
JSON-LD publishing). Walk the "used by" edges on any node below to see exactly
who depends on it.

## Entity reference

### @mnemosyne/core

The foundation library (`libs/mnemosyne/core/src`), split behind `index.ts` into
five modules. `types.ts` defines the branded-ID type system (`LearnerId`,
`SRSCardId`, `KGNodeId`, …) and the shared learner/competency/SRS/assessment
schemas. `memory-science.ts` implements scientifically named spaced-repetition
schedulers — Ebbinghaus forgetting curve, SM-2 (Anki), FSRS v4, and half-life
regression — with review forecasting and cognitive-load management.
`assessment.ts` implements IRT (1PL/2PL/3PL), MLE ability estimation, Fisher
information, and a Computer-Adaptive-Testing loop plus rubric evaluation.
`knowledge-graph.ts` is an in-memory directed weighted graph (BFS shortest path,
bounded-depth DFS, Kahn topological sort, gap identification, Jaccard
similarity). `ai-infrastructure.ts` provides a 15-subsystem AI layer (prompt
templating, RAG, Socratic dialogue, question/distractor generation) built around
the injectable `LLMProvider` seam with algorithmic fallbacks — an honest
with/without-LLM boundary, not a fabricated model.

### @mnemosyne/linguistics

The largest engine (`libs/mnemosyne/linguistics/src/linguistics.ts`, ~6,500
lines): general linguistic analysis covering morphology, syntax, semantics,
pragmatics, historical/comparative linguistics, etymology, corpus linguistics,
typology, and endangered-language documentation (spec `39.4`). It includes real
algorithms such as `segmentMorphemes`, `buildInflectionalParadigm`,
`detectDerivationalProcess`, `analyzeCompound`, `parseDependency`,
`buildXBarStructure`, and morphological-typology classification, with
per-language morpheme and derivation databases behind `getMorphemeDatabase`.

### @mnemosyne/philology

The Digital Philology Suite (`libs/mnemosyne/philology/src/philology.ts`, ~4,700
lines; spec `39.6`): classical-language curricula (Ancient Greek, Latin,
Sanskrit, and a broader `CLASSICAL_CURRICULA_DATABASE`), script/writing-system
modules (Greek alphabet, cuneiform, hieroglyphic, Devanagari, Chinese radicals),
and digital-critical-edition tooling — TEI element types, Leiden epigraphic
conventions (`LEIDEN_CONVENTIONS`), manuscript witnesses, paleography,
papyrology, and intertextuality. Functions like `generateScriptDrillExercise`
and `computeScriptMasteryScore` operate over the curated curriculum data.

### @mnemosyne/phonetics

A multi-module phonetics package (`libs/mnemosyne/phonetics/src`) whose barrel
re-exports `types`, `ipa-database`, `phoneme-inventory`, `minimal-pairs`,
`tone-systems`, `prosody`, and an `extended` namespace. It carries a full IPA
chart (`ipa-database.ts` — pulmonic consonants, vowels, diacritics,
suprasegmentals), per-language phoneme inventories with L1→L2 difficulty
analysis (`phoneme-inventory.ts`), minimal-pair discrimination exercises
(`minimal-pairs.ts`), tonal-language data with Chao values and sandhi rules
(`tone-systems.ts`), prosody/connected-speech processing (`prosody.ts`), and the
~4,100-line `phonetics-extended.ts` laboratory (feature geometry, OT
constraints, phonotactics, historical sound changes, loanword adaptation).

### @mnemosyne/pronunciation

Advanced pronunciation tooling
(`libs/mnemosyne/pronunciation/src/pronunciation.ts`; spec `39.16`): ELSA-style
phoneme/syllable/fluency scoring (`computeOverallPronunciationScore`,
`identifyWeakPoints`), an L1-interference error database (`L1_ERROR_DATABASE`,
`getL1Errors`), personalised practice targeting, a Forvo-style native-recording
database with moderation/voting (`createRecording`, `moderateRecording`,
`getBestRecording`), and offline-pack building. It honestly documents that real
phoneme boundaries come from an ASR/forced-aligner upstream; the scoring
functions here compute deterministically over the supplied assessment
structures.

### @mnemosyne/polyglot

The multi-language mastery engine (`libs/mnemosyne/polyglot/src`), split across
`language-database`, `vocabulary`, `phonetic`, `grammar`, `reading`,
`frequency-bands`, `cefr`, plus `skills-extended`, `vocab-grammar-extended`, and
`language-resources`. It holds a typological language database with
cognate/false-friend tables, CEFR↔ILR↔ACTFL mapping (`cefr.ts`), vocabulary
coverage and frequency-band profiling, a rule/paradigm-driven grammar exercise
generator (`grammar.ts`), readability scoring (Flesch / Flesch-Kincaid → CEFR)
in `reading.ts`, and a rule-based grapheme-to-IPA transcriber plus
phonetic-similarity scorer (`phonetic.ts`). Its docs note word-segmentation
should be done via `@mnemosyne/philology` first.

### @mnemosyne/classical-tools

Specialised classical-language tooling
(`libs/mnemosyne/classical-tools/src/classical-tools.ts`; spec `39.18`): an
Alpheios-style morphological reading environment and DCC-style annotated-text
platform for Latin, Ancient Greek, Sanskrit, and others. It models morphological
forms and analyses (`createMorphologicalAnalysis`), dictionary lookup-URL
building, paradigm tables (Latin first declension, Greek thematic verb),
treebank dependency annotation (`getTokenDependents`, `getTokenPath`),
translation alignment, reading-progress/vocabulary-list tracking, and passage
difficulty assessment (`assessPassageDifficulty`).

### @mnemosyne/writing

Writing tools and feedback (`libs/mnemosyne/writing/src/writing.ts`; spec
`39.17`): a LanguageTool-style multilingual grammar-rule engine
(`GRAMMAR_RULES`, `getRulesForLanguage`, `createCustomRule`), per-language
syllable counters (English, Spanish, Italian, French, German) feeding a
readability score (`computeReadability`), formality and repetition analysis,
sentence-structure metrics, correction-history tracking, and a writing-practice
system with prompts (`WRITING_PROMPTS`, `generateDailyPrompt`) and rubrics.

### @mnemosyne/rhetoric

The classical trivium (`libs/mnemosyne/rhetoric/src/rhetoric.ts`; spec `39.8`):
grammar (part-of-speech identification, sentence diagramming via
`diagramSentence`, style guides, essay structures), logic and critical thinking
(logic-symbol tables, `evaluateTruthTable`/`generateTruthTable`, syllogism
forms, a `LOGICAL_FALLACIES` and `COGNITIVE_BIASES` catalogue, CRAAP source
evaluation, Toulmin argument mapping), and rhetoric/persuasion (rhetorical
appeals — ethos, pathos, logos, kairos — and the five canons).

### @mnemosyne/temporal

History, archaeology, and anthropology
(`libs/mnemosyne/temporal/src/temporal.ts`; spec `39.5`): multi-calendar
historical dates, a `HISTORICAL_PERIODS` timeline with `getPeriodByYear`,
causation-chain modelling (`buildCausationChain`, `rankCausationFactors`),
prosopographical tooling (genealogical trees, network centrality via
`computeNetworkCentrality`, shortest relationship paths), and
geographic-historical analysis including a `HISTORICAL_TRADE_ROUTES` dataset
with route-length computation — extending through bioarchaeology, economic, and
military/political history sections.

### @mnemosyne/mythology

Comparative religion and folklore (`libs/mnemosyne/mythology/src/mythology.ts`;
spec `39.9`): curated databases of deities, heroes, creatures, sacred places and
objects, cosmogony and flood myths, and underworld concepts across many
pantheons, with cross-cultural correspondence mapping
(`mapCrossculturalDeityCorrespondences`), divine genealogy,
comparative-mythology scholarship, the Hero's Journey stages, Jungian archetypes
and mythemes, and folklore classification via an ATU tale-type index and
Thompson motif sample (`classifyTaleType`, `extractMotifs`).

### @mnemosyne/aesthetics

Art history and visual analysis (`libs/mnemosyne/aesthetics/src/aesthetics.ts`;
spec `39.7`): an art-historical data model (`ArtworkSchema`, provenance,
conservation, exhibition records) with IIIF manifest generation
(`generateIIIFManifest`), Getty AAT vocabulary samples, and CIDOC-CRM mapping;
plus deterministic visual-analysis functions over structured artwork inputs —
`classifyArtworkStyle`, `analyzeAttribution`, `analyzeColorPalette`,
`detectForgeryIndicators` — and iconographic databases (symbols, saint
attributes, heraldry). The "Visual Analysis AI" computes from supplied artwork
descriptors, not random outputs.

### @mnemosyne/heritage

Cultural-heritage preservation (`libs/mnemosyne/heritage/src/heritage.ts`; spec
`39.10`): 3D digitisation pipeline configs (photogrammetry, structured light,
LiDAR, CT, RTI, multispectral), mesh optimisation and scan change-detection
(`compareScans` over point clouds), virtual reconstruction following the London
Charter and Seville Principles with uncertainty visualisation and polychromy
reconstruction, and archival infrastructure — an OAIS model, PREMIS/Dublin-Core
metadata builders, and provenance/repatriation tooling (it imports
`node:crypto`'s `createHash` for content hashing).

### @mnemosyne/knowledge-graph

Semantic infrastructure for humanities knowledge graphs
(`libs/mnemosyne/knowledge-graph/src/knowledge-graph.ts`; spec `39.11`): an RDF
term/triple model with namespace prefix expansion, CIDOC-CRM / FRBRoo / CRMsci /
CRMarchaeo class-and-property catalogues, LIDO and Europeana Data Model records,
Schema.org and Wikidata alignment tables, ontology-consistency validation, and
serialisation to Turtle, N-Triples, and JSON-LD (`serializeToTurtle`,
`convertTriplesToJSONLD`, `buildSPARQLQuery`). This is the linked-data
publishing counterpart to `core`'s in-memory learning graph.

### @mnemosyne/experience

The learning-experience and adaptivity engine
(`libs/mnemosyne/experience/src/experience.ts`; spec `39.12`): Bayesian
Knowledge Tracing (`updateBKT`, the classic 4-parameter HMM), a
Deep-Knowledge-Tracing feature-vector model, learning-trajectory optimisation
with prerequisite sequencing, Zone-of-Proximal-Development classification,
cognitive-load and fatigue estimation, UCB1 multi-armed-bandit and RL action
selection for content adaptation, learning-style/time-of-day profiling, and an
A/B-testing harness.

### @mnemosyne/immersion

Comprehensible-input and immersion infrastructure
(`libs/mnemosyne/immersion/src/immersion.ts`; spec `39.14`): MorphMan-style
morpheme-frequency analysis, i+1 sentence-difficulty scoring and content
laddering grounded in Krashen's Input Hypothesis, Refold-stage determination,
immersion-session tracking with streak/stat computation, and a sentence-mining
system — SRT parsing (`parseSRT`), one-target-sentence filtering, Jaccard
near-duplicate detection, bilingual-subtitle alignment, and subs2srs-style card
templates.

### @mnemosyne/community

Social learning and language exchange
(`libs/mnemosyne/community/src/community.ts`; spec `39.15`):
HelloTalk/Tandem-style partner matching (`computeMatchScore`,
`findLanguagePartners`), exchange-session scheduling with time-split balance
checks, inline correction markup that can be saved to vocabulary,
conversation-topic suggestion, social moments, voice rooms, and
reporting/moderation. It is paired with a substantial second module,
`community/src/transliteration.ts`, a deterministic table-driven transliterator
covering Hepburn romanisation of kana, on'yomi kanji, Revised-Romanisation
Hangul, ISO-9 Cyrillic, ALA-LC Arabic, ISO-15919 Devanagari, RTGS Thai, and
Georgian national romanisation.

### @mnemosyne/gamification-plus

Advanced, Duolingo-grade gamification
(`libs/mnemosyne/gamification-plus/src/gamification-plus.ts`; spec `39.19`):
tiered leagues (Bronze→Obsidian) with weekly promotion/demotion resolution
(`LEAGUE_DEFINITIONS`, `rankLeague`, `resolveLeagueWeek`), XP-multiplier events,
friend and team challenges, streak state with freeze/repair mechanics and
milestone XP multipliers (`computeStreakMultiplier`, `updateStreak`,
`repairStreak`), league achievements, and anti-gaming analysis
(`analyseAntiGaming`).

### @mnemosyne/platform

Infrastructure and integration (`libs/mnemosyne/platform/src/platform.ts`; spec
`39.13`): data import/export (Anki deck parse/export, CSV vocabulary, SCORM
manifest parsing, xAPI statement creation, LTI launch validation, Zotero export,
GDPR data packaging), external-content integration (Wikipedia/Wikidata SPARQL
URL builders, Europeana and Internet Archive query builders),
dictionary/translation provider definitions, and portable-progress data
structures — the connective tissue that lets the Mnemosyne engines exchange data
with external standards and services.