Learning Assistant

A personal spaced-repetition learning assistant that runs as an MCP server. It schedules study sessions using the SM-2 algorithm, syncs scheduling state to your Obsidian vault's YAML frontmatter, and is aware of your SBB commute times to help you find optimal study slots.

How it works

flowchart TD
    User([You]) -->|"finished a lecture /<br/>reviewed a topic /<br/>what should I study?"| Claude[Claude Desktop]
    Claude <-->|MCP protocol| Server[Learning Assistant<br/>MCP Server]

    subgraph Tools[" "]
        direction LR
        Write["log_lecture<br/>review_topic"]
        Read["get_learning_queue<br/>get_streak"]
        Plan["optimize_study_slots<br/>get_sbb_connection"]
        Sync["resync_index"]
    end

    Server --- Tools

    Write -->|"atomic dual-write"| Vault[("Obsidian Vault<br/>YAML frontmatter<br/><i>source of truth</i>")]
    Write -->|"atomic dual-write"| DB[("SQLite<br/>.learning_index.db<br/><i>query cache + streak</i>")]

    Read --> DB
    Sync -->|"rebuild from notes"| Vault
    Sync --> DB

    Plan -->|"travel times"| SBB[["SBB OpenData API"]]
    Read -.->|"due topics"| Plan

    SM2{{"SM-2 scheduling<br/>interval · ease · next_review"}}
    Write --- SM2

    style Vault fill:#7c3aed,color:#fff
    style DB fill:#0ea5e9,color:#fff
    style Claude fill:#d97706,color:#fff
    style SBB fill:#dc2626,color:#fff
    style SM2 fill:#059669,color:#fff

• Obsidian vault is the source of truth — each topic is an Obsidian note; scheduling metadata lives in the YAML frontmatter.
• SQLite acts as a fast query cache and stores streak/cognitive-load state that has no per-note equivalent.
• Every write operation (log_lecture, review_topic) updates both the note frontmatter and the SQLite row atomically.

Quick start

1. Clone and install

   git clone https://github.com/wysernils04/learning-assistant-mcp.git
   cd learning-assistant-mcp
   python -m venv .venv
   source .venv/bin/activate        # Windows: .venv\Scripts\activate
   pip install -r requirements.txt
   

2. Add the server to Claude Desktop

   Open claude_desktop_config.json in a text editor:

   • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   Add the following block (replace the paths with your own):

   {
     "mcpServers": {
       "learning-assistant": {
         "command": "/absolute/path/to/learning-assistant-mcp/.venv/bin/python",
         "args": ["/absolute/path/to/learning-assistant-mcp/learning_assistant_v3.py"],
         "env": {
           "OBSIDIAN_VAULT_PATH": "/absolute/path/to/your/obsidian/vault"
         }
       }
     }
   }
   

   The env block is all you need — no .env file required for Claude Desktop.

3. Restart Claude Desktop — the config is only read on startup.

4. Verify — open a new conversation and ask:

   "What learning tools do you have access to?"

   Claude should list all 7 tools (log_lecture, review_topic, get_learning_queue, optimize_study_slots, get_sbb_connection, get_streak, resync_index). If it doesn't, double-check the file paths in the config and restart again.

---

Tools

Tool	Description
log_lecture	Record a newly studied topic with an initial understanding score (0–5). Creates the Obsidian note if it doesn't exist.
review_topic	Log a review session and update the SM-2 interval, ease factor, and next-due date.
get_learning_queue	Return topics due for review today, sorted by priority.
optimize_study_slots	Given a list of calendar events and current energy level, suggest the best study windows — factoring in SBB travel times.
get_sbb_connection	Look up the next SBB connection between two stations.
get_streak	Return the current study streak and daily load summary.
resync_index	Rebuild the SQLite index from all notes in the vault. Use this if you edited notes manually in Obsidian or migrated existing notes.

Configuration reference

Variable	Required	Default	Description
OBSIDIAN_VAULT_PATH	Yes	—	Absolute path to your Obsidian vault root
OBSIDIAN_LERNEN_DIR	No	📚 Lernen	Subfolder inside the vault for learning notes
LEARNING_DB_PATH	No	<vault>/.learning_index.db	Path for the SQLite cache
SBB_API_BASE	No	https://transport.opendata.ch/v1	SBB transport API base URL
SBB_TRAVEL_FALLBACK_MIN	No	30	Fallback travel time in minutes if the API is unreachable

Set these in the env block of claude_desktop_config.json (as shown in the quick start), or in a .env file next to the script if you want to run it directly from the command line.

Vault structure

The server creates and manages notes automatically — no manual folder setup required. The layout is:

<vault>/
└── 📚 Lernen/          ← OBSIDIAN_LERNEN_DIR
    └── <Module>/       ← one folder per module (e.g. "Algebra")
        └── <topic>.md  ← one note per topic (slugified filename)

Each note gets the following YAML frontmatter written and kept up to date:

---
type: lernthema
module: Algebra
topic: Lineare Funktionen
understanding_score: 4
ease_factor: 2.5
interval: 4
repetitions: 1
next_review: "2026-06-17"
last_reviewed: "2026-06-13"
---

If you have existing notes you want to import, add type: lernthema to their frontmatter and run resync_index — the server will pick them up and fill in any missing fields with sensible defaults.

Usage with Claude Desktop

Scope it to a project

Rather than enabling this server globally, add it to a specific Claude Desktop project (e.g. "Studies"). That way the tools are only active when you're in that context and won't clutter other conversations.

System prompt

Add this to your project's system prompt so Claude uses the tools naturally without being asked:

You have access to a personal learning assistant (MCP server).
- When I tell you I finished a lecture or studied a topic, call log_lecture.
- When I say I reviewed or practiced something, call review_topic.
- When I ask what to study, call get_learning_queue.
- When I share my schedule for the day, call optimize_study_slots. Pass events as
  ["HH:MM-HH:MM description", ...] and ask for my energy level if I haven't mentioned it.
Always confirm the module and topic name before logging.

Memory keys

Tell Claude the following once (or put them in the system prompt) so it can fill in tool parameters without asking every time:

Key	Example	Used by
Your modules	"My modules are: Algebra, Analysis, Physics"	log_lecture, review_topic
Home station	"My home station is Zurich HB"	optimize_study_slots, get_sbb_connection
School/work station	"My school station is Bern"	optimize_study_slots, get_sbb_connection
Chronotype	"I'm a morning person" / "I have high energy in the afternoon"	optimize_study_slots
Vault subfolder	"My learning folder is called 📚 Lernen"	all vault tools (if you changed the default)

SM-2 Scheduling

Understanding scores and quality scores both use a 0–5 scale:

• 0–2 — Poor recall; interval resets, ease factor decreases.
• 3 — Marginal; interval stays short.
• 4–5 — Good/perfect recall; interval and ease factor increase.

Initial intervals by understanding score: {0: 1d, 1: 1d, 2: 2d, 3: 2d, 4: 4d, 5: 6d}.