Skip to content

README_EN.md

Latest commit

 

History

History
196 lines (146 loc) · 10 KB

README_EN.md

File metadata and controls

196 lines (146 loc) · 10 KB
Raw

study-loop is a study helper for your university courses and exams, used inside Claude Code.

Tell it which course you're taking and when the exam is, and it'll plan what to study each day, generate practice questions, walk you through the ones you get wrong, schedule reviews on a forgetting curve, and even produce a mock exam paper before the test — from the first week of class through finals.

What sets it apart from other study and flashcard apps, in one line: it won't let you "pretend you've learned it." Other apps mark a topic "mastered" the moment you answer it once, or count a card as learned after a single pass; study-loop only calls it "really known" when you can solve it on your own and still solve it when the question is rephrased. For every mistake it asks "why did you actually get this wrong?", remembers the answer, then re-tests you with a different wording until it's sure you're not just guessing — and even the AI-generated questions have to solve themselves and survive a critic before they're allowed near you.

All your study data lives on your own computer. It doesn't depend on any cloud service, and it won't vanish if some platform shuts down.

Understanding ≠ mastery. It builds the bridge between "I get it" and "I can do it."

Quick start

Install

Python 3.11+ is required. Use python3 on macOS/Linux; on Windows, replace it with python.

git clone https://github.com/monkeydyt/study-loop.git
cd study-loop
python3 -m pip install -r requirements.txt
python3 -m pytest

For Claude Code, place the repository in the Skill directory:

ln -s "$(pwd)" ~/.claude/skills/study-loop

Start a course

python3 scripts/init_course.py ~/courses/analog-electronics \
  --course-id analog-electronics \
  --name "Analog Electronics" \
  --exam-date 2026-07-25

Then enter the course directory and say /study in Claude Code, or ask:

Help me study analog electronics. What is the most valuable next step?

Run the end-to-end demo

bash demo/demo.sh

The demo creates a temporary course and walks through knowledge registration, a high-confidence mistake, misconception attribution, repair, transfer validation, FSRS, and next-best-step. It does not modify a real course.

What it solves

Question How study-loop responds
What should I study today? Recommends a next-best-step from state, exam date, risks, and due cards.
Why did I get it wrong? Records wrong assumptions, missing premises, 14 error types, and triggers.
Do I really know it? Separates unseen, explained, practiced, checked, confirmed, weak, and blocked states (7 states).
Will I fail on a new variant? Uses T0–T4 transfer levels plus an original-question retest.
When will I forget it? Schedules review cards with FSRS.

Core capabilities

  • Event sourcing: learning activity is appended to events.jsonl; state is derived and rebuildable.
  • Seven teaching states: unseen/explained/practiced/checked/confirmed/weak/blocked—from never-seen to transfer-confirmed, plus regression and prerequisite-block as exception states, modeled separately.
  • Misconception memory: mistakes are remembered by KC × 14 error types × trigger, then repaired through original and transfer retests.
  • Four AI question gates: Generator → blind Solver → adversarial Reviewer → mechanical validation.
  • One-command drills: drill.py supports syllabus-first and diagnostic-first selection, with HTML, PDF, or Markdown output.
  • Local-first data: course state stays in the local workspace; events.jsonl is the source of truth.

Example requests

Goal Example
Start studying Continue studying and tell me today's most valuable next step.
Drill by syllabus Give me 10 syllabus questions as an interactive HTML quiz.
Diagnose weaknesses Diagnose my weak knowledge points, then give me 5 questions.
Repair a mistake Help me analyze this mistake and schedule an original retest plus a transfer test.
Inspect progress Show my mastery evidence, misconceptions, and due review cards.

If you are unsure where to start, say “Help me study”; the agent checks your state first, then route the intent before executing.

How it works

User request
   ↓
SKILL.md routes the intent
   ↓
Python CLI appends an event
   ↓
events.jsonl (source of truth)
   ↓
Derived state / FSRS / misconception memory / next-best-step
   ↓
Dashboard / HTML quiz / PDF paper / conversational guidance

The agent handles intent and explanations. Scripts handle deterministic calculations, state transitions, event writes, and question validation. State must be written through the CLI under scripts/; do not edit course .study/ files directly.

Multiple output formats

python3 scripts/drill.py --mode syllabus --count 10 --format html
python3 scripts/drill.py --mode diagnostic --count 5 --format paper

HTML quizzes include a runtime explanation toggle. PDF output includes a Chinese-font fallback and can generate both question and answer-analysis papers.

Repository map

study-loop/
├── README.md                  # Chinese project homepage
├── README_EN.md               # English project overview
├── SKILL.md                   # Main agent routing and invariants
├── agents/                    # Generator / Solver / Reviewer cards
├── references/                # Architecture and learning rules
├── scripts/                   # CLI entry points and core library
├── templates/                 # Dashboard and HTML quiz templates
├── demo/                      # End-to-end demo
├── tests/                     # pytest suite
├── docs/                      # User guide and delivery report
├── assets/                    # README visual assets
└── .github/                   # CI, issue, and pull-request templates

Delivered and roadmap

Delivered

  • V1: event sourcing, seven teaching states, evidence graph, misconception memory, transfer validation, FSRS, and /study routing.
  • V2: bilingual KC labels, one-command drills, interactive HTML quizzes, PDF papers, and multiple output formats.
  • V3: a redesigned README with a banner and navigation, bilingual project documentation, guided Agent onboarding, and contribution, security, issue, pull-request, and CI collaboration entry points.
  • V4: tightened data model (D7 no-hint promotion, D8 demotion only on conceptual errors; KC ledger gains aliases/related/weight) + a quality/trust layer (question provenance grounding/exam_ref with ingest validation; dirty-data rollback via event.py flag-question --question-id ... --reason ... → evidence invalidation, question withdrawal, state recompute, tracked in state.json.flagged_question_count) + three-tier scheduling (next_step.py now emits today's list + priority top-3 + exam-risk warnings; course.yaml daily_minutes sets the daily budget) + misconception interaction (student confirmation --confirmed-by + per-label ask-before-repair) + personalization (drill strategy/difficulty hints, references/teaching-style.md, learning_rhythm) + syllabus skeleton syllabus.json (init_course --syllabus, syllabus.py migrate, KC syllabus_node, alias-match prompt). Breaking: new candidate questions must carry grounding.material.

Roadmap

  • Scene completion: /preview, /exam (tiered knowledge list + full-set mock papers), and a full /review loop beyond FSRS.
  • Resumable learning: treat "unfinished" as a first-class state; reopen where you left off (open_tasks.json).
  • Unified front-end return path: import HTML/PDF attempts as attempt events; fill in the evidence contract fields.
  • Dual question paths: real-exam variants (reuse a real question, tweak numbers/context).
  • Content parsing: paragraph-level grounding, slide/textbook parsing; alias auto-merge; Obsidian export.
  • Post-exam feedback and cross-course learning fingerprints.

Non-goals: multi-user collaboration, cloud sync, and a full GUI.

See docs/DELIVERY-REPORT.md for current limitations.

Tests

python3 -m pytest
git diff --check

GitHub Actions runs the test suite on pushes and pull requests. See CONTRIBUTING.md for development rules.

Documentation

Contributing

Documentation improvements, bug fixes, and verifiable new capabilities are welcome. Read CONTRIBUTING.md before starting. For security issues, read SECURITY.md and do not disclose sensitive information in a public issue.

License

MIT. See LICENSE.