MergeLearn

MergeLearn is a local-first, model-free learning tool. Your own coding agent writes the lessons; MergeLearn stores them, schedules reviews with FSRS, and gives you a local website to learn from. It ships no model, account, telemetry, or required network service. Authored Mermaid diagrams may load their renderer from jsDelivr when displayed; no lesson or library data is sent with that request.

How you use it

npm install -g mergelearn
mergelearn setup-agent

Then open your coding agent in a repository and ask:

Create a MergeLearn lesson from my last PR.

For worthwhile work, the agent reads relevant recent lessons, writes an AgentSetPatch, and runs mergelearn apply --file <patch.json> --open. That single action validates and stores the lesson, starts or reuses one local server, opens its exact URL, and prints the URL as a fallback. It may deliberately create no lesson when the work has no durable learning value.

mergelearn serve reuses the same managed local server; --port 4321 requests a fixed port only when it needs to start one. The server closes after inactivity. Home lists lessons with their objective, estimated time, progress, and one Start / Continue / Practice again action. Due spaced-repetition reviews stay separate.

Home keeps authored lessons and spaced-repetition reviews separate.

Try it before using an agent

From the empty Home page, click Try a sample lesson, or run:

mergelearn sample
mergelearn serve

The sample is opt-in, offline, and demonstrates every question type. Running the command again does not create duplicates.

Try the interview-pattern example

examples/interview-pattern-lesson.json is an original, opt-in lesson with only reserved example.org references. Import it through the normal authoring gate:

mergelearn apply --file examples/interview-pattern-lesson.json --open

When authoring transfer practice, fade guidance from a worked example to a completion task, then a near-miss and an unlabelled transfer prompt. Keep problem and pattern identity out of the prompt and context when those labels would reveal the approach. Put them in the explanation or post-reveal references instead. Include competing approaches when constraints change the right choice; state the tradeoff rather than presenting one pattern as universally best. Never copy a problem statement or claim a company asked it. Dated list or company labels are provenance only, not verification or frequency claims.

Practice from evidence and supplied references

Open mergelearn serve, then choose Practice. Review due starts a graded, scheduled session. The read-only Strengthen weak areas mode contains cards with enough persisted retrieval failures, while External problems contains author-supplied references. Repeated set, tag, and source query parameters make those filtered views shareable. Source filters affect external references only. Strengthen and External problems never write FSRS state or imply readiness.

Install details

Requirements: Node.js 20 or newer. Git is needed only for lessons that cite repository code.

setup-agent auto-detects installed coding agents. Supported agents: claude (Claude Code), codex, cursor, opencode, and gemini.

mergelearn setup-agent                                  # detected agents, global
mergelearn setup-agent --agent all                      # every supported agent
mergelearn setup-agent --agent claude,codex --scope project
mergelearn setup-agent --dry-run                        # preview, write nothing
mergelearn setup-agent --uninstall                      # remove managed copies
mergelearn doctor                                       # read-only setup diagnosis

The installer copies the canonical skills (no symlinks), records checksums so reruns are idempotent, and never overwrites a copy edited by hand. Unsupported agents can read skills/mergelearn-authoring/SKILL.md directly.

Question types

Cards are attempt-first: you act before the answer is revealed, and the reveal is feedback on your attempt.

• Multiple choice. Pick one or several options, graded in the browser.
• Text answer. Write a short answer, then self-grade against the expected one. Good for explain-why prompts.
• Code ordering. Reorder shuffled code blocks into the correct sequence (click a block and use the arrow keys, drag it, or use the move buttons), graded by exact order.
• Flashcard. A plain reveal-then-self-grade card for pure recall.

Code-ordering activities work with the mouse or keyboard. Select a tile, move it with the arrow keys or visible buttons, or drag it into place.

After an attempt, MergeLearn reveals deterministic feedback and the authored explanation. Pre-reveal confidence is recorded for calibration and does not affect FSRS. Your post-reveal Again, Hard, Good, or Easy grade controls scheduling; answer correctness is stored separately as learning evidence.

Feedback appears only after the attempt; the learner still chooses the review grade.

Ways to use it

• Learn a codebase. Ask your agent to author lessons from real files; cited code is frozen at a pinned commit so the lesson stays stable.
• Learn a concept. Skip the repo and ask for a conceptual lesson on any topic (a language feature, an algorithm, a protocol).
• Keep it fresh. Review the due queue in the browser now and then; FSRS spaces cards so you revisit them right before you would forget.
• Preview before you trust it. Run mergelearn apply --dry-run on an agent's output to see what would be created before it touches your library.

CLI commands

The browser is the main interface. Core library inspection, maintenance, and review grading are also available on the command line.

mergelearn context     [--goal "..."] [--repo <path>] [--target-set <id>] [--recent <n>]
mergelearn apply       --file <patch.json> [--agent <name>] [--open] [--dry-run]
mergelearn skip        --task <text> --reason <text>
mergelearn sample      [--dry-run]
mergelearn doctor
mergelearn status
mergelearn list        <sets|cards|due> [filters]
mergelearn archive     <setId/cardId>
mergelearn unarchive   <setId/cardId>
mergelearn edit        <setId/cardId> [content options]
mergelearn delete      <setId|setId/cardId> --yes [--force]
mergelearn settings    [--review-session-cap <n>] [--queue-strategy overdue|interleaved]
mergelearn list due    [--set <id>] [--tag <id>] [--folder <path>] [--limit <n>] [--quiet] [--if-any]
mergelearn show        <setId/cardId>
mergelearn grade       <setId/cardId> <1-4>
mergelearn mastery
mergelearn weak
mergelearn check       [--set <id>] [--archived]
mergelearn prune       [--set <id>] [--yes]
mergelearn export      --set <id> --output <lesson.mergelearn.zip>
mergelearn import      --file <lesson.mergelearn.zip> [--as-copy] [--dry-run]
mergelearn backup      --output <profile.mergelearn-backup.zip>
mergelearn restore     --file <profile.mergelearn-backup.zip> [--force] [--dry-run]
mergelearn serve       [--port <n>]
mergelearn setup-agent [--agent <ids|all>] [--scope global|project] [--dry-run] [--uninstall]

Global options work before or after any operational command: --home <path> selects the library, --json emits machine-readable output, and --yes confirms destructive or bulk actions. Run mergelearn help <command> for full options or mergelearn help --all for internal and deprecated spellings.

list cards --json returns every match by default, wrapped so a page can never be mistaken for the whole library:

{ "cards": [ ... ], "total": 400, "returned": 400, "truncated": false }

Human output pages at 100 rows and prints showing 100 of 400 to stderr, keeping stdout pipeable. --limit <n> pages deliberately and sets truncated: true; --limit 0 means no cap. The deprecated cards alias returns the same envelope, so there is one JSON contract rather than two.

Progress is reported as two separate measures, because one number cannot express both. mastery shows how much of a tag or folder has been learned (reached review at least once) next to how much is still retained right now (current FSRS recall probability over the cards actually studied), with the studied count alongside so the denominator is never a mystery. Rows are ordered weakest first. weak goes further and names the individual cards you keep failing to recall, using recorded review evidence; it stays silent rather than ranking cards whose history is too thin to judge.

status also answers "is there anything to do?" by reporting the due count. due --if-any --quiet prints one line when reviews are waiting and nothing at all when they are not, which makes it safe to call from a shell prompt hook.

context prints the current library state for an agent; --goal is optional but helps focus the lesson, while --recent exposes recent question summaries, source paths, and review state. apply --open is the normal agent workflow: it validates, stores, starts or reuses one local GUI, opens the exact lesson, and prints the URL. apply without --open is the lower-level storage primitive for scripts and dry runs; skip records meaningful completed work for which the developer deliberately made no lesson. Early-stage "Worth it" feedback controls are shown by default; set MERGELEARN_DOGFOOD_CONTROLS=0 before starting the server to hide them.

Each lesson is included in spaced repetition by default. Its lesson page has an Include in spaced repetition checkbox for a reversible learn-once opt-out.

Lesson identity is explicit: omitting set.id always means "create a new lesson", and passing an existing set.id means "update or append to that one". An omitted id that slugifies onto an existing lesson is rejected with set:id_collision rather than merged, because two unrelated lessons can share a title and a silent merge overwrites the first lesson's metadata.

Learner-owned state survives later agent re-imports of the same lesson. An agent refreshing its teaching text replaces the question, answer, explanation, interaction, tags, and citations, but review history, scheduling state, creation provenance, the learn-once preference, and an archived card's archived status are all preserved. Refreshing a lesson never resets progress or resurrects a card you archived.

Lesson bundles contain authored teaching content, interactions, referenced tags, assets, and frozen source excerpts. They exclude review schedules, sessions, preferences, agent metadata, and local repository identifiers. Private profile backups are different: they preserve learning state, history, configuration, and the repository registry. Backup files are unencrypted and should be stored securely.

Storage layout

The library lives at ~/.mergelearn/ (override with MERGELEARN_HOME or --home).

~/.mergelearn/
  library/
    tags.json                     the taxonomy that links topics together
    folders.json
    sets/<setId>/
      set.json
      order.json                  the teaching order
      cards/<cardId>.json         one file per card
  repos/registry.json             stable repoId -> path (optional)
  profile/sessions/<date>/        one file per review sitting
agent-skills.json                 manifest of skills installed via setup-agent

Privacy

• No telemetry, no required network calls, no bundled model.
• Your coding agent does the authoring; MergeLearn never sends code anywhere.
• Cited code is read from your local disk and frozen at a pinned commit.

See docs/PRIVACY.md for details.

Verification

npm run check          # tsc --noEmit
npm test               # vitest
npm run build          # emit dist/
npm run smoke          # build + CLI --help
npm run smoke:package  # pack the tarball and run the packaged binary

License

Licensed under the Apache License 2.0. MergeLearn is free to use, modify, and distribute under its terms.