spacedrep 0.5.0

Spaced repetition for AI agents — CLI and MCP server for Anki flashcards

spacedrep

Spaced repetition you can script. A CLI and MCP server 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 (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.

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

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):

{
  "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

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.

spacedrep card update-cloze 42 "{{c1::Ottawa}} is in {{c2::Canada}}, {{c3::North America}}"

Search and Filters

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.