MUST use when the user mentions flashcards, Mochi, spaced repetition, memorization, studying, or wanting to remember something. Trigger proactively when the user says "I want to remember this", "make flashcards", "create Mochi cards", "help me study", "turn this into flashcards", "SRS", "Anki", or "I need to memorize this". Creates evidence-based cards using cognitive science principles (Andy Matuschak's 5 properties of effective prompts) via the Mochi API.
Transform content into evidence-based Mochi.cards flashcards that produce lasting retention. Every card created must satisfy the 5 properties of effective prompts: focused, precise, consistent, tractable, and effortful.
Core Philosophy: Writing prompts for spaced repetition is task design. You're creating recurring retrieval tasks for your future self. Bad prompts waste time and fail to build lasting memory. Great prompts compound learning over years.
scripts/mochi_api.py — Python client for the Mochi API. Both importable (from scripts.mochi_api import MochiAPI) and CLI-executable (python scripts/mochi_api.py list-decks). Handles auth, field naming conventions (snake_case → kebab-case), and pagination.MOCHI_API_KEY environment variable (obtain from Mochi.cards → Account Settings → API Keys). Uses HTTP Basic Auth.export MOCHI_API_KEY="your_api_key_here"
Every prompt must satisfy all five (from Andy Matuschak's research):
Before creating each card, verify:
If any checkbox fails, revise before creating the card.
Reject these on sight:
| Anti-Pattern | Example | Fix |
|---|---|---|
| Binary (yes/no) | "Is encapsulation important?" | "What benefit does encapsulation provide?" |
| Pattern-matching | Long verbose question → obvious answer | Keep question short and direct |
| Unfocused | "Features, benefits, and drawbacks of X?" | Separate card per detail |
| Vague | "Tell me about async/await" | "What problem does async/await solve?" |
| Trivial | "What does URL stand for?" | "Why do URLs encode spaces as %20?" |
For full cognitive science background, knowledge-type strategies (factual, conceptual, procedural, salience), the five conceptual lenses, and research citations, consult:
→ references/prompt_design_principles.md
Load any stored feedback preferences before starting:
python ${PLUGIN_ROOT}/scripts/feedback_manager.py mochi-creator show-feedback
If feedback entries exist, apply them throughout card creation:
Determine the scope and emotional connection before drafting any cards.
Ask the user:
api.list_decks() or create new)If the user seems unmotivated or creating cards "because they should," push back gently. Emotional connection is primary — boredom leads to abandonment of the entire system.
Identify card format:
--- separator between sidesfrom scripts.mochi_api import MochiAPI, MochiAPIError
api = MochiAPI()
# List existing decks
decks = api.list_decks()
# Or create a new deck
deck = api.create_deck(name="Python Programming")
deck_id = deck["id"]
Apply knowledge-type appropriate strategies. Always follow the "More Than You Think" rule: write 3-5 focused prompts instead of 1 comprehensive prompt.
For factual knowledge — Break into atomic units:
# Instead of one card listing all ingredients, create focused cards:
facts = [
("What is the primary dry ingredient in chocolate chip cookies?", "Flour"),
("What fat is used in chocolate chip cookies?", "Butter"),
("What two sweeteners are used?", "White sugar and brown sugar"),
]
For conceptual knowledge — Use multiple lenses (attributes, similarities, parts, causes, significance):
# Approach a concept from 5 angles for robust understanding
cards = [
("What is the core attribute of dependency injection?",
"Dependencies are provided from outside rather than created internally"),
("How does dependency injection differ from service locator?",
"DI pushes dependencies in, service locator pulls them out"),
("What problem does dependency injection solve?",
"Makes code testable by allowing mock dependencies to be injected"),
]
For procedural knowledge — Focus on transitions, rationale, and timing (not rote steps):
# Focus on WHY and WHEN, not step numbers
cards = [
("Why do you autolyse before adding salt?",
"Salt inhibits gluten development; autolyse allows gluten to form first"),
("What indicates sourdough is ready for shaping?",
"50-100% volume increase, jiggly texture, small bubbles on surface"),
]
For salience prompts — Context-based application for behavioral change:
# Answers may vary — experimental, less well-researched
cards = [
("What's one situation this week where you could apply first principles thinking?",
"(Give an answer specific to your current work context)"),
]
For detailed cognitive science strategies per knowledge type, consult:
→ references/prompt_design_principles.md
For ready-to-use Python helper functions per knowledge type (create_concept_cards_five_lenses(), create_procedure_cards(), etc.), consult:
→ references/knowledge_type_templates.md
Present all drafted cards to the user before creating them. For each card, show:
Flag quality issues proactively:
Wait for user approval before proceeding to Step 3.
Create approved cards with error handling. Use tags for organization.
Simple cards:
card = api.create_card(
content="# What problem does dependency injection solve?\n---\nMakes code testable by allowing mock dependencies to be injected",
deck_id=deck_id,
manual_tags=["design-patterns", "dependency-injection"]
)
Template-based cards:
# Create or retrieve a template
template = api.create_template(
name="Vocabulary Card",
content="# << Word >>\n\n**Definition:** << Definition >>\n\n**Example:** << Example >>",
fields={
"word": {"id": "word", "name": "Word", "type": "text", "pos": "a"},
"definition": {"id": "definition", "name": "Definition", "type": "text", "pos": "b",
"options": {"multi-line?": True}},
"example": {"id": "example", "name": "Example", "type": "text", "pos": "c",
"options": {"multi-line?": True}}
}
)
# Create cards using the template
card = api.create_card(
content="",
deck_id=deck_id,
template_id=template["id"],
fields={
"word": {"id": "word", "value": "ephemeral"},
"definition": {"id": "definition", "value": "Lasting for a very short time; temporary"},
"example": {"id": "example", "value": "The beauty of cherry blossoms is ephemeral."}
}
)
Batch creation with error handling:
results = {"success": [], "failed": []}
for question, answer in cards:
try:
card = api.create_card(
content=f"# {question}\n---\n{answer}",
deck_id=deck_id,
manual_tags=tags
)
results["success"].append(card["id"])
except MochiAPIError as e:
results["failed"].append({"question": question, "error": str(e)})
Report to the user:
After reporting results, offer refinement:
Cards are created directly in the user's Mochi.cards account via the API. The deliverable is:
Cards use markdown with --- to separate sides:
# Question text
---
Answer text with **formatting**
Use hierarchical structures: Subject → Topic → Subtopic
parent = api.create_deck(name="Programming")
child = api.create_deck(name="Python", parent_id=parent["id"])
Soft delete (preferred, reversible):
from datetime import datetime
api.update_card(card_id, trashed=datetime.utcnow().isoformat())
Pagination for large collections:
result = api.list_cards(deck_id=deck_id, limit=100)
if result.get("bookmark"):
next_page = api.list_cards(deck_id=deck_id, limit=100, bookmark=result["bookmark"])
For complete API details, field types, and edge cases, consult:
→ references/mochi_api_reference.md