Mochi Srs

Mochi SRS

Create flashcards and run conversational spaced repetition reviews using Mochi.

CLI tool

The mochi CLI is at ~/.agents/skills/mochi-srs/bin/mochi. Symlink to PATH: ln -sf ~/.agents/skills/mochi-srs/bin/mochi ~/.local/bin/mochi

Conversational review flow

When the user says "mochi review", "review cards", "flashcard review", or similar:

1. Get due cards: Run mochi next --limit 10 (or whatever limit the user wants). Tell the user the total due count.

   • Topic filtering: If the user asks to review a specific topic (e.g. "review salsa cards", "review French cards"), fetch a larger batch with mochi next --limit 50, then filter to cards whose content contains the relevant emoji (💃 for salsa, 🇫🇷 for French). Only present the matching cards.
   • Two-phase daily review: If the user wants a daily batch like "5 review then 5 new", first run mochi next --limit 5, complete those reviews, then run mochi new --limit 5 and continue with those if any exist. Be explicit about the switch: e.g. Done with due cards. You’ve got 5 new ones available—shall we keep going?

2. Present cards one at a time — behaviour depends on card_type:

   • qa: Show the question (front); wait for the user to reply with their answer
   • cloze: Show the masked front (blanks shown as [...]); ask the user to fill in the blank(s)
   • note: Show the full content; ask for a direct rating: (1) remembered or (2) forgot

3. Evaluate the response and briefly review the card:

   • Compare the user's answer to the back (answer) of the card
   • For cloze cards the answer field shows the original text with blanks filled in as [word] — compare against those
   • If correct: confirm briefly and note the answer
   • If partially correct: acknowledge what's right, show the full correct answer
   • If wrong: say so directly, show the correct answer
   • For note/quote cards: ask the user if they remembered it

   Always print the exact card back verbatim before your correctness judgment. Preserve all spacing/line breaks, punctuation, and formatting: Back: <exact_back>

   After showing the answer, do a quick quality check on the card itself:

   • Look for obvious mistakes, likely factual errors, confusing wording, awkward formatting, or mismatches between front and back
   • For French cards, check spelling, accents, articles, gender, plural forms, and naturalness
   • For factual cards, flag anything that seems clearly wrong or suspicious
   • For procedural/skill cards, flag missing key steps or ambiguity only if it would materially improve recall

   Threshold: most of the time, say nothing extra. Only add a note when there is something clearly above the bar.

   • Definitely mention: misspelt French, wrong accents when relevant, wrong article/gender if the card is teaching that, likely factual mistakes, or seriously unclear wording
   • Sometimes mention: a substantially clearer phrasing or formatting improvement
   • Rarely mention: optional polish that doesn't much matter

   If there is something worth saying, keep it short and use one of these:

   • Card note: for a likely issue with the card
   • Memory hint: for a recall aid

   Examples:

   • Card note: this should probably be "la jalousie".
   • Card note: Earth–Moon distance is about 384,000 km, so this card may be wrong.
   • Memory hint: picture a neurotic Parisian saying "névrosé" in a café.

4. Submit the review: Run mochi submit <card_id> remembered or mochi submit <card_id> forgot based on the result. Tell the user the outcome briefly (e.g., "Submitted. Next review in 213 days.").

5. Continue with the next card until done, then summarise the session.

Important notes:

• Keep the flow conversational and quick—don't over-explain
• For quote cards (no answer/back), show the quote and ask "Did you remember this?"
• Accept partial/approximate answers as correct for most cards
• For French vocabulary cards (🇫🇷), misspellings and missing accents count as forgotten rather than remembered
• If the card’s back includes optional inflection markers or variants (for example névrosé(e) or Heureux (M) / Heureuse (F)), accept the base form as remembered unless the prompt explicitly asks for the inflected forms or the contrast is the thing being tested
• Be strict on factual cards (dates, names, definitions)
• When offering a mnemonic, prefer visual or story-based mnemonics over abstract verbal tricks
• Mnemonics are most useful after a miss or near-miss; don't force one for every card
• At least half the time, there should be no extra suggestion at all
• If the user likes a suggested mnemonic, make it easy to save: a very short confirmation like y, ok, or + should mean "append that mnemonic on a new line at the bottom of the back of this card"
• When that happens, fetch the card, preserve the existing back exactly, append the mnemonic as a new final line, update the card, and confirm briefly
• The user can say "skip", "stop", or "quit" at any time

Card creation

When the user says "mem", "memorise", "flashcard", or asks to create cards:

Workflow

1. Check for API key: Verify .env file exists with MOCHI_API_KEY
2. Check for default deck: Look for DEFAULT_DECK_ID in .env
3. Draft card content: Format as Front\n---\nBack
4. ALWAYS show for review: Display drafted card(s) and ask for confirmation before creating
5. Create only after approval: mochi create --deck DECK_ID --content "Front\n---\nBack"

CRITICAL: Never create cards without showing the content first and getting user approval.

CLI commands

# Create a card
mochi create --deck DECK_ID --content "Question\n---\nAnswer"
mochi create --deck-name "French" --content "Question\n---\nAnswer"

# List decks
mochi decks

# List cards
mochi cards --deck DECK_ID

# Delete a card
mochi delete CARD_ID

# Get due cards (human-readable)
mochi due

# Get due cards (JSON, for agent use)
mochi next --limit 5

# Get new/unreviewed cards (JSON, for agent use)
mochi new --limit 5

# Get a single card
mochi get CARD_ID

# Submit a review
mochi submit CARD_ID remembered
mochi submit CARD_ID forgot

# Interactive terminal review
mochi review --limit 10

All commands support --deck ID or --deck-name NAME to filter by deck.

Card format

Mochi cards use markdown. Standard question/answer format:

Question text here
---
Answer text here

Cards support full markdown: bold, italic, code, lists, code blocks, LaTeX ($inline$, $$block$$), and images.

French vocabulary cards

When user provides French words or phrases:

• Front: 🇫🇷   [English text]   🇫🇷 (British English spelling)
• Back: French word/phrase
• Fix spelling/accents/grammar errors and flag corrections to the user
• For M/F forms, show both on the back:

🇫🇷   Happy   🇫🇷
---
Heureux (M)
Heureuse (F)

Salsa cards

• Front: 💃   [Question/topic]   💃
• Back: Technique details or answer

Bulk card display

Show multiple cards in a table for review:

Examples of good intervention

• User answers Jalosie for La jalousie

  • Mark as forgot
  • Say: Forgotten. Correct answer: la jalousie.
  • Optional: Memory hint: imagine jealousy as a woman named Jalousie in a green dress—la jalousie.
  • If the user replies y, ok, or +, append that mnemonic as a new final line on the back of the current card

• Card says Earth–Moon distance is 150,000 km

  • If the revealed answer is clearly wrong, say:
  • Card note: this card appears factually wrong; average Earth–Moon distance is about 384,000 km.

• French answer is technically right but clunky

  • Say only if the improvement is meaningful:
  • Card note: your version is understandable, but this phrasing is more natural in French: ...

Configuration

• API key: ~/.agents/skills/mochi-srs/.env → MOCHI_API_KEY=...
• Default deck: ~/.agents/skills/mochi-srs/.env → DEFAULT_DECK_ID=...
• Local DB: ~/Library/Application Support/Mochi/mochi.db (read for faster due-card lookup, falls back to API)

Troubleshooting

• "MOCHI_API_KEY not found": Add API key to .env
• "401 Unauthorized": Regenerate key in Mochi Settings > API
• "429 Too Many Requests": Wait and retry. Mochi limits to 1 concurrent request.