spacedrep

# spacedrep [](https://pypi.org/project/spacedrep/) [](https://pypi.org/project/spacedrep/) [](LICENSE) Spaced repetition you can script. A CLI and [MCP server](https://modelcontextprotocol.io/) for flashcards — so an AI agent can generate cards from what you're learning, quiz you in conversation, and manage your deck alongside you. Import your existing Anki decks to get started. Scheduling uses [FSRS](https://github.com/open-spaced-repetition/py-fsrs) (same algorithm as Anki 23.10+). Everything is JSON in, JSON out — pipe it, script it, or let an agent drive it. [Why build a CLI this way.](https://dev.to/uenyioha/writing-cli-tools-that-ai-agents-actually-want-to-use-39no) > **You:** Quiz me on my AWS deck. > > **Agent:** What does S3 stand for, and what is it used for? > > **You:** Simple Storage Service, it's object storage. > > **Agent:** Correct. Rated **good** — next review in 4 days. What is the CAP theorem? > > **You:** Something about distributed systems... I forget. > > **Agent:** CAP: pick 2 of 3 — consistency, availability, partition tolerance. Rated **again** — it'll come back shortly. 12 cards left. ## Install ```bash pip install spacedrep ``` Optional extras: `spacedrep[mcp]` for the MCP server, `spacedrep[optimizer]` for FSRS parameter optimization (requires torch). ## Features - **FSRS scheduling** — same algorithm as Anki 23.10+, with parameter optimization from your review history - **Cloze deletions** — `{{c1::answer}}` syntax, auto-expands into multiple cards - **Reversed cards** — one note becomes two cards (Q→A and A→Q); edits are template-aware and re-adds dedupe on (question, deck). Basic ↔ reversed collisions are caught with a clear error — delete the existing card first to convert it - **Anki-native storage** — single SQLite file using Anki's schema for full round-trip compatibility - **Rich filtering** — by deck, tags, state, date ranges, FSRS properties, and more - **Agent-friendly** — duplicate detection, leech detection, review preview, bury/unbury, review history ## MCP Server Add to Claude Desktop (`claude_desktop_config.json`): ```json { "mcpServers": { "spacedrep": { "command": "uvx", "args": ["--from", "spacedrep[mcp]", "spacedrep-mcp"], "env": { "SPACEDREP_DB": "/path/to/collection.anki21" } } } } ``` ### Agent loop `get_next_card` → grade → `submit_review`. The server bundles a few affordances for that loop: - **Loop instructions on connect** — the agent gets the loop, the rating scale, and the rule that it picks the rating (not the user) - **Inline review history** — `get_next_card` and `get_card` include the last 3 reviews with their `user_answer` and `feedback` text - **Session pacing** — `get_next_card` returns `due_remaining` for "N cards left" messaging - **Sibling auto-bury** — `submit_review` buries cloze/reversed siblings for 24h and returns them as `siblings_buried`, so the next card isn't a sibling whose answer was just shown ## CLI Quick Start ```bash spacedrep db init # create the database spacedrep deck import ~/Downloads/deck.apkg # or import an existing Anki deck spacedrep card add "What is CAP theorem?" "Pick 2 of 3: consistency, availability, partition tolerance" --deck AWS spacedrep card add-cloze "{{c1::Ottawa}} is the capital of {{c2::Canada}}" --deck Geo spacedrep card add-reversed "Capital of France" "Paris" --deck Geo # creates 2 cards: Q→A and A→Q spacedrep card next # get the next due card spacedrep review submit <card_id> good # again | hard | good | easy ``` See `spacedrep --help` and `spacedrep <command> --help` for all options. ## Cloze Deletions Each `{{c1::answer}}` becomes a separate card. Hints are supported: `{{c1::Ottawa::capital city}}` shows `[capital city]` as the blank. ```bash spacedrep card update-cloze 42 "{{c1::Ottawa}} is in {{c2::Canada}}, {{c3::North America}}" ``` ## Search and Filters ```bash spacedrep card list --search "Lambda" --deck AWS --state review spacedrep card list --due-before "2026-12-31" --leeches spacedrep card bury 42 --hours 4 spacedrep deck export out.apkg ``` Filters work on `card list` and `card next`. See `--help` for the full list. ## Anki Compatibility spacedrep operates directly on Anki's native SQLite schema. Importing an `.apkg` replaces the working database; exporting writes it back. FSRS scheduling state survives the round-trip — cards reviewed in spacedrep show correct due dates when opened in Anki. Media files, JavaScript templates, and nested cloze deletions are not supported. ## Data Storage Your database is a single SQLite file (`collection.anki21` by default). Every card addition and review is committed immediately — if the agent disconnects or the process crashes, no work is lost. You don't need to export after every session. The `.apkg` import/export tools are for moving data between spacedrep and Anki Desktop, not for saving your progress.