# Smart Study Agent

> The AI study agent that learns how you learn — RL picks the action, FSRS picks the timing, the LLM only writes the quizzes. Chrome extension · Anki export · MCP server · runs on Ollama

- **Type:** MCP server
- **Install:** `agentstack add mcp-humphreysun98-smart-study-agent`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [HumphreySun98](https://agentstack.voostack.com/s/humphreysun98)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [HumphreySun98](https://github.com/HumphreySun98)
- **Source:** https://github.com/HumphreySun98/Smart-Study-Agent
- **Website:** https://huggingface.co/spaces/HumphreySun98/smart-study-agent

## Install

```sh
agentstack add mcp-humphreysun98-smart-study-agent
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# SmartStudy Agent

> The AI study agent that **learns how you learn** — a reinforcement-learning policy decides *what* you study next, an FSRS memory model decides *when* you review it, and an LLM generates the quizzes in between. In your browser, in your terminal, or inside Claude via MCP.

[](https://www.python.org/downloads/)
[](https://www.anthropic.com/)
[](https://streamlit.io/)
[-4A90E2.svg)](chrome-extension/)
[](https://github.com/open-spaced-repetition/py-fsrs)
[](anki_export.py)
[](mcp_server.py)
[](LICENSE)
[](https://huggingface.co/spaces/HumphreySun98/smart-study-agent)

**[English](#-live--two-ways-to-use-it)** · **[中文简介](#-中文简介)** · **[📚 Technical Deep Dive](docs/DEEP_DIVE.md)** — the POMDP framing, the math behind both policies, and the experiments (including the ones the heuristic won)

## 🌐 Live — Two Ways to Use It

| | Where it runs | How to try it |
|---|---|---|
| **Web app** | Hugging Face Spaces (free Kimi-K2 backend) | [Open in browser](https://huggingface.co/spaces/HumphreySun98/smart-study-agent) |
| **Chrome extension** | Your browser — works on any page, PDF, or YouTube video | [**Install from the Chrome Web Store**](https://chromewebstore.google.com/detail/edbjkpfjonahanfkamlcbobmnplihmik) · [Source](chrome-extension/) (MV3) |

  
    
  
  
  Live on the Chrome Web Store — click to install.

  
  
  Side panel running on a YouTube ML course — topics auto-extracted from captions, belief state updating in real time.

The web app runs on Hugging Face Spaces using free HF Inference Providers (Kimi-K2). The Chrome extension calls the Anthropic API directly from your browser — same agent core, zero backend. For local development, plug in your own Anthropic key to get Claude's higher-quality reasoning.

SmartStudy Agent is a goal-based, partially observable AI agent that turns any lecture material into a fully personalized learning experience. Unlike a chatbot, it maintains a persistent belief state about student knowledge and uses an adaptive policy to decide what to study next.

---

## Why SmartStudy?

Traditional study tools are static. They show you the same content regardless of what you already know. SmartStudy Agent solves this by closing the loop:

| Problem | SmartStudy's Solution |
|---------|----------------------|
| Generic study materials | Topics extracted and prioritized per student |
| No feedback on weak areas | Quiz answers update a persistent belief state |
| Same recommendations for everyone | Q-learning policy (or Contextual Bandit) adapts per student trajectory |
| Forgetting without practice | **FSRS** spaced repetition — the same modern memory model family as Anki (SM-2 fallback) |
| Out-of-order topics | Topological sort over a concept dependency graph |
| Locked into one app | **Anki .apkg export**, **MCP server** for Claude, Chrome extension, web app |

### How it compares

| | SmartStudy | DeepTutor | OpenTutor | Anki |
|---|---|---|---|---|
| Runs where you read (browser extension) | ✅ Chrome Web Store | ❌ web workspace | ❌ self-hosted app | ❌ |
| RL policy decides next action | ✅ Q-learning + LinUCB, honest benchmark | ❌ | ❌ | ❌ |
| Spaced repetition | ✅ FSRS | ❌ | ✅ FSRS | ✅ FSRS |
| Quiz generation from any material | ✅ | ✅ | ✅ | ❌ |
| Anki export | ✅ .apkg | ❌ | ❌ | — |
| Drive it from Claude (MCP) | ✅ | ❌ | ❌ | via 3rd-party |
| Footprint | ~3k LOC, SQLite, runs on free tier | Full platform (FastAPI + Next.js) | FastAPI + Next.js | Desktop app |

SmartStudy is deliberately **not** an all-in-one learning platform — it's the lightweight agent core: observe → plan → quiz → evaluate → adapt, with real learning-science scheduling. If you want a full workspace, [DeepTutor](https://github.com/HKUDS/DeepTutor) is excellent. If you want the decision loop embedded where you already study — this repo.

---

## Architecture

SmartStudy implements the **OPEAA loop** — a five-phase adaptive agent cycle:

```
       ┌─────────────────────────────────────────────────┐
       │              Lecture Materials                  │
       │   PDF · TXT · MD · DOCX · PPTX · VTT · SRT      │
       └────────────────────┬────────────────────────────┘
                            ▼
       ┌─────────────────────────────────────────────────┐
       │     Claude API  ·  claude-opus-4-6              │
       │     thinking: { type: "adaptive" }              │
       └────────────────────┬────────────────────────────┘
                            ▼
       ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐
       │ OBSERVE │─▶│  PLAN   │─▶│   ACT   │─▶│ EVALUATE│
       │         │  │  + DAG  │  │  quizzes│  │  + LLM  │
       │ extract │  │   sort  │  │  3 MCQs │  │feedback │
       │ topics  │  │         │  │         │  │         │
       └─────────┘  └─────────┘  └─────────┘  └────┬────┘
            ▲                                       │
            │           ┌──────────────────────────▼┐
            │           │           ADAPT           │
            └───────────┤  Heuristic OR Q-learning  │
                        │  StudentProfile updated   │
                        └─────────┬─────────────────┘
                                  ▼
                  ┌─────────────────────────────────┐
                  │   Persistent Belief State       │
                  │   (JSON storage · per student)  │
                  └─────────────────────────────────┘
                                  │
                ┌─────────────────┼─────────────────┐
                ▼                 ▼                 ▼
          Spaced Repetition  Concept Graph    Interfaces
            (FSRS)           (DAG topo sort)  Streamlit · Chrome ext
                                              MCP server · Agent Skill
```

The agent is modeled as a **POMDP** (partially observable Markov decision process):
- **State** — student's true knowledge (hidden)
- **Belief state** — `StudentProfile` (mastered topics, weak areas, quiz history)
- **Actions** — `advance` · `reinforce` · `review`
- **Observations** — student answers to generated quizzes
- **Reward** — improvement in quiz scores over time

---

## Features

### Core Agent
- **5-phase OPEAA loop** — Observe → Plan → Act → Evaluate → Adapt
- **Claude integration** with `thinking: {type: "adaptive"}` for internal reasoning
- **Goal-based agent design** following Russell & Norvig's PEAS framework
- **POMDP belief state** persisted across sessions
- **Two adaptive policies** — heuristic (Bloom's 70% mastery threshold) and tabular Q-learning

### Knowledge & Memory
- **Concept dependency graph** — Kahn's algorithm topological sort over a topic prerequisite DAG, rendered as an **interactive draggable graph** (pyvis)
- **FSRS spaced repetition** — per-topic memory model (stability · difficulty · recall probability) via [py-fsrs](https://github.com/open-spaced-repetition/py-fsrs); automatic SM-2 fallback
- **Anki export** — one click turns your generated quiz bank into a styled `.apkg` deck
- **Persistent SQLite storage** — student profiles survive across sessions
- **Multi-student support** with peer comparison dashboard

### Integrations
- **MCP server** — Claude Desktop / Claude Code can query your review queue, generate quizzes, record results (training the RL policy), and export decks
- **Claude Agent Skill** — `skills/smartstudy/` turns any Claude Code session into an adaptive study coach
- **Multi-provider LLM** — Claude, HF Inference, or **any OpenAI-compatible endpoint** (Ollama, LM Studio, vLLM, DeepSeek) — fully local studying is supported

### Input & Evaluation
- **7 input formats** — PDF, TXT, MD, DOCX, PPTX, VTT, SRT
- **Quantitative evaluation** — Monte Carlo simulation of adaptive vs random baselines
- **Mock client** — `MockAnthropic` lets you run the entire system offline without an API key

### User Interface
- **Streamlit web app** with 8 pages (premium glassmorphism theme)
- **Chrome extension (MV3)** — run the full OPEAA loop on any web page, Q-table persisted in `chrome.storage.local`
- **Interactive terminal UI** powered by `rich`
- **Auto-demo mode** for video recording

---

## Installation

```bash
git clone https://github.com/HumphreySun98/Smart-Study-Agent.git
cd Smart-Study-Agent
pip install -r requirements.txt
```

The agent supports four LLM backends and picks one automatically:

| Backend | Env variable | Cost | Quality |
|---------|--------------|------|---------|
| **Anthropic Claude** | `ANTHROPIC_API_KEY` | Pay as you go | ⭐⭐⭐⭐⭐ Best — supports adaptive thinking |
| **Any OpenAI-compatible endpoint** (Ollama, LM Studio, vLLM, DeepSeek…) | `SMARTSTUDY_LLM_BASE_URL` + `SMARTSTUDY_LLM_MODEL` | Free if local | ⭐⭐⭐–⭐⭐⭐⭐ your choice |
| **HF Inference (Kimi-K2)** | `HF_TOKEN` | **Free** | ⭐⭐⭐⭐ Great |
| **Mock** | _(no env vars)_ | Free | ⭐⭐ Canned responses for offline demos |

```bash
# Option 1 — Claude (premium quality)
export ANTHROPIC_API_KEY=sk-ant-...

# Option 2 — fully local & private with Ollama
export SMARTSTUDY_LLM_BASE_URL=ollama        # shortcut for http://localhost:11434/v1
export SMARTSTUDY_LLM_MODEL=llama3.1

# ...or any other OpenAI-compatible server
export SMARTSTUDY_LLM_BASE_URL=https://api.deepseek.com/v1
export SMARTSTUDY_LLM_MODEL=deepseek-chat
export SMARTSTUDY_LLM_API_KEY=sk-...

# Option 3 — Hugging Face (completely free)
export HF_TOKEN=hf_...

# Option 4 — Mock mode (no setup)
# just run the agent without any keys
```

Get a Claude key from [console.anthropic.com](https://console.anthropic.com) ($5 free credit) or a free HF token from [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens).

---

## Quick Start

### Hosted Demo (zero install)
👉 **[https://huggingface.co/spaces/HumphreySun98/smart-study-agent](https://huggingface.co/spaces/HumphreySun98/smart-study-agent)**

### Web App (local)
```bash
streamlit run app.py
```
Open **http://localhost:8501**, create a student in the sidebar, then go to **📖 Study Session** to run the full OPEAA loop on a sample ML lecture or your own PDF.

### Terminal demo (interactive)
```bash
python demo.py
python demo.py --pdf path/to/lecture.pdf
python demo.py --mock                  # offline mode, no API key needed
```

### Auto demo (for screen recording)
```bash
python demo_auto.py
```

### Chrome extension (run the agent on any web page, PDF, or YouTube video)

**Now live on the Chrome Web Store** — [install in one click](https://chromewebstore.google.com/detail/edbjkpfjonahanfkamlcbobmnplihmik).

Prefer to run the source directly? Load it unpacked in  ['Linear Algebra', 'Neural Networks', 'Backpropagation']

# Spaced repetition scheduler (SM-2)
due_today = get_review_queue(record["quiz_history"])

# Q-learning adaptive policy
policy = QLearningPolicy()
action = policy.choose_action(score=0.55)         # 'reinforce'
policy.update(prev_score=0.55, action=action, new_score=0.80)

# Quantitative evaluation vs random baseline
results = compare(n_runs=30, n_sessions=20)
print(f"Adaptive beats baseline by {results['improvement_pct']:.1f}%")
```

---

## Web App Pages

| Page | Purpose |
|------|---------|
| 🏠 **Dashboard** | Mastered topics, weak areas, due reviews, and key metrics |
| 📖 **Study Session** | Upload a lecture and run the full OPEAA loop step-by-step |
| 🔁 **Spaced Review** | FSRS memory state per topic — recall %, stability, next due date |
| 🃏 **Anki Export** | Build a styled `.apkg` deck from your generated question bank |
| 🧠 **Concept Graph** | Interactive draggable prerequisite DAG — mastered/weak topics color-coded |
| 📊 **Progress History** | Personal score trajectory across all attempts |
| 👥 **Peer Comparison** | Multi-student leaderboard ranked by average score |
| 🎯 **RL Policy** | Inspect the Q-table and train it on simulated episodes |
| 🧪 **Baseline Evaluation** | Adaptive vs random topic-selection simulation results |
| 📋 **Pilot Study** | Real usage metrics, engagement analysis, learning progression report |

---

## Project Structure

```
smartstudy-agent/
├── smartstudy_agent.py     # Core agent — 5 OPEAA phases
├── mock_claude.py          # Offline mock client
├── hf_client.py            # Hugging Face Inference adapter (free LLM backend)
├── app.py                  # Streamlit web app (8 pages)
├── demo.py                 # Interactive terminal demo
├── demo_auto.py            # Automated demo (no input needed)
│
├── storage.py              # SQLite persistent storage (+ question bank)
├── concept_graph.py        # Topic prerequisite DAG with cross-course linking
├── pilot_study.py          # Pilot study data collection and analysis
├── rl_policy.py            # Tabular Q-learning policy
├── bandit_policy.py        # Contextual Bandit (LinUCB) — alternative to RL
├── spaced_repetition.py    # FSRS review scheduler (SM-2 fallback)
├── anki_export.py          # Question bank → Anki .apkg deck (genanki)
├── mcp_server.py           # MCP server — drive the agent from Claude
├── skills/smartstudy/      # Claude Agent Skill — study coach for Claude Code
├── multi_format.py         # PDF/TXT/MD/DOCX/PPTX/VTT/SRT loader
├── evaluation.py           # Adaptive vs baseline simulation
├── experiments/            # Reproducible studies (scheduler comparison, ...)
├── docs/DEEP_DIVE.md       # POMDP framing, policy math, experiment analysis
│
├── generate_visuals.py     # Generates architecture diagrams
├── requirements.txt        # Python dependencies
├── README.md               # This file
│
├── chrome-extension/       # Chrome MV3 extension — OPEAA loop in the browser
│   ├── manifest.json
│   ├── popup.{html,css,js} # Gradient popup UI + full agent logic
│   ├── content.js          # Active-tab text extractor
│   ├── options.{html,js}   # API key + model settings
│   ├── background.js       # Service worker
│   └── icons/              # 16/48/128 PNG
│
├── data/                   # Created at runtime
│   ├── smartstudy.db       # SQLite database (student profiles + sessions)
│   ├── qtable.json         # Q-learning policy state
│   └── concept_graph.json  # User-defined graph edges
│
└── visuals/                # Generated PNG diagrams
    ├── adaptive_loop.png
    ├── system_architecture.png
    ├── performance_dashboard.png
    └── ai_techniques.png
```

---

## Tech Stack

| Layer | Technology |
|-------|-----------|
| LLM | Claude (adaptive thinking) · any OpenAI-compatible endpoint · HF Inference |
| Web UI | Streamlit |
| RL | Tabular Q-learning over discretized score buckets + LinUCB bandit |
| Knowledge Graph | NetworkX + Kahn's algorithm + pyvis (interactive) |
| Spaced Repetition | FSRS via [py-fsrs](https://github.com/open-spaced-repetition/py-fsrs) (SM-2 fallback) |
| Flashcards | genanki → Anki `.apkg` |
| Agent Interop | MCP server (FastMCP) + Claude Agent Skill |
| Storage | SQLite (auto-migrates from JSON, scales to >1k students) |
| Document Parsing | pypdf, python-docx, python-pptx |
| Terminal UI | rich |

---

## How the Agent Decides

The ADAPT phase uses a **two-layer decision system**: the RL policy chooses the action, and the LLM explains the decision to the student in natural language.

### Q-Learning Policy (decides the action)

The action (`advance` / `reinforce` / `review`) is chosen by a tabular Q-learning agent — **not** by the LLM. This runs every time a student finishes a quiz.

| Component | Value |
|-----------|-------|
| **State** | Quiz score discretized into 5 buckets: `very_low` / `low` / `medium` / `high` / `very_high` |
| **Actions** | `review` · `reinforce` · `advance` |
| **Reward** | Score change between attempts: `r = (new_score − prev_score) × 10` |
| **Learning rate (α)** | 0.2 |
| **Discount factor (γ)** | 0.8 |
| **Exploration (ε)** | 0.15 (epsilon-greedy) |

Update rule:
```
Q(s, a) ← Q(s, a) + α · [r + γ · max(Q(s', a')) − Q(s, a)]
```

The Q-table is **persisted to disk** (`data/qtable.json`) and trains on every real quiz attempt. It can also be inspected and manually trained in the **🎯 RL Policy** page.

### LLM Layer (explains the decision)

After

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [HumphreySun98](https://github.com/HumphreySun98)
- **Source:** [HumphreySun98/Smart-Study-Agent](https://github.com/HumphreySun98/Smart-Study-Agent)
- **License:** MIT
- **Homepage:** https://huggingface.co/spaces/HumphreySun98/smart-study-agent

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-humphreysun98-smart-study-agent
- Seller: https://agentstack.voostack.com/s/humphreysun98
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.