Your own material, a runnable course: spaced repetition, retrieval practice, real grading, zero dependencies.

Project Telos | gather | crucible | index | forum | telos | learn | emet | buildlang

learn turns whatever you are studying, a course, a certification, or your own notes, into a runnable learning loop. Spaced repetition schedules your reviews, retrieval practice builds cloze prompts from your own drafts, misconception tracking spends your next session where you are actually weak, and a concept map gates readiness on prerequisites. One command, learn tutor study, composes all of it into a single plan from your recorded attempts. A second engine automates course and certification logistics while halting at every graded step so the work is yours. Zero external dependencies, Node 20 or newer.

Features

• One-command study plans. learn tutor study composes what is due, what you keep getting wrong, an interleaved practice order, prerequisite readiness, and the mastery verdict into a single plan from your own recorded attempts.
• Adaptive per-item memory model (opt-in). An FSRS-class scheduler tracks per-item difficulty, stability, and retrievability, decays each item's recall probability on its own curve, and surfaces the item you are most likely to have forgotten, against a retention target you set (for example 90%). Grade each attempt 0 to 4. It is a scheduling hint, never a verdict: the mastery gate reads only your witnessed attempts, so the schedule can never move the "ready" line.
• Spaced repetition by default. An SM-2-lite/Leitner scheduler over your practice log; tutor due reports which objectives are overdue, most-overdue first. Timestamps are injected with --now, so every schedule is deterministic and re-checkable.
• Re-derivable schedule + per-learner fit. tutor derive-schedule replays your witnessed graded log to rebuild the FSRS scheduling state from scratch, then audits it against the cached itemState: a stale or tampered cache is caught as DRIFT with a per-field diff, never silently trusted. --optimize fits an advisory per-learner initial-difficulty prior from your own accuracy; it never changes the audit verdict or the mastery gate.
• Retrieval practice from your own material. Claims your own draft asserts become blanked cloze prompts you answer from memory, each carrying its source so you check yourself after, not before.
• Misconception targeting. Your wrong attempts and your own feedback are aggregated per objective, ranked by count, so the next session spends time where it is actually needed.
• Predict-then-observe. Record a prediction before you see a rendered aid or worked example, then score it against what happened. A pending prediction is never silently counted correct.
• Self-explanation with a real check. Your explanation of a concept is bucketed into grounded, shaky, and unverifiable claims, so "explain it back" gets a check instead of a vibe.
• Concept map with prerequisite gating. Objectives (plain strings or {id, text, requires}) get a topological learning path; you are never told to study something whose prerequisite you have not passed.
• Proof-packet lessons. tutor prooflesson turns a verified-claim packet (sources, hashes, MATCH/DRIFT/UNVERIFIABLE verdict) into a lesson: a scaffold that prompts you to derive the reasoning yourself, retrieval questions from the packet's own fields, and a binding to the packet's verdict. A failed packet also yields a typed misconception record.
• Re-verifiable receipts. tutor reverify recomputes a receipt's own evidence: the hash chain must recompute (a break is typed CHAIN_BROKEN) and the mastery verdict must re-derive from the recorded attempts (VERDICT_MISMATCH otherwise). A chainless receipt is UNVERIFIED, never verified.
• Credential-logistics engine. learn run executes a declarative course workflow and halts at every graded assess step, plus consent, CAPTCHA, payment, and account creation. Nothing graded ever auto-completes, in either submission mode.
• Zero-dep MCP server. src/mcp.mjs exposes fourteen advisory/read tools over stdio JSON-RPC for agent use; actuation stays operator-driven on the CLI.

Install

git clone https://github.com/HarperZ9/learn.git
cd learn
node --test          # 284 tests, zero dependencies, nothing to build

Or install the published release: npm install -g @harperz9/learn (the repository can run ahead of the latest npm publish; the repo is the source of truth). Library use is available through the package exports @harperz9/learn, @harperz9/learn/doctor, and @harperz9/learn/status.

Quickstart

node src/cli.mjs tutor plan mysession --topic "derivatives" --objectives "power-rule,chain-rule"
node src/cli.mjs tutor record mysession --objective power-rule --prompt "d/dx x^3" --answer "3x^2" --correct true
node src/cli.mjs tutor study mysession --now 2026-06-30T00:00:00Z
node src/cli.mjs tutor mastery mysession

Expected output of tutor study after that one attempt:

tutor study mysession: 1 due, 0 misconception(s), mastery not yet
  due: chain-rule
  order: power-rule, chain-rule
  readiness: power-rule:unlocked, chain-rule:unlocked

tutor study is the one command to run first: it composes what is due, what you keep getting wrong, a mixed practice order, and the mastery-gate verdict, all from your own recorded attempts.

For the adaptive scheduler, create the session with --enable-fsrs, grade attempts 0 to 4, and ask for a retention-targeted plan:

node src/cli.mjs tutor plan sess --topic "SC-900" --objectives "identity,compliance" --enable-fsrs
node src/cli.mjs tutor record sess --objective identity --grade 3 --now 2026-06-30T00:00:00Z
node src/cli.mjs tutor study sess --now 2026-07-15T00:00:00Z --use-fsrs --desired-retention 0.9

The flags are advisory: on a session created without --enable-fsrs they fall back to the Leitner/interleave path.

A worked session

Record a wrong attempt with feedback, watch the plan shift, then emit and re-verify a receipt:

node src/cli.mjs tutor record mysession --objective chain-rule \
  --prompt "d/dx sin(x^2)" --answer "cos(x^2)" --correct false --feedback "forgot inner derivative"
node src/cli.mjs tutor misconceptions mysession
# tutor misconceptions mysession: 1 objective(s)
#   chain-rule (1x): forgot inner derivative

node src/cli.mjs tutor study-receipt mysession --now 2026-06-30T00:00:00Z
# tutor study-receipt mysession: verified true, mastery not yet -> tutor/mysession.study-receipt.json

node src/cli.mjs tutor reverify mysession
# tutor reverify mysession: VERIFIED (1 receipt(s))

The misconception now steers the next tutor study plan, and the receipt re-verifies from its own recorded evidence rather than a stored boolean.

The credential engine

The second engine turns a declarative workflow into a witnessed run: navigate a course, open a module, reach a graded step.

node src/cli.mjs run examples/course.json --id run1
node src/cli.mjs resume run1 --attest "completed Quiz 1 myself"
node src/cli.mjs verify run1
node src/cli.mjs receipt run1

At every assess step (and at consent, CAPTCHA, payment, or account creation) it halts and waits for you. When you resume, your attestation is recorded alongside everything the engine actually did. Drivers: FakeDriver (offline, deterministic) and NativeDriver (real browser over native-control). An adapter pack covers Coursera, Udemy, LinkedIn Learning, edX, Credly, Microsoft Learn, NonprofitReady, and generic self-paced courses, with no graded logic anywhere. See docs/smoke.md for an operator-run live-LMS walkthrough.

MCP server

node src/mcp.mjs

Exposes the advisory/read tools over stdio JSON-RPC: learn_doctor, learn_status, learn_verify, learn_receipt, learn_dry_run, learn_tutor_plan, learn_tutor_record, learn_tutor_mastery, learn_tutor_due, learn_tutor_studyplan, learn_tutor_misconceptions, learn_tutor_reverify, learn_tutor_prooflesson, and learn_visualize_dry_run. The MCP surface never performs a real course action or answers a graded step.

Status

• Release: 1.6.0; command learn; Node >= 20; zero external dependencies (ES modules, node:test).
• CLI surface: learn status, learn doctor, learn run/resume/verify/receipt, learn assist, learn visualize, and learn tutor <plan|record|mastery|receipt|reverify| prooflesson|due|misconceptions|retrieval|explain|predict|score|path|study|study-receipt>.
• Tests: 284 across the runtime, adapters, receipt, tutor/learning-loop, and telos interop, including a falsifiable test per integrity invariant. learn doctor re-checks the invariants at runtime and must report MATCH on every line.
• History: CHANGELOG.md.

Integrity boundary

learn never produces, hints, or auto-fills an answer to a graded assessment; the mastery() verdict is a function of your own scored practice attempts only, never of a render, a visualization, or a pending prediction. Every run writes a witnessed, hash-chained receipt that separates automated logistics from your own graded work, and tutor reverify re-checks a receipt from its recorded evidence. If you can get any command to cross that line, that is the most useful bug report this tool can receive: every such path has a falsifiable test.

Docs

• docs/INTRODUCTION.md: what learn is, core concepts, and a first-ten-minutes walkthrough.
• docs/HOW-IT-WORKS.md: the study loop step by step: plan, due, retrieval, predict-then-observe, self-explanation, misconceptions, mastery-gate, witnessed receipt.
• docs/ARCHITECTURE.md: the accountability spine (witness, ledger, gate) and how both engines are built from it.
• USAGE.md: install and basic usage for both engines and the MCP surface.
• docs/ENTERPRISE-READINESS.md: context-envelope and action-receipt contract for unattended agent workflows.
• docs/smoke.md: operator-run live-LMS smoke test.
• AGENTS.md: scope, developer contract, and verification commands.
• CONTRIBUTING.md and AUTHORS.md.
• docs/brand/README.md: brand assets (docs/brand/learn-hero.png, docs/brand/learn-hero.svg, docs/brand/learn-mark.svg) and their provenance.

Peer tools: gather (source receipts) and crucible (measured claim evaluation) power the assist pillar; telos renders math/physics concepts as witnessed learning aids via its math_physics lane.

License

Fair Source (see LICENSE), including a binding integrity clause: derivatives may not remove the guarantee that graded assessments always halt for the human.

For developers

Keep the public README, package metadata, and examples aligned with current behavior. Before opening a PR, run the full suite.

node --test
node src/cli.mjs doctor