Mnemosyne — Technical Specifications

The humanistic learning and cultural intelligence platform

This document specifies the data models, algorithms, public APIs, and configuration of the Mnemosyne domain as actually implemented in libs/mnemosyne/*. Mnemosyne ships as 19 TypeScript libraries under the @mnemosyne/<name> namespace.

Every library is a pure, in-memory TypeScript package — there is no server, no Prisma/Drizzle schema, no HTTP route layer, and no message bus inside the domain. "Persistence", "events", and "APIs" below therefore describe library-level data shapes and function signatures, not a running service. This means the specifications here are authoritative descriptions of what functions exist and what TypeScript types they accept — a consuming application is responsible for wiring them to a database, network, or UI.

Each package declares only zod (validation) as a runtime dependency and vitest as a dev dependency. @mnemosyne/polyglot additionally imports @mnemosyne/core for shared types; all other packages are standalone. Source layout per package is src/<name>.ts plus src/<name>.test.ts and a barrel src/index.ts. A few packages — core, polyglot, phonetics — split into multiple source files.

1. Core Domain Model (@mnemosyne/core)#

@mnemosyne/core is the foundation package. Its src/types.ts defines the shared domain model; src/memory-science.ts, src/assessment.ts, src/knowledge-graph.ts, and src/ai-infrastructure.ts add algorithms and their associated types.

1.1 Branded ID Types#

All entity IDs use TypeScript nominal branding so the type system prevents accidentally passing a SRSCardId where a LearnerId is expected. The Brand<T, B> helper achieves this via intersection types:

type Brand<T, B> = T & { readonly __brand: B };

The twelve branded ID types defined in @mnemosyne/core are:

1.2 Learner Types#

The LearnerProfile is the central entity in the learning model. It carries the learner's language history, study preferences, cognitive style, and cumulative statistics. Several supporting types compose into it:

CognitiveStyle models learner preferences using the VARK model — four 0–1 preference scores rather than a single categorical label, reflecting that most learners blend modalities:

interface CognitiveStyle {
  visual: number; // 0-1 preference strength
  auditory: number; // 0-1
  kinesthetic: number; // 0-1
  readingWriting: number; // 0-1
}

Other learner-related types:

type StudyTimePreference = 'morning' | 'afternoon' | 'evening' | 'night';

interface LanguageProficiency {
  languageCode: string; // ISO 639-1
  level: CEFRLevel;
  isNative: boolean;
  subScores?: {
    reading: number; // 0-100
    listening: number;
    speaking: number;
    writing: number;
  };
}

interface LearnerStats {
  totalReviews: number;
  totalStudyTimeMinutes: number;
  cardsLearned: number;
  cardsMastered: number;
  averageRetention: number; // 0-1
  averageResponseTimeMs: number;
}

interface LearnerProfile {
  id: LearnerId;
  displayName: string;
  cognitiveStyle: CognitiveStyle;
  languages: LanguageProficiency[]; // ordered strongest → weakest
  dailyStudyMinutes: number;
  preferredStudyTime: StudyTimePreference;
  activeDomains: string[];
  createdAt: number; // epoch ms
  updatedAt: number; // epoch ms
  stats: LearnerStats;
  streakDays: number;
  longestStreakDays: number;
}

Session and progress types capture what happens during a single study period:

interface LearningSession {
  id: string;
  learnerId: LearnerId;
  startTime: number; // epoch ms
  endTime: number | null; // null = ongoing
  itemsStudied: SRSCardId[];
  correctCount: number;
  incorrectCount: number;
  focusScore: number; // 0-1, derived from response-time variance
  averageDifficulty: number;
  domains: string[];
}

interface ProgressMeasurement {
  recall: number; // 0-1
  speed: number; // 0-1, 1 = fastest
  accuracy: number; // 0-1
  fluency: number; // 0-1, productive fluency
  measuredAt: number; // epoch ms
  sampleSize: number;
}

1.3 Knowledge Item#

KnowledgeItem is the atomic unit of learning content — a fact, concept, skill, or procedure in any humanities domain. It carries prerequisite links directly so the knowledge graph can traverse them:

type KnowledgeItemType = 'fact' | 'concept' | 'skill' | 'procedure';

interface KnowledgeItem {
  id: KnowledgeItemId;
  type: KnowledgeItemType;
  title: string;
  description: string;
  domain: string; // e.g. "japanese", "calculus"
  difficulty: number; // 0-1
  prerequisites: KnowledgeItemId[];
  tags: string[];
  content?: string;
  createdAt: number;
  updatedAt: number;
}

KnowledgeItemType has exactly four values. There is no vocabulary or grammar item type; language-specific items live in @mnemosyne/polyglot's own VocabularyItem / GrammarRule types (§4).

1.4 Mastery Levels#

Six proficiency levels following the Dreyfus model of skill acquisition. The MASTERY_LEVELS constant provides the canonical ascending order used for all comparisons:

type MasteryLevel =
  | 'novice'
  | 'beginner'
  | 'intermediate'
  | 'advanced'
  | 'expert'
  | 'master';

const MASTERY_LEVELS: readonly MasteryLevel[]; // ordered, index = ordinal

1.5 Competency Frameworks#

Three international language proficiency frameworks are supported. Each has its own level enumeration and a corresponding descriptor type:

CEFR (Common European Framework of Reference) — the most widely used international standard:

type CEFRLevel = 'A1' | 'A2' | 'B1' | 'B2' | 'C1' | 'C2';

interface CEFRDescriptor {
  level: CEFRLevel;
  label: string; // 'Breakthrough', 'Waystage', 'Threshold', …
  description: string;
  canDo: string[]; // "can-do" statements
}

CEFR_LEVELS (ordered) and CEFR_DESCRIPTORS (6 entries, Council of Europe definitions) are exported constants.

ILR (Interagency Language Roundtable) — the US government scale used for military and intelligence language assessment, with 11 discrete levels:

type ILRLevel =
  | '0'
  | '0+'
  | '1'
  | '1+'
  | '2'
  | '2+'
  | '3'
  | '3+'
  | '4'
  | '4+'
  | '5';

interface ILRDescriptor {
  level: ILRLevel;
  label: string; // 'No Proficiency', 'Elementary Proficiency', …
  description: string;
}

ILR_LEVELS (11 entries) and ILR_DESCRIPTORS (11 entries) are exported.

ACTFL (American Council on the Teaching of Foreign Languages) — the standard used in US academic language programs:

type ACTFLLevel =
  | 'Novice Low'
  | 'Novice Mid'
  | 'Novice High'
  | 'Intermediate Low'
  | 'Intermediate Mid'
  | 'Intermediate High'
  | 'Advanced Low'
  | 'Advanced Mid'
  | 'Advanced High'
  | 'Superior'
  | 'Distinguished';

ACTFL_LEVELS is an ordered 11-entry constant. The ACTFL labels use spaces, not hyphens ('Novice Low', not 'Novice-Low').

A CompetencyFramework type provides a normalized interface over all three:

interface CompetencyFramework {
  name: 'CEFR' | 'ILR' | 'ACTFL';
  levels: readonly string[];
  normalise(level: string): number; // → 0-1 normalised score
}

1.6 SRS Card and Review Types#

The spaced repetition card design is central to the system. A single SRSCard carries state for both SM-2 and FSRS simultaneously so either algorithm can be used without card duplication. The review types track a learner's grading response and how the card schedule should be updated.

type ReviewGrade = 'again' | 'hard' | 'good' | 'easy';

const REVIEW_GRADE_MAP: Record<ReviewGrade, number>;
// { again: 1, hard: 2, good: 3, easy: 4 }

type SM2Grade = 0 | 1 | 2 | 3 | 4 | 5; // 0 = blackout, 5 = perfect

type FSRSState = 'New' | 'Learning' | 'Review' | 'Relearning';

The SRSCard interface showing both SM-2 and FSRS fields:

interface SRSCard {
  id: SRSCardId;
  front: string;
  back: string;
  deckId: DeckId;
  tags: string[];

  // SM-2 fields
  easeFactor: number; // initialised at 2.5
  interval: number; // days
  repetitions: number; // consecutive correct (SM-2 n)

  // FSRS fields
  difficulty: number; // 1-10 scale
  stability: number; // days
  state: FSRSState;
  lapses: number;
  reps: number;

  // Scheduling
  lastReviewAt: number | null; // epoch ms
  nextReviewAt: number; // epoch ms
  createdAt: number; // epoch ms
}

interface ReviewSchedule {
  cardId: SRSCardId;
  nextReviewAt: number; // epoch ms
  intervalDays: number;
  easeFactor: number;
}

interface ReviewResult {
  cardId: SRSCardId;
  grade: ReviewGrade;
  responseTimeMs: number;
  wasCorrect: boolean;
  reviewedAt: number; // epoch ms
}

1.7 FSRS Parameters#

FSRS v4 uses a 17-element weight vector that was calibrated on large review datasets. The default weights come from open-spaced-repetition/fsrs4anki:

interface FSRSParameters {
  w: readonly [number × 17];   // 17-element weight vector w[0]..w[16]
  requestRetention: number;    // 0-1, target retention
  maximumInterval: number;     // days
}

const FSRS_DEFAULT_PARAMETERS: FSRSParameters = {
  w: [
    0.4072, 1.1829, 3.1262, 15.4722, 7.2102, 0.5316, 1.0651, 0.0589,
    1.5747, 0.0838, 0.9816, 2.0379, 0.11, 0.2553, 2.218, 0.2267, 2.867,
  ],
  requestRetention: 0.9,
  maximumInterval: 36500,   // ~100 years
};

1.8 Assessment Types (IRT / CAT)#

IRT parameters describe each item's measurement properties. The three parameters correspond to the 3PL model: discrimination (how sharply the item distinguishes ability levels), difficulty (where on the ability scale the item is located), and guessing (the baseline probability of a correct answer by chance).

interface IRTParameters {
  a: number; // discrimination (slope), typically 0.5-2.5
  b: number; // difficulty (location on theta scale), typically -3..+3
  c: number; // pseudo-guessing (lower asymptote), typically 0-0.35
}

interface IRTAbilityEstimate {
  theta: number; // point estimate of ability
  standardError: number;
  itemCount: number;
  logLikelihood: number; // log-likelihood at the MLE
}

interface TestItem {
  id: TestItemId;
  question: string;
  options: string[];
  correctOptionIndex: number;
  irtParameters: IRTParameters;
  domain: string;
  administered?: boolean;
}

interface ItemResponse {
  itemId: TestItemId;
  selectedOptionIndex: number;
  correct: boolean;
  responseTimeMs: number;
}

interface AssessmentResult {
  id: AssessmentId;
  learnerId: LearnerId;
  items: ItemResponse[];
  abilityEstimate: IRTAbilityEstimate;
  score: number; // fraction correct
  totalTimeMs: number;
  averageDifficulty: number;
  completedAt: number; // epoch ms
}

The CAT configuration determines when the adaptive test starts, what selection strategy it uses, and when it stops:

interface CATConfig {
  minItems: number;
  maxItems: number;
  seThreshold: number; // stop when SE < this value
  initialTheta: number;
  selectionStrategy: 'max_info' | 'random' | 'stratified';
}

const DEFAULT_CAT_CONFIG: CATConfig = {
  minItems: 5,
  maxItems: 50,
  seThreshold: 0.3,
  initialTheta: 0.0,
  selectionStrategy: 'max_info',
};

1.9 Rubric Types#

Rubric assessment scores open-response submissions against multi-criterion definitions. Each criterion has an explicit weight and a set of ordered levels with descriptors so raters apply it consistently:

interface RubricCriterion {
  name: string;
  description: string;
  weight: number; // normalised internally
  levels: RubricLevel[]; // ordered lowest → highest
}

interface RubricLevel {
  score: number; // 0-based
  label: string;
  description: string;
}

interface Rubric {
  id: string;
  title: string;
  criteria: RubricCriterion[];
}

interface RubricEvaluation {
  rubricId: string;
  criterionScores: Array<{
    criterionName: string;
    score: number;
    maxScore: number;
    feedback: string;
  }>;
  totalScore: number; // weighted, 0-1
  overallFeedback: string;
}

1.10 Knowledge Graph Types#

The knowledge graph models relationships between concepts. The six relationship types cover both pedagogical dependencies and semantic associations:

type KGRelationType =
  | 'prerequisite'
  | 'part_of'
  | 'related_to'
  | 'causes'
  | 'temporal'
  | 'semantic_similar';

interface KGNode {
  id: KGNodeId;
  label: string;
  type: string; // domain-specific node type
  domain: string;
  properties: Record<string, string | number | boolean>;
  mastery?: MasteryLevel;
}

interface KGEdge {
  id: KGEdgeId;
  sourceId: KGNodeId;
  targetId: KGNodeId;
  type: KGRelationType;
  weight: number; // 0-1
  provenance: string; // e.g. 'expert', 'mined', 'inferred'
}

interface KGPath {
  nodes: KGNodeId[];
  edges: KGEdgeId[];
  totalWeight: number;
}

1.11 Learning Path Types#

Learning paths connect a curriculum (a structured sequence of modules and lessons) to a specific learner's progress through it. Branching rules allow the path to adapt based on what the learner has demonstrated:

type ExerciseType =
  | 'multiple_choice'
  | 'fill_in'
  | 'production'
  | 'matching'
  | 'ordering'
  | 'cloze';

interface Exercise {
  id: ExerciseId;
  type: ExerciseType;
  prompt: string;
  correctAnswers: string[];
  distractors?: string[];
  hint?: string;
  difficulty: number; // 0-1
  knowledgeItemId?: KnowledgeItemId;
  domain: string;
}

interface Lesson {
  id: string;
  title: string;
  description: string;
  knowledgeItems: KnowledgeItemId[];
  exercises: ExerciseId[];
  estimatedMinutes: number;
  order: number;
}

interface CurriculumModule {
  id: string;
  title: string;
  description: string;
  lessons: Lesson[];
  prerequisites: string[]; // module IDs
  order: number;
}

interface Curriculum {
  id: CurriculumId;
  title: string;
  description: string;
  domain: string;
  modules: CurriculumModule[];
  targetLevel: MasteryLevel;
  estimatedHours: number;
  createdAt: number;
  updatedAt: number;
}

interface LearningPath {
  id: LearningPathId;
  learnerId: LearnerId;
  curriculumId: CurriculumId;
  moduleOrder: string[];
  unlockedModules: string[];
  completedModules: string[];
  currentModuleId: string | null;
  branchingRules: BranchingRule[];
  createdAt: number;
  updatedAt: number;
}

interface BranchingRule {
  condition: BranchCondition;
  targetModuleId: string;
  action: 'skip' | 'unlock';
}

type BranchCondition =
  | { type: 'score_above'; moduleId: string; threshold: number }
  | {
      type: 'mastery_at_least';
      knowledgeItemId: KnowledgeItemId;
      level: MasteryLevel;
    }
  | { type: 'time_spent_below'; moduleId: string; minutes: number };

1.12 Gamification Types#

Badge tiers are distinct from competitive league tiers — badges are awarded for individual accomplishments and use five tiers; leagues (in @mnemosyne/gamification-plus) are competitive divisions and use six tiers including Obsidian.

type BadgeTier = 'bronze' | 'silver' | 'gold' | 'platinum' | 'diamond';

const BADGE_TIERS: readonly BadgeTier[];

interface AchievementBadge {
  id: AchievementBadgeId;
  name: string;
  description: string;
  iconUrl: string;
  tier: BadgeTier;
  domain: string; // or 'global'
  criteria: BadgeCriteria;
  xpReward: number;
}

type BadgeCriteria =
  | { type: 'streak'; days: number }
  | { type: 'cards_reviewed'; count: number }
  | { type: 'mastery_reached'; level: MasteryLevel; domain: string }
  | { type: 'accuracy_above'; threshold: number; windowDays: number }
  | { type: 'sessions_completed'; count: number }
  | { type: 'perfect_session'; count: number };

interface EarnedBadge {
  badgeId: AchievementBadgeId;
  learnerId: LearnerId;
  earnedAt: number;
}

The BadgeTier set is bronze/silver/gold/platinum/diamond (five tiers). The Duolingo-style competitive league tiers (Bronze … Obsidian) are a separate type defined in @mnemosyne/gamification-plus (§10).

1.13 Cognitive Load Types#

Based on Sweller's Cognitive Load Theory, the load estimate separates three types of mental effort. When total load exceeds 0.85 the system recommends reducing difficulty or ending the session:

interface CognitiveLoadEstimate {
  intrinsicLoad: number; // 0-1, from the material itself
  extraneousLoad: number; // 0-1, from presentation / interface
  germaneLoad: number; // 0-1, productive learning effort
  totalLoad: number; // 0-1; > 0.85 → overload risk
  recommendation: CognitiveLoadRecommendation;
}

type CognitiveLoadRecommendation =
  | 'continue'
  | 'reduce_difficulty'
  | 'take_break'
  | 'end_session';

1.14 Review Forecast and Interleaving Types#

Forecast types model the future review queue so a learner (or application) can anticipate load and plan study time:

interface ReviewForecast {
  startDate: number; // epoch ms
  dailyCounts: DailyReviewCount[];
  averageDailyReviews: number;
  peakDailyReviews: number;
}

interface DailyReviewCount {
  dayOffset: number; // 0 = today
  dueCount: number;
  estimatedMinutes: number;
}

interface InterleavingPlan {
  sequence: SRSCardId[];
  domains: string[];
  strategy: InterleavingStrategy;
}

type InterleavingStrategy =
  | 'round_robin'
  | 'weighted_random'
  | 'difficulty_interleaved';

1.15 Half-Life Regression Types#

HLR fits a personalized forgetting curve per learner per item. The weight vector encodes how each feature (number of repetitions, time since last review, prior half-life) contributes to the predicted half-life:

interface HLRFeatures {
  repetitionCount: number;
  lagTimeDays: number;
  previousHalfLife: number; // days
  extras?: Record<string, number>;
}

interface HLRWeights {
  intercept: number;
  repetitionWeight: number;
  lagTimeWeight: number;
  previousHalfLifeWeight: number;
  extraWeights?: Record<string, number>;
}

const DEFAULT_HLR_WEIGHTS: HLRWeights = {
  intercept: 2.0,
  repetitionWeight: 0.9,
  lagTimeWeight: -0.2,
  previousHalfLifeWeight: 0.5,
};

1.16 Feedback Types#

Feedback is richly typed to support different delivery contexts. FeedbackTiming distinguishes immediate (shown right after a response) from delayed (shown in a later review). FeedbackGranularity ranges from simple verification ("correct!") through elaboration to metacognitive reflection:

type FeedbackTiming = 'immediate' | 'delayed';
type FeedbackPurpose = 'formative' | 'summative' | 'diagnostic';
type FeedbackGranularity =
  | 'verification'
  | 'correct_response'
  | 'elaboration'
  | 'strategic'
  | 'metacognitive';
type FeedbackModality = 'text' | 'audio' | 'visual' | 'interactive';

interface Feedback {
  id: string;
  timing: FeedbackTiming;
  purpose: FeedbackPurpose;
  granularity: FeedbackGranularity;
  modality: FeedbackModality;
  content: string;
  explanation?: FeedbackExplanation;
  targetItemId?: ExerciseId | KnowledgeItemId | TestItemId;
  learnerResponse?: string;
  wasCorrect?: boolean;
  confidence?: number; // 0-1
  tags: string[];
  createdAt: number;
}

Supporting interfaces include FeedbackExplanation (summary, steps, misconceptions, references, alternativeApproaches), FeedbackReference (title, type ∈ textbook/video/article/exercise/external, url, anchor), ImmediateFeedbackConfig, DelayedFeedbackConfig, FormativeFeedback (strengths, areasForImprovement, nextSteps, progressTowardObjective, identifiedGaps, suggestedRemediation), and SummativeFeedback (overallScore, gradeLabel, masteryLevel, domainScores, optional certification, percentileRank, narrative).

2. Core Algorithms (@mnemosyne/core)#

2.1 Memory Science (src/memory-science.ts)#

The memory science module implements all scheduling algorithms as pure functions. Each function's signature, formula, and error-handling behavior is documented below. Input invariants that are violated throw RangeError rather than returning silently incorrect results.

Memory-science return types: SM2ReviewResult (easeFactor, interval, repetitions, nextReviewAt), FSRSReviewResult (difficulty, stability, state, interval, reps, lapses, nextReviewAt), AdaptiveDifficultyConfig, AdaptiveDifficultyState, CircadianPhase, CircadianPerformanceProfile, SleepSchedule.

The seven circadian phases and the adaptive difficulty defaults are:

type CircadianPhase =
  | 'early_morning'
  | 'morning'
  | 'early_afternoon'
  | 'afternoon'
  | 'evening'
  | 'night'
  | 'late_night';

const DEFAULT_ADAPTIVE_DIFFICULTY_CONFIG: AdaptiveDifficultyConfig = {
  targetAccuracy: 0.85,
  smoothingFactor: 0.3,
  minDifficulty: 0.05,
  maxDifficulty: 0.95,
  adjustmentRate: 0.1,
  minResponsesBeforeAdjust: 3,
};

DEFAULT_CIRCADIAN_PROFILES is a 7-entry constant array (one CircadianPerformanceProfile per CircadianPhase) with empirically motivated learningEfficiency and consolidationBonus values.

FSRS v4 State Machine#

fsrsReview implements the full FSRS v4 transition graph on the card's state field. The transitions work as follows:

• New → first review initialises D0 = w[4] − (g−3)·w[5] and S0 = w[g−1]; grade again/hard → Learning, good/easy → Review.
• Learning / Relearning → again stays in the current learning state; hard/good/easy graduate to Review. A lapse counter increments only in Relearning.
• Review → again applies the lapse-stability formula and transitions to Relearning (increments lapses); hard/good/easy apply the success-stability formula and stay in Review.

Interval is 9·S·(1/requestRetention − 1) for Review cards (rounded, clamped to [1, maximumInterval]); learning/relearning cards use short 0–1 day intervals.

2.2 Assessment (src/assessment.ts)#

All IRT functions take ability (theta) and item parameters; they return probabilities or information values. The classes provide stateful workflows built on top of these pure functions.

The stateful assessment classes are:

• ItemBank — in-memory item bank: addItem / addItems / removeItem / getItem / getAllItems, size; filters getByDomain, getByDifficultyRange, getByDiscriminationRange; exposure tracking recordAdministration / getExposureCount / getUnderexposedItems; getStatistics() → ItemBankStatistics; clear().
• PortfolioTracker — PortfolioEntry collection with addEntry, getEntries, getByType, getByTimeRange, size, computeGrowthTrajectory(domain?), analyzeStrengthsWeaknesses(), clear().
• PeerAssessmentManager — peer-review workflow: createAssignments, submitReview, getAssignmentsForReviewer, getReviewsForSubmission, computeAgreement (variance-based inter-rater agreement), aggregateReviews (reliability-weighted consensus), setReviewerReliability / getReviewerReliability.
• SelfAssessmentCalibrator — addPrediction, recordActualScore, computeCalibration() → CalibrationMetrics (bias, absoluteError, calibrationSlope, resolution, sampleSize, over/underconfidence rates), generateFeedback(), clear().
• CertificationManager — registerCertification, getCertification, getAllCertifications, checkRequirements, issueCredential (issues only when all requirements are met), getCredentialsForLearner, refreshValidity.

Assessment data types include ItemBankStatistics, PortfolioEntry, PeerReviewStatus (pending/in_progress/completed/disputed), PeerReviewAssignment, PeerReview, SelfAssessmentPrediction, CalibrationMetrics, Certification, CertificationRequirement (a tagged union: min_score / min_mastery / portfolio_entries / study_hours), Credential, CredentialEvidence, ProctoringMode (unproctored / ai_proctored / live_proctored / record_and_review), ProctoringFlag, ProctoringFlagType (10 values: tab_switch, face_not_detected, multiple_faces, audio_anomaly, copy_paste, screen_share, unusual_typing, time_anomaly, browser_resize, external_device), ProctoringSession.

2.3 Knowledge Graph (src/knowledge-graph.ts)#

The KnowledgeGraph class is an in-memory directed weighted graph. Node similarity is computed as Jaccard similarity over the two nodes' properties maps (each key-value pair is treated as a set element).

Node operations: addNode, removeNode (cascades incident edges), getNode, getAllNodes, nodeCount, getNodesByType, getNodesByDomain.

Edge operations: addEdge (validates endpoints exist), removeEdge, getEdge, getEdgesFrom, getEdgesTo, getAllEdges, edgeCount, getEdgesByType, getNeighbours, getInDegree, getOutDegree.

Traversal and pathfinding:

• findPath — BFS shortest path between two nodes.
• findAllPaths — DFS all paths, bounded by maxDepth.
• getPrerequisites — transitive backward traversal over prerequisite edges.
• getDependents — transitive forward traversal.
• topologicalSort() — Kahn's algorithm over prerequisite edges; throws on a cycle.

Learning-specific operations:

• identifyKnowledgeGaps(learnerMastery, targetNodeId, minLevel?) — missing or under-mastered prerequisites given the learner's current state.
• recommendNextItems(learnerMastery, count, targetLevel?) — items whose prerequisites are met, ranked by dependent count and mastery gap.
• findSimilarNodes(nodeId, threshold?) — Jaccard similarity search.
• query(query: GraphQuery) — SPARQL-style Basic Graph Pattern matching over TriplePattern[] (conjunctive); supports node-property and edge patterns, ?-prefixed variables.
• discoverCrossDomainLinks(similarityThreshold?, maxLinksPerNode?) — creates semantic_similar edges between similar nodes in different domains.
• getTimeline(startNodeId, direction?, maxDepth?) — temporal traversal.
• getNodesInTimeRange(startYear, endYear) — year-filtered node set.
• buildTemporalChain(domain) — orders nodes in a domain chronologically.
• clear().

Query types: TriplePattern (subject, predicate, object), GraphQuery (where: TriplePattern[]).

2.4 AI / ML Infrastructure (src/ai-infrastructure.ts)#

The AI infrastructure layer is designed to run with or without a live LLM. With an injected LLMProvider it can use generative power; without one it falls back to algorithmic and template implementations. The layer covers 15 subsystems:

LLM integration. LLMProvider interface (complete, embed, name, isAvailable); LLMMessage, MessageRole (system/user/assistant), CompletionConfig, LLMCompletionResult. Default parameters: DEFAULT_COMPLETION_CONFIG = { maxTokens: 1024, temperature: 0.7, topP: 0.9, frequencyPenalty: 0.1, presencePenalty: 0.1 }.

Bloom's taxonomy and scaffolding. BloomLevel (remember, understand, apply, analyze, evaluate, create), BLOOM_LEVELS, BLOOM_ACTION_VERBS (verb lists per level), ScaffoldingLevel (full/partial/minimal/none), SCAFFOLDING_LEVELS. EducationalContext carries mastery, domain, cognitive style, bloom level, and scaffolding level.

Prompt framework. PromptTemplate ({{placeholder}} syntax), renderPromptTemplate, buildEducationalSystemPrompt, EDUCATIONAL_PROMPT_TEMPLATES (5 built-in templates: explain_concept, socratic_question, generate_hint, detect_misconception, generate_analogy), selectPromptTemplate.

RAG pipeline. DocumentChunk, ChunkingConfig (fixed_size/sentence/paragraph/semantic strategy), DEFAULT_CHUNKING_CONFIG (512 max tokens, 64 overlap, sentence strategy), chunkDocument, cosineSimilarity, bm25Score (Okapi BM25), retrieveChunks (BM25 / cosine / hybrid), assembleRAGContext, RetrievalResult.

Knowledge-grounded responses. generateGroundedResponse → GroundedResponse with Citation[] and a groundingScore.

Socratic dialogue. SocraticMethod (elenchus, maieutic, reductio, hypothesis_testing, dialectic), SocraticQuestion, SocraticDialogueTurn, SocraticDialogueState; generateSocraticQuestion, createSocraticDialogue, advanceSocraticDialogue.

Adaptive hints. HintLevel (nudge, clue, explanation, solution), HINT_LEVELS, Hint, HintSequenceState; generateHint, createHintSequence, getNextHint, selectInitialHintLevel.

Multi-perspective explanations. ExplanationPerspective (analogy, formal, visual, historical, practical, first_principles, comparative — seven perspectives), PerspectiveExplanation, MultiPerspectiveExplanation; generateMultiPerspectiveExplanation, selectBestPerspective.

Misconception detection. MisconceptionPattern, MisconceptionDetectionResult, COMMON_MISCONCEPTIONS (curated, research-based pattern library), detectMisconceptions, createMisconceptionPattern.

Question generation. QuestionType, GeneratedQuestion, AQGConfig, DEFAULT_AQG_CONFIG, generateQuestionsFromText.

Distractor generation. Distractor, DistractorErrorType, generateDistractors.

Cloze deletion. ClozeDeletion, ClozeScoreFactors, generateClozeDeletions, estimateClozeDifficulty (→ MasteryLevel).

Semantic cards. SemanticCard, SemanticCardType, generateSemanticCards, generateCardsFromText.

Multimodal content. ContentModality, MultimodalContent, AccessibilityMetadata, ContentGenerationRequest, generateMultimodalContentPlan.

Personalized examples. LearnerInterestProfile, PersonalizedExample, generatePersonalizedExamples.

Learning analytics. LearningDataPoint, DropoutPrediction, MasteryTimeline, OptimalReviewPrediction, EngagementTrend; predictDropoutRisk, predictMasteryTimeline, predictOptimalReviewCount, analyzeEngagementTrend.

3. Memory Science Algorithm Reference#

The formulas below are the exact computations implemented in src/memory-science.ts. They are repeated here for quick reference without needing to read source code.

SM-2#

EF' = EF + (0.1 − (5 − q) × (0.08 + (5 − q) × 0.02))   (clamped ≥ 1.3)
q < 3 → repetitions = 0, interval = 1
q ≥ 3 → repetitions++, interval = 1 (n=1), 6 (n=2), round(interval × EF') (n≥3)

FSRS v4 Retrievability#

R(t, S) = (1 + t / (9 · S))^(−1)

IRT Probability Models#

1PL  P(θ, b)        = 1 / (1 + e^(−(θ − b)))
2PL  P(θ, a, b)     = 1 / (1 + e^(−a(θ − b)))
3PL  P(θ, a, b, c)  = c + (1 − c) / (1 + e^(−a(θ − b)))

Fisher Information (3PL)#

I(θ) = a² · (P − c)² · (1 − P) / ((1 − c)² · P)

Half-Life Regression#

h = 2^(θ · x)        retention p = 2^(−t / h)

The full Bayesian Knowledge Tracing implementation lives in @mnemosyne/experience (§9), not in @mnemosyne/core.

4. Polyglot — Language Engine (@mnemosyne/polyglot)#

@mnemosyne/polyglot splits across nine source files: language-database.ts, vocabulary.ts, grammar.ts, reading.ts, skills-extended.ts, vocab-grammar-extended.ts, cefr.ts, phonetic.ts, frequency-bands.ts, plus types.ts.

4.1 Language Metadata Types#

Language codes are branded strings so a raw string cannot be passed where a LanguageCode is expected:

type LanguageCode = string & { __brand: 'LanguageCode' }; // ISO 639-3

The full set of language classification types:

type LanguageFamily =
  | 'Indo-European'
  | 'Sino-Tibetan'
  | 'Afro-Asiatic'
  | 'Niger-Congo'
  | 'Austronesian'
  | 'Dravidian'
  | 'Turkic'
  | 'Japonic'
  | 'Koreanic'
  | 'Uralic'
  | 'Tai-Kadai'
  | 'Austroasiatic'
  | 'Language Isolate'
  | 'Kartvelian'
  | 'Mongolic'
  | 'Tungusic'
  | 'Quechuan'
  | 'Arawakan'
  | 'Tupian'
  | 'Nilo-Saharan'
  | 'Hmong-Mien'
  | 'Trans-New Guinea'
  | 'Creole'
  | 'Sign Language';

type WritingSystemType =
  | 'alphabet'
  | 'abjad'
  | 'abugida'
  | 'syllabary'
  | 'logographic'
  | 'featural'
  | 'alphasyllabary';

type ScriptDirectionality = 'LTR' | 'RTL' | 'TTB';
type WordOrder = 'SOV' | 'SVO' | 'VSO' | 'VOS' | 'OVS' | 'OSV' | 'Free';
type MorphologicalType =
  | 'analytic'
  | 'synthetic'
  | 'agglutinative'
  | 'fusional'
  | 'polysynthetic';

type PartOfSpeech =
  | 'noun'
  | 'verb'
  | 'adjective'
  | 'adverb'
  | 'pronoun'
  | 'preposition'
  | 'conjunction'
  | 'determiner'
  | 'interjection'
  | 'numeral'
  | 'particle'
  | 'auxiliary';

WritingSystem, UnicodeRange, TypologicalFeatures, and LanguageMetadata record full script and typological metadata. The exported registries and accessors are: LANGUAGE_DATABASE, WRITING_SYSTEMS, getLanguage, getAllLanguages, getLanguageFamily, getLanguageSubfamily, getRelatedLanguages, getLanguagesInFamily, getTypologicalFeatures, getLanguageDistance, getWritingSystem, getAllWritingSystems, getUnicodeRanges. The langCode helper brands a raw string as a LanguageCode.

Cross-language vocabulary relationships: COGNATE_DATABASE / getCognates and FALSE_FRIENDS_DATABASE / getFalseFriends / findFalseFriend cover cross-language cognates and false friends (CognateEntry, FalseFriendEntry).

4.2 Vocabulary Types#

Each VocabularyItem carries the word's cross-language translations, example sentences, typical collocations, and CEFR level so exercises can be tailored to the learner's current proficiency:

type Register =
  | 'informal'
  | 'neutral'
  | 'formal'
  | 'literary'
  | 'slang'
  | 'technical';

interface VocabularyItem {
  word: string;
  language: LanguageCode;
  translations: Record<string, string>; // keyed by language code
  exampleSentences: ExampleSentence[];
  collocations: string[];
  register: Register;
  cefrLevel: CEFRLevel;
  partOfSpeech: PartOfSpeech;
  ipa?: string;
  audioUrl?: string;
  notes?: string;
}

Supporting vocabulary types: ExampleSentence, ThematicModule, ThemeCategory (20 categories: travel, food_dining, shopping, health_medical, business, technology, education, family, housing, transportation, weather, sports, entertainment, law_government, environment, arts_culture, science, emotions, work_career, daily_routines), ThematicActivity, VocabularyCoverage, WordFamily, WordFamilyMember, DerivationType, MnemonicKeyword, CoverageOptions.

Vocabulary functions and constants include CEFR_VOCABULARY_SIZE, COVERAGE_THRESHOLDS, estimateCEFRFromVocabSize, estimateVocabSizeFromCEFR, getVocabSizeRange, estimateCoverageFromVocabSize, getFrequencyList, generateFrequencyList, calculateCoverage, getThematicModules, getThematicModule, getModulesForLevel, expandWordFamily, getDerivationPatterns, generateMnemonic, SAMPLE_MNEMONICS. DEFAULT_COVERAGE_OPTIONS uses 0.95 (extensive) / 0.90 (assisted) reading thresholds, word families on, proper nouns counted as known.

4.3 Grammar Types#

Grammar types cover both reference data (rules, paradigms, patterns) and exercise generation:

GrammarRule, GrammarExample, MorphologicalParadigm, ParadigmForm, SyntacticPattern, PatternSlot, GrammarExerciseType (fill_in, transform, error_correct, judgment, multiple_choice, sentence_build, conjugate), GrammarExercise, ContrastiveAnalysis, TransferError.

Grammar functions: getGrammarRules, getGrammarRulesForLevel, getGrammarRule, getGrammarRulesByTopic, getParadigms, getParadigm, getForm, getSyntacticPatterns, getSyntacticPattern, generateFillInBlank, generateTransformation, generateErrorCorrection, generateGrammaticalityJudgment, generateMultipleChoice, getContrastiveAnalysis, getContrastiveAnalyses, getTransferErrors, getPredictedDifficulty.

4.4 Reading and Frequency Analysis#

Reading analysis types model both text properties and learner comprehension skills:

TextDifficulty, VocabularyProfile (K1/K2/K3/offList bands), ComprehensionSkill (literal, inferential, evaluative, main_idea, vocabulary_in_context, author_purpose, text_structure), ComprehensionQuestion, ReadingMetrics, TextAnalysisResult.

Reading functions: countSyllables, splitSentences, tokenizeWords, fleschReadingEase, fleschKincaidGradeLevel, fleschToCEFR, analyzeVocabularyProfile, analyzeTextDifficulty, analyzeVocabularyCoverage, analyzeText, generateLiteralQuestion, generateInferentialQuestion, generateMainIdeaQuestion, generateVocabularyQuestion, calculateReadingMetrics, recommendReadingApproach.

Corpus frequency bands (frequency-bands.ts): BandLabel, FrequencyBands, SUPPORTED_BAND_LANGUAGES, getDefaultBands, getWordBand, profileFromCorpus. The package ships real corpus data under libs/mnemosyne/polyglot/data/: en-frequency-bands.json (New General Service List v1.2, 2,801 headwords) and es-frequency-bands.json (top-3000 Spanish lemmas), each grouped into K1/K2/K3 bands per Laufer & Nation's Lexical Frequency Profile.

4.5 Phonetic Transcription#

phonetic.ts exports: wordToIPA, phoneticSimilarity, tokenizeIPA, detectLanguage, and the DetectedLanguage type.

4.6 CEFR Mapping#

All three international proficiency scales are supported with bidirectional mapping between them:

LanguageSkill (reading, writing, listening, speaking, interaction), CEFRSkillDescriptor, CEFRProgressReport, SkillEstimate, ProficiencyEstimate, StandardizedTestType (IELTS, TOEFL_iBT, TOEFL_PBT, Cambridge, DELF_DALF, Goethe, DELE, JLPT, HSK, TOPIK, TestDaF), TestScoreMapping, CEFREvidence.

CEFR functions: CEFR_SKILL_DESCRIPTORS, getCEFRDescriptors, getCEFRDescriptorsForSkill, getCEFRDescriptor, mapToILR, mapToACTFL, mapILRToCEFR, mapACTFLToCEFR, cefrToNumericScore, numericScoreToCEFR, mapToCEFR, estimateCEFRLevel, createProficiencyEstimate, compareCEFRLevels, nextCEFRLevel, previousCEFRLevel, cefrRange.

@mnemosyne/polyglot also implements extended skill descriptors (skills-extended.ts) and extended vocabulary/grammar modules (vocab-grammar-extended.ts).

5. Classical Tools (@mnemosyne/classical-tools)#

The classical tools package supports assisted reading of ancient texts in seven languages. The ClassicalLanguage union names those languages; the types below describe the morphological, syntactic, and annotation structures needed for an Alpheios-style reading environment.

type ClassicalLanguage = …;   // Latin, Ancient Greek, Sanskrit, Classical
                              // Arabic, Biblical Hebrew, Old Church Slavonic,
                              // Classical Syriac
type GrammaticalCase = …;
type VerbTense = …;  type VerbMood = …;  type VerbVoice = …;

Domain types: MorphologicalForm, MorphologicalAnalysis, DictionaryEntry, DictionaryExample, DictionarySource, ParadigmCell, ParadigmTable, GrammarReference, TreebankToken, TreebankAnnotation, SyntacticRelation, AlignmentPair, TranslationAlignment, ClassicalReadingProgress, VocabularyListEntry, PassageDifficultyAssessment, ReadingCheckpoint, CheckpointQuestion, AnnotationLayer, TextAnnotation, AnnotationMedia, CrossReference, MapReference, StudyGuide, StudyGuideSection, AnnotationQuizQuestion, CollaborativeAnnotationEdit, AnnotationExport, CoreVocabularyList, CoreVocabularyEntry, CEFREquivalent.

Functions include describeMorphForm, createMorphologicalAnalysis, buildDictionaryLookupUrl, buildLatinFirstDeclensionParadigm, buildGreekThematicVerbParadigm, GRAMMAR_REFERENCES / findGrammarReferences, getTokenDependents, getTokenPath, createTranslationAlignment, createReadingProgress, recordWordLookup, createVocabularyListEntry, assessPassageDifficulty, createReadingCheckpoint, createTextAnnotation, generateStudyGuide, generateQuizFromAnnotations, proposeAnnotationEdit, applyAnnotationEdit, exportAnnotations.

6. Phonetics (@mnemosyne/phonetics)#

The phonetics package is organized across six source modules covering the full IPA system and language-specific phonological features:

• IPA database — PULMONIC_CONSONANTS, IPA_VOWELS, IPA_DIACRITICS, IPA_SUPRASEGMENTALS, ALL_IPA_ENTRIES constant arrays. Accessors: getIPAEntry, getIPAEntryByName, getConsonantsByFeatures, getVowelsByFeatures, describeSymbol, getDiacritic, getDiacriticsByCategory. Feature types: PlaceOfArticulation, MannerOfArticulation, VowelHeight, VowelBackness, Voicing, VowelRounding, with PLACES_OF_ARTICULATION / MANNERS_OF_ARTICULATION / VOWEL_HEIGHTS / VOWEL_BACKNESSES ordered constants.
• Phoneme inventory — getPhonemeInventory, getAvailableLanguages, compareInventories, identifyDifficultPhonemes, getPhonemeDistribution; types Phoneme, PhonemeInventory, InventoryDiphthong.
• Minimal pairs — generateMinimalPairs, getAvailableContrasts, rankMinimalPairDifficulty, generateDiscriminationExercise.
• Tone systems — getToneSystem, getTonalLanguages, applyMandarinSandhi, getMandarinToneValue, getCantoneseToneValue, getToneSandhiRules, isTonalLanguage, compareToneSystems.
• Prosody — predictStressedSyllableIndex, analyzeStressPattern, analyzeSentenceStress, analyzeRhythm, identifyConnectedSpeechRules, getConnectedSpeechRulesByType, getSyllableStructure, getAllRhythmProfiles, compareRhythm.

7. Heritage (@mnemosyne/heritage)#

The heritage package models the full pipeline from physical digitization through digital archiving to legal provenance documentation. Key enum types establish the vocabulary of methods and classification systems used in conservation science:

type DigitizationMethod = …;        // photogrammetry, structured light, …
type FileFormat3D = …;              // OBJ, STL, PLY, glTF, …
type ReconstructionUncertainty = …;
type ConditionGrade =
  | 'excellent' | 'good' | 'fair' | 'poor' | 'critical';
type ICHDomain = …;                 // UNESCO intangible-heritage domains

Selected interfaces and constants organized by area:

Digitization: PhotogrammetryPipeline / PHOTOGRAMMETRY_PIPELINE, StructuredLightScanner / STRUCTURED_LIGHT_SCANNING, LiDARProcessingConfig / LIDAR_PROCESSING, CTScanVisualization / CT_SCAN_VISUALIZATION, RTIConfiguration / RTI_CONFIGURATION, MultiSpectralImaging / MULTISPECTRAL_IMAGING, MeshOptimizationConfig, AnnotationModel, MeasurementResult, ChangeDetectionResult, PointCloud.

Virtual reconstruction: ArchitecturalReconstruction, LONDON_CHARTER_PRINCIPLES, SEVILLE_PRINCIPLES, VirtualAnastylosis, PolychromyReconstruction / CLASSICAL_POLYCHROMY_PIGMENTS, UncertaintyVisualization, PhaseTimeline.

Digital archiving: OAISModel / OAIS_MODEL, PREMISMetadata, DublinCoreRecord, METSDocument, EADFindingAid, FormatMigrationPlan / FORMAT_RISK_REGISTRY, DOIAssignment, OAIPMHRecord, FAIR_PRINCIPLES_CHECKLIST.

Virtual museums: VirtualGallery, VirtualMuseumObject, GuidedTour, ExhibitionSchedule, VisitorAnalytics.

Conservation: ConditionAssessment / CONDITION_ASSESSMENT_TEMPLATES, TreatmentRecord, CONSERVATION_MATERIALS_DATABASE, EnvironmentalMonitoring / ICCROM_ENVIRONMENTAL_STANDARDS, RiskAssessment.

Provenance and repatriation: ProvenanceChain, ArtLossRecord, NAZI_ERA_PROVENANCE_GUIDELINES, ColonialAcquisitionAnalysis, RepatriationClaim / REPATRIATION_LEGAL_FRAMEWORKS, BlockchainProvenanceRecord.

Intangible heritage: UNESCOICHElement / INTANGIBLE_HERITAGE_EXAMPLES, OralHistoryInterview, TraditionalKnowledgeRecord / LOCAL_CONTEXTS_TK_LABELS, PerformanceCaptureSession / LABANOTATION_SYMBOLS, FoodwaysDocumentation, UNESCOICHSafeguardingPlan.

Functions: create3DAnnotation, measureDistance, compareScans, calculateReconstructionCompleteness, buildPhaseTimeline, createPREMISObject, verifyChecksum, assignDOI, createVirtualGallery, addObjectToGallery, calculateRiskScore, generateProvenanceReport, createICHSafeguardingPlan. The package exports a HERITAGE_CAPABILITIES summary constant.

8. Temporal — History / Archaeology / Anthropology (@mnemosyne/temporal)#

The temporal package models historical knowledge structurally: events have typed dates, people exist in prosopographical networks, sites have stratigraphic sequences, and artifacts have classification schemas.

HistoricalDate uses a CalendarSystem tag to indicate which calendar a date is expressed in. Note that the package does not currently implement cross-calendar numeric conversion functions; CalendarSystem is a classification tag, not a conversion engine.

type CalendarSystem =
  | 'gregorian'
  | 'julian'
  | 'coptic'
  | 'islamic'
  | 'hebrew'
  | 'chinese'
  | 'mayan'
  | 'roman'
  | 'egyptian';

type DateCertainty =
  | 'exact'
  | 'approximate'
  | 'circa'
  | 'terminus_post_quem'
  | 'terminus_ante_quem'
  | 'floruit';

interface HistoricalDate {
  year: number; // negative = BCE
  month?: number;
  day?: number;
  calendar: CalendarSystem;
  certainty: DateCertainty;
  label?: string; // e.g. "ca. 480 BCE", "fl. 5th c. BCE"
}

The HistoricalEvent type connects events causally and geographically:

type EventType =
  | 'battle'
  | 'treaty'
  | 'coronation'
  | 'death'
  | 'birth'
  | 'migration'
  | 'founding'
  | 'disaster'
  | 'invention'
  | 'trade_contact'
  | 'religious'
  | 'political'
  | 'cultural';

interface HistoricalEvent {
  id: string;
  name: string;
  date: HistoricalDate;
  dateEnd?: HistoricalDate;
  type: EventType;
  location?: GeographicPoint;
  participants: string[]; // person / polity ids
  description: string;
  sources: HistoricalSource[];
  causes?: string[]; // event ids
  consequences?: string[]; // event ids
  significance: 'local' | 'regional' | 'civilizational' | 'global';
  tags: string[];
}

Further types, organized by sub-domain:

Historiography: HistoricalPeriod, HistoricalSource (with a 1-5 reliability score), HistoriographyEntry, HistoriographicalSchool (12 schools), CausationChain, CausationFactor, CausationConsequence.

Prosopography: HistoricalPerson, PersonName, PersonRelationship, RelationshipType, GenealogicalTree, GenealogicalNode, ProsopographicalNetwork, NetworkNode, NetworkEdge, SocialStatus.

Geography: GeographicPoint, GeographicRegion, PopulationEstimate, BorderChange, TradeRoute, TradedCommodity, MigrationEvent.

Archaeology: ArchaeologicalSite, SiteType, StratigraphicLayer, DatingMethod, DateEstimate, ArtifactRecord, ArtifactCategory.

AI discovery: SatelliteImageryFeature, PredictiveModel, PredictiveVariable, SitePrediction, PatternRecognitionResult.

Anthropology: KinshipSystem, KinshipTerminologySystem, RitualSystem, CulturalMaterialSystem, EthnographicRecord.

Bioarchaeology: SkeletalAnalysisResult, AgeAtDeath, SkeletalPathology, ActivityMarker, DentitionAnalysis, AncientDNAResult, AdmixtureComponent, IsotopeAnalysis, Taxon.

Economic history: HistoricalCurrency, PriceSeriesEntry, EconomicSystem, EconomicRegime, TradeNetworkNode.

Data constants include HISTORICAL_PERIODS, HISTORICAL_TRADE_ROUTES, ARCHAEOLOGICAL_SITES, KINSHIP_SYSTEMS, and HOMO_LINEAGE. Functions include getPeriodByYear, formatHistoricalDate, yearSpan, buildCausationChain, rankCausationFactors, buildGenealogicalTree, computeNetworkCentrality, findShortestRelationshipPath, calculateRouteLength, haversineDistance, routeSpanYears, computeStratigraphicSequence, findArtifactsByCategory, getBestDateEstimate, scoreFeatureSignificance, clusterFeaturesProximity, runPredictiveModel, detectRitualLandscape, classifyKinshipSystem, analyzeRitualStructure, computeCulturalDiffusion, estimateDietFromIsotopes, isMigrant, estimateLifeExpectancy, assessNutritionalStatus.

9. Experience — Adaptive Learning Engine (@mnemosyne/experience)#

@mnemosyne/experience is the adaptive learning, gamification, and analytics engine. It is where dynamic skill modelling (BKT, DKT), Zone of Proximal Development management, and the core gamification loop all live.

9.1 Knowledge Tracing#

BKT models the latent probability that a learner has truly mastered a skill. The four parameters capture the probabilistic nature of learning and performance:

interface BKTParams {
  p_init;
  p_learn;
  p_slip;
  p_guess;
} // four params
interface BKTState {
  skillId;
  p_known;
  observationCount;
}

const DEFAULT_BKT_PARAMS: BKTParams;

updateBKT(state, params, correct) applies the Bayesian Knowledge Tracing update rule; initBKTState initialises state for a new skill.

Deep Knowledge Tracing uses an LSTM-style decay model: DKTFeatureVector, DKTState, initDKTState, updateDKTState.

9.2 Trajectory and ZPD#

These types and functions keep the learner working at appropriate difficulty by reasoning about Zone of Proximal Development:

LearningItem, TrajectoryConfig, optimiseLearningTrajectory, sequenceByPrerequisites (topological ordering, returns null on cycle). ZPDZone (too_easy / zpd / too_hard), classifyZPD. CognitiveLoadEstimate + estimateCognitiveLoad (this package's own variant, distinct from @mnemosyne/core's version). Multi-armed bandit: BanditArm, ucb1SelectArm, updateBanditArm. Reinforcement-learning policy: RLState, RLAction, selectRLAction.

9.3 Learner Modelling#

Learner modelling types track cognitive style, daily performance patterns, fatigue, and session calibration:

ContentModality (visual / auditory / reading / kinesthetic), LearningStyleProfile, createLearningStyleProfile, updateLearningStylePreference; TimeOfDayProfile, buildTimeOfDayProfile; FatigueModel, estimateFatigue; SessionLengthRecommendation, recommendSessionLength; ReviewNewBalance, balanceReviewNew; DifficultyRamp, calibrateDifficultyRamp. A/B testing: ABTestVariant, ABTest, createABTest, assignABTestVariant, concludeABTest.

9.4 Gamification#

The gamification system provides XP economy, achievements, social structures, and accessibility tooling. Key types and constants:

LevelDefinition + LEVEL_DEFINITIONS constant; UserXPState, calculateLevel, awardXP, XP_REWARDS constant. Achievements: AchievementCategory, Achievement, ACHIEVEMENT_CATALOG, checkAchievements. Streaks: StreakState, updateStreak. Challenges: Challenge, generateDailyChallenges. Leaderboards: LeaderboardEntry, LeaderboardType (global / friends / league / weekly), buildLeaderboard. Leagues: League (Bronze … Obsidian), LeagueDefinition, LEAGUE_DEFINITIONS, determineLeaguePromotion. Economy: VirtualCurrency, ShopItem, SHOP_CATALOG, purchaseShopItem. Avatars: AvatarConfig, AVATAR_BASE_STYLES, AVATAR_ACCESSORIES, BACKGROUND_SCENES, createDefaultAvatar. Social: UserProfile, ShareableCard, createShareableCard, TeamChallenge, updateTeamChallengeProgress, StudyGroup, createStudyGroup, joinStudyGroup, TutorProfile, TuteeRequest, matchTutorTutee. Skill trees: SkillNode, SkillTree, HUMANITIES_SKILL_TREE. Certificates and quests: Certificate, issueCertificate, Quest, SAMPLE_QUESTS.

10. Gamification-Plus (@mnemosyne/gamification-plus)#

@mnemosyne/gamification-plus adds advanced, Duolingo-style competitive gamification. It is a self-contained library with no code dependency on @mnemosyne/experience. The six-tier league system is the primary new concept it introduces:

type LeagueTier =
  | 'Bronze'
  | 'Silver'
  | 'Gold'
  | 'Platinum'
  | 'Diamond'
  | 'Obsidian';
type LeagueStatus = 'active' | 'promotion_zone' | 'demotion_zone';

LEAGUE_DEFINITIONS is a Record<LeagueTier, LeagueDefinition>. League functions: createLeague, addParticipantToLeague, rankLeague, resolveLeagueWeek (computes promotions / demotions), getNextTier, getPreviousTier, matchLeaguesByActivity. Types: LeagueDefinition, LeagueParticipant, League.

XP multiplier events: XPMultiplierEvent, createXPMultiplierEvent, getActiveXPMultiplier. Friend challenges: ChallengeStatus, FriendChallenge, createFriendChallenge, acceptChallenge, updateChallengeProgress. Team leagues: TeamLeague, Team, createTeam, updateTeamXP. League achievements: LeagueAchievementId, LeagueAchievement, LEAGUE_ACHIEVEMENTS, checkLeagueAchievements. Anti-gaming: AntiGamingAnalysis, analyseAntiGaming.

Streak milestones are defined at specific day counts, and the system awards multiplied XP for reaching them:

STREAK_MILESTONES: [3, 7, 14, 21, 30, 60, 100, 150, 200, 365, 500, 1000]

Streak functions: StreakState, STREAK_MILESTONES, STREAK_XP_MULTIPLIERS, computeStreakMultiplier, createStreakState, updateStreak, streakRepairCost, repairStreak, checkMilestone, celebrateMilestone, purchaseStreakFreeze, purchaseStreakInsurance, activateGracePeriod.

Habits and scheduling: HabitTracker, createHabitTracker, updateHabitTracker, StudySchedule, StudyReminder, CalendarEvent, createStudySchedule, generateCalendarEvents, buildStreakSocialShareText.

Seasonal events: EventType, LearningEvent, EventReward, EventBadge, CommunityGoal, ContentPack, PartnerInfo, EventLeaderboardEntry, createLearningEvent, updateCommunityGoal, getCountdownSeconds, addEventLeaderboardEntry, SAMPLE_SEASONAL_EVENTS, UserEventProposal, createEventProposal, getActiveEvents, getUpcomingEvents.

11. Immersion (@mnemosyne/immersion)#

The immersion package implements comprehensible-input and immersion methodology across four sub-domains: general difficulty scoring, sentence mining, video immersion, reading immersion, and listening immersion.

• Morpheme analysis — MorphemeFrequency, MorphemeAnalysis, FREQUENCY_SAMPLES, analyseMorphemes.
• Difficulty / comprehension — SentenceDifficultyScore, scoreSentenceDifficulty, estimateComprehension, ImmersionContent, buildDifficultyLadder, recommendIPlus1Content (i+1 content selection).
• Refold staging — RefoldStage (1-4), RefoldStageDefinition, REFOLD_STAGES, determineRefoldStage.
• Immersion sessions — ImmersionMode (active / passive / intensive), ImmersionSessionRecord, createImmersionSession, ImmersionStats, computeStreaks, computeImmersionStats, WordDensityMap, buildWordDensityMap.
• Acquisition vs learning — AcquisitionMode, AcquisitionProfile, analyseAcquisitionBalance.
• Sentence mining — MinedSentence, SubtitleEntry, parseSRT (SRT subtitle parser), extractMiningSentences, filterOneTargetSentences (1T sentences), SentenceQualityFactors, scoreSentenceQuality, computeJaccardSentenceSimilarity, detectNearDuplicates, BilingualSubtitle, alignBilingualSubtitles, CardTemplate, CardTemplateDefinition, CARD_TEMPLATES.
• Video immersion — VideoDifficultyTier, VideoDifficultyDefinition, VIDEO_DIFFICULTY_TIERS, VideoContent, CreatorProfile, classifyVideoDifficulty, SubtitleWord, InteractiveSubtitle, buildInteractiveSubtitle, VideoWatchHistoryRecord.
• Reading immersion — WordStatus (1|2|3|4|5|'known'|'ignored'), TrackedWord, createTrackedWord, advanceWordStatus, WORD_FAMILIARITY_LEVELS, ReadingSessionRecord, createReadingSession, computeReadingStats, GradedReader, GRADED_READER_CATALOG, ParallelTextSegment, buildParallelText, PopupDictionaryEntry, buildPopupEntry.
• Listening immersion — PodcastFeed, PodcastEpisode, SAMPLE_COMPREHENSIBLE_PODCASTS, AudioCondensationConfig, DEFAULT_CONDENSATION_CONFIG, AudioTimestamp, ListeningJournalEntry, createListeningJournalEntry, ListeningLevelAssessment, assessListeningLevel, recommendPodcasts, ListeningExerciseType, ListeningExercise, generateGapFillExercise, ListeningQuizQuestion, generateComprehensionQuiz, RadioStation, SAMPLE_RADIO_STATIONS.

The package exports an IMMERSION_CAPABILITIES summary constant.

12. Community (@mnemosyne/community)#

The community package provides language-exchange and peer-learning infrastructure. It is the only package in the domain that models real-time social interactions (voice rooms, whiteboard).

• Partner matching — LanguageProfile, ExchangeProfile, MatchScore, computeMatchScore, findLanguagePartners; PartnerRating, createPartnerRating, computeAverageRating; ReportReason, UserReport, createUserReport.
• Exchange sessions — ExchangeSessionStatus, ExchangeSession, scheduleExchangeSession, checkTimeSplitBalance; PartnerRelationship, createPartnerRelationship, updatePartnerRelationship.
• Chat with inline correction — MessageType, CorrectionType, InlineCorrection, ChatMessage, createTextMessage, applyInlineCorrection, renderCorrectionMarkup, saveVocabularyFromCorrection; ConversationTopicSuggestion, TOPIC_SUGGESTIONS, suggestConversationTopics.
• Transliteration (transliteration.ts) — TransliterationRequest, TransliterationResult, buildTransliterationRequest, and a transliterate dispatcher backed by per-script implementations: transliterateKanaSequence, transliterateKanji, transliterateHangul, transliterateCyrillic, transliterateArabic, transliterateDevanagari, transliterateThai, transliterateGeorgian.
• Whiteboard — WhiteboardElement, Whiteboard, createWhiteboard, addWhiteboardElement.
• Social moments — MomentType, MomentVisibility, Moment, MomentCorrection, createMoment, addMomentCorrection, filterMomentsForLearner, MomentAnalytics, computeMomentAnalytics; WritingPrompt, WRITING_PROMPTS, detectSpam.
• Voice rooms — RoomStatus, ParticipantRole, VoiceRoomParticipant, VoiceRoom, LiveTranscriptSegment, RoomParticipationStats, createVoiceRoom, joinVoiceRoom, toggleHandRaise.

13. Platform — Integration Library (@mnemosyne/platform)#

@mnemosyne/platform provides data interchange and external-service integration descriptors. Like the rest of the domain, it is a pure library: it builds request URLs and parses payloads, but does not itself perform network I/O.

• Anki interchange — AnkiField, AnkiNote, AnkiDeck, AnkiNoteModel; parseAnkiDeck (parses a simplified Anki deck JSON export — an .apkg deconstruction, not the binary archive) and exportAnkiDeck.
• CSV vocabulary — VocabularyEntry, CSVImportResult, parseCSVVocabulary.
• LMS / e-learning standards — SCORMManifest + parseSCORMManifest; XAPIStatement, XAPI_VERBS, createXAPIStatement; LTIConfig, LTILaunchParams, validateLTILaunch.
• Reference managers — ZoteroItem, parseZoteroExport.
• Portable data / privacy — PortableProgressData, buildPortableProgressData; GDPRDataPackage, buildGDPRPackage.
• Public API descriptors — APIEndpointDefinition and the PUBLIC_API_ENDPOINTS constant describe a REST surface a hosting application could expose; they are declarative metadata, not a server.
• External content connectors (URL builders + payload parsers) — Wikipedia / Wikidata (buildWikipediaSearchUrl, buildWikidataSparqlUrl, extractLearningContentFromWikipedia), Europeana (buildEuropeanaSearchQuery), Internet Archive (buildArchiveSearchUrl), dictionaries (DICTIONARY_PROVIDERS), translation (TRANSLATION_PROVIDER_CONFIGS), museum APIs (MUSEUM_API_CONFIGS, buildMetObjectSearchUrl), and library catalogs (buildSRUQueryUrl).
• LLM configuration — LLMProvider, LLMConfig (configuration shapes for consuming applications).

14. Other Domain Libraries#

The table below covers the five remaining packages, listing their most significant exported symbols. Each is fully implemented with domain-specific algorithms and real data constants.

15. Validation, Invariants, and Acceptance Criteria#

Input Validation#

Each package declares zod as a runtime dependency for schema validation. Algorithmic functions enforce input invariants directly with RangeError rather than silently producing incorrect results:

• calculateRetention rejects non-positive stability.
• irt2PL / irt3PL reject non-positive discrimination.
• irt3PL rejects a guessing parameter outside [0, 1).
• fsrsInterval requires requestRetention ∈ (0, 1).

Invariants Enforced in Code#

These invariants are maintained by the implementation and cannot be violated through normal function calls:

• SM-2 ease factor is clamped to a minimum of 1.3.
• FSRS difficulty is clamped to [1, 10]; stability has a floor of 0.1; a lapse never increases stability.
• FSRS intervals are clamped to [1, maximumInterval].
• KnowledgeGraph.addEdge rejects edges whose source or target node is absent.
• KnowledgeGraph.topologicalSort throws when a cycle exists in the prerequisite sub-graph.
• CertificationManager.issueCredential returns null unless every requirement is satisfied.
• PeerAssessmentManager.createAssignments skips a reviewer who is the author.
• Adaptive difficulty does not adjust until minResponsesBeforeAdjust responses have been observed.

Acceptance Criteria#

Every package ships a co-located Vitest suite (src/<name>.test.ts, plus *-extended.test.ts where the package is split). The tests assert domain correctness against known values — they would fail on random or hardcoded returns. Representative concrete assertions from the test suite:

• MASTERY_LEVELS.length === 6
• ILR_LEVELS.length === 11
• FSRS_DEFAULT_PARAMETERS.w.length === 17
• FSRS_DEFAULT_PARAMETERS.requestRetention === 0.9
• DEFAULT_CAT_CONFIG.maxItems === 50
• REVIEW_GRADE_MAP mapping again/hard/good/easy → 1/2/3/4

A package is considered complete when its tsc build and vitest run pass and it provides genuine domain algorithms rather than only CRUD operations.

16. Configuration#

Mnemosyne libraries are pure, dependency-injected TypeScript. They do not read environment variables, connect to PostgreSQL/Redis, or call LLM/TTS services on their own. All configuration is supplied through typed function parameters and exported default constants that a consuming application can override.

LLM-backed features accept an injected LLMProvider; with no provider they fall back to the deterministic template/algorithmic implementations described in §2.4. Any database, cache, embedding service, or HTTP layer is the responsibility of a consuming application. @mnemosyne/platform (§13) parses and emits Anki deck JSON and builds external-service request URLs, but binary .apkg archive handling, cross-calendar numeric conversion, webhook delivery, and a running HTTP server do not exist inside libs/mnemosyne/* today.

17. Integration Points#

Inbound Dependencies#

@mnemosyne/* packages import only zod and (for non-core packages) @mnemosyne/core. The AI infrastructure accepts an injected LLMProvider implementation from the caller. No package opens a network connection or reads a process environment variable.

Cross-Domain Boundary#

The Mnemosyne packages declare no @oshun/*, @sophia/*, or @metis/* dependency. This boundary is intentional: Mnemosyne is a library of pure learning-science and humanities-knowledge functions, not a service.

The data that would flow across this boundary if a consuming application chose to integrate Mnemosyne with other Oshun domains:

• Outbound from Mnemosyne: LearnerProfile, AssessmentResult, KnowledgeItem, LearningPath, ReviewResult — structured learning records that other domains might use for enrichment or analytics.
• Inbound to Mnemosyne: An LLMProvider implementation for AI-backed features; content payloads for the knowledge graph or vocabulary database.

Any cross-domain orchestration (Sophia knowledge enrichment, Metis assessment sharing) is assembled in a consuming application, not inside this domain.

18. Phase Reference#

Mnemosyne is implemented as Phase 39 of the Oshun migration plan (TODOS/phase-39.md), "Mnemosyne Domain — Humanistic Learning & Cultural Intelligence Platform". The table below maps sub-sections to the 19 libraries they cover.