Molecular Machines

Learn / For agents

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: JSON, format molecular-machines.cards, version 1.
  • Per machine: /learn/cards/<slug>.json, for example ATP synthase; shared.json holds the cross-machine cards.
  • Anki import file: 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

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

The same text, as plain Markdown for an agent to read: /learn/llms.txt.