Metadata-Version: 2.4
Name: spacedrep
Version: 0.5.0
Summary: Spaced repetition for AI agents — CLI and MCP server for Anki flashcards
Project-URL: Homepage, https://github.com/wpwilson10/spacedrep
Project-URL: Repository, https://github.com/wpwilson10/spacedrep
Project-URL: Issues, https://github.com/wpwilson10/spacedrep/issues
Author-email: wpwilson10 <wpwilson10@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: anki,cli,flashcards,fsrs,mcp,spaced-repetition
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Education
Requires-Python: >=3.12
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: fsrs<7,>=6.3
Requires-Dist: pydantic>=2.0
Requires-Dist: typer>=0.15
Provides-Extra: dev
Requires-Dist: mcp>=1.0; extra == 'dev'
Requires-Dist: pre-commit>=4.0; extra == 'dev'
Requires-Dist: pyright>=1.1; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.11; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Provides-Extra: optimizer
Requires-Dist: fsrs[optimizer]; extra == 'optimizer'
Description-Content-Type: text/markdown

# spacedrep

[![PyPI version](https://badge.fury.io/py/spacedrep.svg)](https://pypi.org/project/spacedrep/)
[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)](https://pypi.org/project/spacedrep/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](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.
