# Molecular Machines: review cards for agents

> Molecular Machines is an atlas of protein machines. Each machine page ends its sections with short review prompts.
> Readers grade them Forgot or Remembered, and a spaced-repetition scheduler (FSRS) brings each card back just before
> it would be forgotten. This file tells an AI agent how to take over a reader's reviews: fetch the cards, store the
> reader's state, schedule reviews and run them.

## Files

- [All cards](/learn/cards.json): JSON, format `molecular-machines.cards`, version 1.
- Per machine: `/learn/cards/<slug>.json`, for example [ATP synthase](/learn/cards/atp-synthase.json); `shared.json` holds the cross-machine cards.
- [Anki import file](/learn/anki.txt): tab-separated, for File → Import in Anki (Basic notes, one per card, with the card id as the note id).
- The reader's review state comes from the reader: on /learn they press "Hand off to your agent" (a prompt with the state inside) or "Export progress" (a JSON file).
- A reference MCP server that does all of this with SQLite lives in the `mcp/` folder of the site's repository.

## Cards

Each card has a stable `id` (keep progress keyed on it), `machine`, `kind` (`qa` or `cloze`), `prompt`, `answer`,
an optional `explanation`, `section` and `topic`, `sources` (ids of the facts it rests on), `cites` (those sources
resolved to labels and places), and `url` (the page that teaches it, relative to the site).

- A `cloze` prompt is a sentence with the answer inside double braces: "One full turn makes {{3}} ATP." Show it with
  the braces replaced by a blank, and reveal the hidden text as the answer.
- Cards change rarely. A card whose meaning changes gets a new id; old ids may disappear from the feed. Keep their
  state, but stop asking them.

## Review state

```json
{
  "format": "molecular-machines.review-state",
  "version": 1,
  "scheduler": { "name": "fsrs", "package": "ts-fsrs@5", "params": {"request_retention":0.9,"maximum_interval":36500,"enable_fuzz":false,"enable_short_term":false} },
  "cards": {
    "<card id>": { "due": "<ISO time>", "stability": 2.31, "difficulty": 2.12, "reps": 1, "lapses": 0, "state": "review", "last_review": "<ISO time>", "added": "<ISO time>" }
  },
  "log": [{ "card": "<card id>", "grade": "remembered", "at": "<ISO time>", "where": "reading" }]
}
```

- A card is in the reader's queue once it has an entry in `cards`. It is due when `due` is at or before now.
- `grade` is `forgot` or `remembered`; `where` is `reading` (inside the notes) or `review` (a session).

## Scheduling

Use FSRS-6, for example the `ts-fsrs` package (npm) or `py-fsrs` (PyPI), with these parameters:
request_retention 0.9, maximum_interval 36500 days, fuzz off, short-term learning steps off.
Map Forgot to Again (rating 1) and Remembered to Good (rating 3). To grade a card, rebuild the FSRS card from `due`,
`stability`, `difficulty`, `reps`, `lapses`, `state` and `last_review`, apply the rating at the current time, and
store the result in the same shape. Append the grade to `log`.

## Running a review

1. Pick the due cards, most overdue first. Ask about 10–20 at a time; stop when the reader wants to.
2. Show the prompt only. Wait for the reader to answer, in words or in their head.
3. Then show the answer and the explanation, and ask: "Did you remember?" Record Forgot or Remembered.
   Judge generously when the reader's words carry the idea; the reader decides when in doubt.
4. Do not teach new cards in a review unless the reader asks. New cards enter the queue when the reader meets them
   in the reading, or when they ask you for new cards from a machine.
5. Link to the card's `url` on the site when the reader wants to read more.

## Reminders

- Check once a day for due cards. If any are due, send one short message with the count and offer to start.
  Do not remind more than once a day, and stop when the reader asks.
- Fetch `/learn/cards.json` about once a week. Add cards with new ids (unseen, not in the queue) and leave the rest.
- When the reader comes back to the site, they can paste an exported state into /learn (Import) to carry on there.