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:

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?

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
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é.
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.").
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

Check for API key: Verify .env file exists with MOCHI_API_KEY
Check for default deck: Look for DEFAULT_DECK_ID in .env
Draft card content: Format as Front\n---\nBack
ALWAYS show for review: Display drafted card(s) and ask for confirmation before creating
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:

🇫🇷 &nbsp; Happy &nbsp; 🇫🇷
---
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:

#	Front	Back	Notes
1	Hello	Bonjour
2	Happy	Heureux (M) / Heureuse (F)

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.