learn-everything

English · 中文

An AI tutor that teaches you many subjects at once — and remembers. It installs as a skill into any Skill-capable AI assistant (Claude Code, Obsidian via Claudian, and others). Talk to it in plain language; it teaches one concept at a time, captures what you understood (and where you stumbled), and quietly schedules spaced reviews so it actually sticks.

Status: alpha · License: MIT · Engine: Python stdlib only (zero deps) · Tests: full stdlib CI suite

You're usually learning several things at once — a professional domain, an exam, a coding skill — and each needs a different kind of teaching, so you lose the thread every time you switch. learn-everything is built to hold that thread for you across all of them.

---

What it does

• Teach-first, dialogic learning. It teaches you in dialogue (explain → you try → adjust → confirm), and only after you understand does it distill a few review cards. Understanding always comes before review material.
• Cross-track orchestration. Every subject is a "track" under one board. Ask "what should I do today?" and it answers across all of them at once — what's due to review, what's stale, what's near a deadline — and time-boxes a plan (tested at 25+ concurrent tracks; tune any track's weight or block size with set-prefs).
• It remembers you as a learner. Every session leaves a memory digest, your misconceptions, the terms you asked about, and a resume pointer — so days later it reconstructs "here's what you learned, where you got stuck, what's next."
• A real pedagogy toolkit. Evidence-based teaching methods — 7 standalone (read-along, Socratic, Feynman, worked-examples, deliberate-practice, active recall, elaboration) plus composable layers (dual-coding, metacognition, a silent learner-model). The tutor picks by material × learner × goal — its judgment, guided by the method files, not a hard-coded selector.
• Cross-host skill design. It runs as a skill in any Skill-capable AI assistant. One recommended setup is Obsidian + the Claudian plugin (read on the left, talk to the tutor on the right, notes grow live in your vault); Claude Code works too. Everything is plain markdown you own.
• Private by default & zero-dependency. Your track files stay local and gitignored. When you ask the tutor to learn a source, that source text is sent to the host model you are using; the engine itself is pure Python standard library — no pip install.

What you get

• A conversational tutor for any subject, in your language.
• Automatic, durable notes + a per-track "map of content."
• Spaced repetition (FSRS-6) that schedules reviews so knowledge sticks.
• A daily, time-boxed "what to study" plan across every subject.
• Captured misconceptions that feed forward — next session re-checks your weak spots and corrects the teaching route.
• A question heatmap — see which concepts you asked about most (your weak/important spots).
• Progress you can see: cards learned, cards locked into long-term memory, weekly accuracy.

Quick start (just talk to it)

learn-everything is a skill you install into any Skill-capable AI assistant, then talk to in plain language — you never touch a command line. The setup below uses Obsidian + the Claudian plugin, one recommended path; if you already use Claude Code, point it at this folder and skip to talking to the tutor.

Day 1 — one-time setup (~10 min):

1. Get the files: git clone https://github.com/lilialla/learn-everything.git.
2. Open it in Obsidian: Open folder as vault → pick the learn-everything folder.
3. Add the Claudian plugin (Community plugins → search "Claudian" → Install → Enable). It puts an AI tutor in the right sidebar that can read and write your vault.
4. (macOS) If Claudian shows a 401 / auth error: its bundled Claude needs a credential. Run claude setup-token in a terminal and paste the token into Claudian's settings as CLAUDE_CODE_OAUTH_TOKEN. (If you use Claude Code's subscription login, you can instead copy your keychain credential to ~/.claude/.credentials.json.)
5. (optional) Native review: add obsidian-spaced-repetition so the cards the tutor makes are also reviewable inside Obsidian.

Then just talk to the tutor in the right sidebar — no commands to remember:

• "I want to learn <topic>" / "teach me this article" (paste or open it)
• "pick up where we left off"
• "quiz me" · "what should I do today?" · "how am I doing?"

It teaches you one concept at a time, writes your notes into the vault as you go, and schedules reviews so things actually stick.

Coming back later: open the vault and ask "what should I do today?" — it leads with how many cards are due across everything. (Want a reminder without opening it? python3 scripts/registry.py nudge prints one plain line — "learn-everything: 7 cards due across 3 subjects … " — drop it in a Daily Note, a shell login, or a scheduled task/cron. No background daemon.)

How it works

        you talk (plain language)
                 │
   ┌─────────────▼──────────────┐     teach → understand → distill cards → review → resume
   │  learn skill (host adapter) │     reads your words, runs the engine, follows a method
   └─────────────┬──────────────┘
     methods/*.md │ scripts/*.py
   (how to teach) │ (deterministic state: scheduling, files, the board)
                 ▼
            tracks/<id>/   ← your learning, as plain markdown you own

Two layers, cleanly split:

• Portable core — a deterministic engine (scripts/: FSRS scheduling, per-track state files, the status board, the daily planner) in Python standard library only, plus a method layer (methods/*.md) of pedagogy templates that are just markdown data.
• Host adapters — the primary Claude Code skill (skills/learn/) turns your plain-language requests into engine calls and teaching loops. The skill is not the intelligence: the host model does the teaching by following the method layer; the engine only keeps the state honest (it never guesses a due date or a card id). mcp/server.py is an optional MCP host adapter over the same core.

The pedagogy toolkit

Teaching method is data (methods/*.md). The tutor picks one by reading the material × learner × goal and following the heuristics in those files — it's the model's judgment, not a hard-coded selector — and you only ever see the outcome ("I'll walk you through it" / "let me quiz you" / "explain it back"). The toolkit is 7 standalone pedagogies + 3 composable layers (dual-coding, metacognition, learner-model, folded into the others) + a cross-cutting learning-science; the exam / applied / reading-guide modes shape a whole track.

Method	For
tutor	read-along teaching — the default for knowledge/explanatory material
socratic	lead by questions; let you discover the answer
feynman	you explain it back; the model probes the gaps
active-recall	retrieval-practice quizzing — the review default (the FSRS partner)
worked-examples	procedural / math / coding — study a solved example, then fade the scaffolding
deliberate-practice	build a performable skill: isolate the edge, drill, immediate feedback
elaboration	the up-shift for a learner who already has it (transfer, edge cases, compression)
dual-coding	pair words with a visual; interleave sub-topics
metacognition	predict-then-compare, plan/monitor/evaluate, catch the illusion of competence
learner-model	silent per-turn read of grasp/misconception/load that steers every move
learning-science	the cross-cutting "why": mission, zone of proximal development, storage strength

Memory & traceability

learn-everything is built so your learning leaves a durable, inspectable trace — all plain markdown:

• CONTEXT.md (per track) — the rolling digest read on resume: Where you are / What you've learned / Known sticking points / Open threads.
• learning-records/ — dated, append-only insights (each corrected misconception, prior knowledge, mastery shown).
• glossary.md — terms you asked about (captured on ask, promoted when you can use them); also a map of what was hard.
• Question heatmap — every ad-hoc question is logged under a concept; questions ranks where you asked most (your weak/important spots), which feeds back into what to re-teach and card.
• progress — three retention numbers per track: total cards / graduated (locked into long-term memory) / 7-day accuracy.
• Source provenance — each card can carry a source (the note / url / page it was distilled from), so any fact traces back to where it came from.
• A close-the-loop check — session-check --strict verifies a session left a card-or-reason, a log row, a next_action, and a CONTEXT.md updated today; the tutor runs it and won't declare done until it passes, so memory actually persists (and the digest stays bounded — no context overload as a track runs for months).

Captured misconceptions feed forward: the next session re-checks your sticking points first and corrects the route — skim what you own, dwell on what you missed, re-teach a past slip from a fresh angle.

Data model

The source of truth is per-track folders under tracks/. registry.json at the repo root is only a rebuildable cache — it can always be regenerated from the TRACK.md files.

tracks/<id>/
  TRACK.md            # source of truth: YAML frontmatter (id, title, mode, pedagogy, status,
                      #   created, deadline, last_active, next_action) + "## Goal" + "## Log"
  MISSION.md          # the real-world "why" for this track (grounds every session)
  CONTEXT.md          # rolling memory digest (read first on resume)
  plan.md             # map-of-content: sessions + card wikilinks
  cards/card-0001.md  # frontmatter + "#flashcards/<track>" + question / "?" / answer
                      #   (Obsidian spaced-repetition compatible)
  notes/<date>-*.md   # the source you're reading + the tutor's lesson notes
  learning-records/   # dated decision-grade insights (corrected misconceptions, etc.)
  glossary.md         # terms you asked about (a map of what was hard)
  review-state.json   # FSRS sidecar: per-card stability/difficulty/due/reps/lapses/last_review/state
  review-log.jsonl    # append-only grading history
  questions-log.jsonl # append-only ad-hoc questions (the heatmap source)
  curriculum.json     # big-book teaching state (chunk list + taught/pending), when a book is loaded
  fsrs-weights.json   # optional: personalized FSRS weights fit from your review history

registry.json         # REBUILDABLE cache of all tracks (never the sole source)

The engine (scripts/) writes: TRACK.md frontmatter/Log, cards/, the *.json/*.jsonl sidecars, curriculum.json, and registry.json. The tutor (skill) writes the human-readable memory — MISSION.md, CONTEXT.md, plan.md, notes/, learning-records/, glossary.md — as plain markdown (no CLI). If registry.json or a review-state.json goes missing or corrupt, the engine rebuilds / degrades gracefully and warns to stderr — it never loses the source of truth and never crashes the run. Full-file writes are atomic (tmp + rename), safe under Google Drive / Dropbox sync.

Sidecar JSON shapes

• review-state.json — { "<card-id>": {stability, difficulty, due, reps, lapses, last_review, state} }
• review-log.jsonl — one line per grade: {date, card, grade, due, reps, lapses, state}
• questions-log.jsonl — one line per question: {date, concept, question, term?}
• curriculum.json — {title, source_file, structure_source, built, max_chars, total, position, chunks:[{chunk_id, title, heading_path, page_range, start, end, char_len, status, taught_on}]}

CLI reference (the tutor runs these for you — you rarely need them directly)

The engine is a stdlib-only scripts/ core. registry.py owns track/card state, structure.py keeps the long-document CLI and curriculum state machine, structure_split.py owns pure document splitting, and fsrs.py is the scheduler.

# orientation & planning
python3 scripts/registry.py status [--today YYYY-MM-DD]        # board, leads with cards due
python3 scripts/registry.py nudge                             # ONE plain line of what's due (daily-note/cron)
python3 scripts/registry.py plan-day [--minutes N] [--energy low|normal|high]
python3 scripts/registry.py progress [--track <id|all>]        # total / graduated / 7-day accuracy

# starting, tuning & gating a track
python3 scripts/registry.py create-track --id <id> --title <t> --mode domain --pedagogy <p> [--deadline YYYY-MM-DD] [--goal "..."]
python3 scripts/registry.py set-prefs --track <id> [--goal-weight N] [--minutes-per-new-block N]
python3 scripts/registry.py ingest-check --track <id>          # ready to learn into? (MISSION set?)
python3 scripts/registry.py session-check [--strict [--review]] --track <id>   # close gate (strict = card+log+next+CONTEXT today)

# cards & review
echo '[{"question":"...","answer":"...","tags":["L2"],"source":"..."}]' | python3 scripts/registry.py add-cards --track <id>
python3 scripts/registry.py due [--track <id|all>] [--today YYYY-MM-DD]
python3 scripts/registry.py leeches --track <id>              # cards that keep failing — re-teach, not re-quiz
python3 scripts/registry.py grade --track <id> --card <card-id> --grade <1-4> [--today YYYY-MM-DD]

# memory & signals
python3 scripts/registry.py log --track <id> --what "..." [--next "..."] [--no-cards-reason "..."]
python3 scripts/registry.py log-question --track <id> --concept "<C>" --question "<Q>" [--term "<T>"]
python3 scripts/registry.py questions [--track <id|all>]       # where you asked most, ranked
python3 scripts/registry.py rebuild                            # rebuild registry.json from TRACK.md

# long documents (big books): split → teach chunk-by-chunk, resumable
python3 scripts/structure.py split <file.md> [--max-chars N]
python3 scripts/structure.py curriculum-build --track <id> <source.md>
python3 scripts/structure.py next-chunk --track <id>          # next pending chunk + its text
python3 scripts/structure.py mark --track <id> --chunk <chunk-id>
python3 scripts/structure.py curriculum-status --track <id>   # taught / remaining / %

# scheduler (called by registry.py; usable standalone)
python3 scripts/fsrs.py schedule --state '<json|->' --grade <1-4> --now YYYY-MM-DD

(Utility/admin: add-card single-card, next-card-id — rarely needed directly.)

Grades: 1=Again 2=Hard 3=Good 4=Easy. When --today is omitted it defaults to the system date.

Privacy & confidentiality

Read this before learning anything sensitive.

• When you ingest a source, its text is sent to the host model (Claude). Don't ingest material you aren't authorized to send to a third-party model; confirm first for privileged/client/legal docs.
• Your learning lives under tracks/, which is gitignored — notes, cards, questions, and memory stay local and are never committed by accident. profile.md, registry.json, .obsidian/, and .claudian/ (which can hold your auth token) are gitignored too.
• Ingested source text is treated as data, not instructions — imperative phrasing inside a document or web page is content to analyze, never a command to obey.

A note on FSRS

The engine implements FSRS-6 spaced repetition in pure standard-library Python. It is behavior-verified (tests lock in grade ordering, due-date monotonicity, new-card seeding); exact numeric parity with the reference implementation is intentionally deferred — the goal is correct, predictable, well-tested scheduling, not bit-for-bit constant reproduction. Personalized weights are out of scope until there's real review history.

Project layout

skills/learn/SKILL.md     primary Claude Code skill adapter (+ FEEDBACK.md improvement log)
methods/*.md              the pedagogy toolkit (data, not code): 7 standalone + 3 layers + modes
scripts/registry.py       all track/card/registry/planner state I/O (stdlib)
scripts/structure.py      long-document CLI + curriculum state machine (stdlib)
scripts/structure_split.py pure long-document splitter, no file I/O
scripts/fsrs.py           FSRS-6 scheduler (stdlib)
scripts/file_io.py        shared atomic writes
scripts/markdown_meta.py  shared frontmatter/scalar helpers
scripts/jsonl.py          shared JSONL append/read helpers
scripts/security_check.py repository secret + privacy-ignore check
adapters/                 optional out-of-core ingestion/search/optimization adapters
adapters/safety.py        shared untrusted-data markers + injection scanning
mcp/server.py             optional MCP host adapter over the same core
tests/                    unit tests (full discovery in CI) — engine + adapters + long-doc curriculum
plans/                    design specs, feature designs, architecture/optimization plans
docs/                     audits + the architecture optimization plan
tracks/                   YOUR learning data (gitignored)

Roadmap

The former backlog is now built (alpha) as out-of-core adapters + new modes, so the stdlib core stays pip-free and CI stays green:

• exam & applied track modes — methods/exam.md (syllabus → study → quiz → mock toward a dated target) and methods/applied.md (learn-by-building; capture the traps).
• URL ingestion (adapters/url_ingest/) — send a link → cleaned source markdown → the normal teach loop. Web route works end-to-end; video (B站/YouTube/抖音) and 微信公众号 run vendored fetchers bundled under providers/ so a clone works out of the box (runtime deps install on demand); PDF hands off to the doc adapter.
• Long-document ingestion + curriculum — scripts/structure_split.py splits a whole book into a hierarchy behind the scripts/structure.py CLI, methods/reading-guide.md (导读) turns it into an approved syllabus, and the curriculum state machine (curriculum-build → next-chunk → mark → curriculum-status) teaches it one chunk per session, resumable across days; adapters/doc_ingest/ does OCR/extraction.
• Web search (adapters/web_search/) — optional, out-of-core: fill a gap or verify a claim mid-lesson; results come back as UNTRUSTED data to weigh and cite (lazy backend, no core dep).
• MCP server (mcp/server.py) — drive the same engine from any MCP-capable host.
• Personalized FSRS weights (adapters/fsrs_optimize/) — fit weights from your own review history; scripts/fsrs.py auto-loads a per-track fsrs-weights.json if present.

Alpha caveat: the dependency-bearing routes (live web fetch, OCR, the MCP handshake, the torch optimizer) are wired and degrade gracefully when their optional deps are absent, but haven't yet been exercised against live inputs at scale — validate before relying on them. The guiding principle still holds: don't let breadth outrun a sticky core loop. Full designs: plans/specs/2026-06-22-feature-designs.md.

Status & honesty

This is alpha. What's solid and tested: the deterministic engine, the full state machine, every CLI, and all file artifacts — covered by full unittest discovery, MCP smoke tests, the secret check, and prior manual from-zero acceptance. What only a real session can prove: the quality of the teaching dialogue itself (that depends on the host model). It hasn't yet been battle-tested across months and many subjects — that's the next milestone, not a build task.

Contributing

Issues and PRs welcome. Keep the invariants: the core stays pip-free stdlib; markdown files are the source of truth (registry.json is a rebuildable cache); cards stay Obsidian-spaced-repetition compatible; teaching comes before cards; nothing is persisted without the learner's approval. New pedagogy is just a new methods/*.md. Run python3 -m unittest discover -v, python3 -m unittest mcp.test_server -v, and python3 scripts/security_check.py --history before sending a change.

Credits

• methods/learning-science.md adapts pedagogy from the teach skill by Matt Pocock (MIT, © 2026 Matt Pocock) — reframed for learn-everything's track/card/FSRS model.
• FSRS scheduling follows open-spaced-repetition/py-fsrs (FSRS-6); cards are compatible with obsidian-spaced-repetition; the in-Obsidian experience runs on Claudian.
• Vendored fetchers under providers/: wechat-article-fetch (MIT, © 2025 杨卫薪律师 — LICENSE.txt retained verbatim) and video-notes (personal-study-use note retained). Used unmodified to turn a link into a learnable source.

License

MIT — see LICENSE.