Memento Flashcards: A Local, File-Based Spaced Repetition System

Overview

Memento Flashcards is a local, file-based flashcard system with spaced-repetition scheduling. Users interact with flashcards through a conversational interface, answering in free text, while the agent grades responses and schedules the next review. The system stores all data in a JSON file at ~/.hermes/skills/productivity/memento-flashcards/data/cards.json, which is created automatically on first use. Never edit this file directly; always use the provided scripts, which use atomic writes to prevent corruption.

When to Use Memento Flashcards

Use this system when:

• The user wants to save facts as flashcards for later review.
• The user wants to review due cards with spaced repetition.
• The user wants to generate a quiz from a YouTube video transcript.
• The user wants to import, export, inspect, or delete flashcard data.

Do not activate this skill for general Q&A, coding help, instructions, or normal conversation.

Prerequisites

• Python 3 must be available.
• Scripts are located at ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py and youtube_quiz.py.
• For YouTube quizzes, the optional dependency youtube-transcript-api must be installed. If missing, tell the user to run pip install youtube-transcript-api.
• The data directory and cards.json are created automatically on first use.

Capabilities

Creating Flashcards from Facts

When the user expresses explicit intent to save a fact (e.g., "remember this", "save as flashcard", "add a card", or mentions "memento"), create the flashcard directly without asking for confirmation. For implicit factual statements that do not mention flashcards, ask "Want me to save this as a Memento flashcard?" and only create the card if confirmed. Do not activate for coding tasks, questions, instructions, or normal conversation.

To generate the question/answer pair from a factual statement, use this internal prompt:

Turn the factual statement into a front-back pair.
Return exactly two lines:
Q: <question text>
A: <answer text>

Statement: "{statement}"

Then call the script:

python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py add \
  --question "What year did World War 2 end?" \
  --answer "1945" \
  --collection "History"

The --collection parameter is optional and defaults to "General" if not provided.

Manual Card Creation

To create a card manually, ask the user for:

• The question (front of the card).
• The answer (back of the card).
• An optional collection name (defaults to "General").

Then call memento_cards.py add with the provided values.

Reviewing Due Cards

Fetch due cards using:

python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py due

Optionally filter by collection:

python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py due --collection "History"

If no cards are due, tell the user: "No cards due for review right now. Check back later!"

For each card, show only the question and wait for the user's free-text answer. Grade the answer as:

• Correct: The key fact is right, even if worded differently.
• Partial: The user is on the right track but missing a core detail.
• Incorrect: The answer is wrong or off-topic.

Always tell the user the correct answer and feedback before moving to the next card:

• Correct: "Correct. Answer: {answer}. Next review in 7 days."
• Partial: "Close. Answer: {answer}. {what they missed}. Next review in 3 days."
• Incorrect: "Not quite. Answer: {answer}. Next review tomorrow."

Then call the rate command:

python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py rate \
  --id CARD_ID --rating easy --user-answer "what the user said"

Map grading to ratings: correct -> easy, partial -> good, incorrect -> hard.

The spaced repetition algorithm works as follows:

• hard: +1 day, reset ease_streak to 0, stays learning.
• good: +3 days, reset ease_streak to 0, stays learning.
• easy: +7 days, increment ease_streak. If ease_streak >= 3, the card is retired.
• retire: Permanently remove from reviews. Reset ease_streak to 0, mark as retired.

If the user says "retire this card", use --rating retire to permanently remove it from reviews.

YouTube Quiz Generation

Extract the video ID from the URL. Support both youtube.com/watch?v=ID and youtu.be/ID formats. For example, the video ID for https://www.youtube.com/watch?v=dQw4w9WgXcQ is dQw4w9WgXcQ.

Fetch the transcript using:

python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/youtube_quiz.py fetch VIDEO_ID

This returns JSON in the format {"title": "...", "transcript": "..."} on success, or an error. If the error indicates missing_dependency, tell the user to run pip install youtube-transcript-api. If the video has no English transcript or transcripts are disabled, inform the user and suggest another video.

Generate 5 quiz questions from the first 15,000 characters of the transcript using these rules:

You are creating a 5-question quiz for a podcast episode.
Return ONLY a JSON array with exactly 5 objects.
Each object must contain keys 'question' and 'answer'.

Selection criteria:
- Prioritize important, surprising, or foundational facts.
- Skip filler, obvious details, and facts that require heavy context.
- Never return true/false questions.
- Never ask only for a date.

Question rules:
- Each question must test exactly one discrete fact.
- Use clear, unambiguous wording.
- Prefer What, Who, How many, Which.
- Avoid open-ended Describe or Explain prompts.

Answer rules:
- Each answer must be under 240 characters.
- Lead with the answer itself, not preamble.
- Add only minimal clarifying detail if needed.

Validate that the output is valid JSON with exactly 5 objects, each having non-empty question and answer strings. If validation fails, retry once.

Store the quiz cards using:

python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py add-quiz \
  --video-id "VIDEO_ID" \
  --questions '[{"question":"...","answer":"..."},...]' \
  --collection "Quiz - Episode Title"

This deduplicates by video_id. If cards already exist for that video, skip creation and report that they already exist.

Present quiz questions one by one. Show "Question X/5: ..." (never include the answer or hint), wait for the user's answer, grade it, show feedback with the correct answer and next review time, call the rate command, then show the next question in the same message. Every answer must receive visible feedback before the next question.

Exporting and Importing CSV

Export cards to CSV using:

python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py export \
  --output ~/flashcards.csv

This produces a 3-column CSV with columns question,answer,collection and no header.

Import cards from CSV using:

python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py import \
  --file ~/flashcards.csv \
  --collection "Imported"

The CSV must have columns: question, answer, and an optional collection column. If the collection column is missing, the value from --collection is used. CSV imports with thousands of rows work, but JSON output may be verbose; summarize the result for the user.

Statistics

Show statistics using:

python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py stats

This returns JSON with keys: total, learning, retired, due_now, and collections (a breakdown by collection).

Deleting Cards and Collections

Delete a specific card:

python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py delete --id ID

Delete an entire collection:

python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py delete-collection --collection NAME

Parameters

Parameter	Meaning	Required
--question	The front text of the flashcard (the question)	Yes for add command
--answer	The back text of the flashcard (the answer)	Yes for add command
--collection	The collection name to organize cards under	No; defaults to "General"
--id	The unique ID of a card (used for rate, delete commands)	Yes for rate and delete commands
--rating	The rating for spaced repetition: easy, good, hard, or retire	Yes for rate command
--user-answer	The user's free-text answer for logging	Yes for rate command
--output	File path for CSV export	Yes for export command
--file	File path for CSV import	Yes for import command
--video-id	YouTube video ID for quiz generation	Yes for add-quiz command
--questions	JSON array of question-answer objects for quiz	Yes for add-quiz command

Constraints and Caveats

• Never edit cards.json directly; always use memento_cards.py subcommands.
• User-facing responses must be plain text only, no Markdown formatting.
• Review and quiz feedback must be brief and neutral; avoid extra praise, pep, or long explanations.
• During review, always show the correct answer and feedback before moving to the next card.
• During quiz, every answer must receive visible feedback before the next question.
• Three consecutive "easy" ratings automatically retire a card.
• YouTube transcript: some videos have no English transcript or have transcripts disabled; inform the user and suggest another video.
• youtube_quiz.py requires the optional dependency youtube-transcript-api; if missing, tell the user to run pip install youtube-transcript-api.
• Video ID extraction must support both youtube.com/watch?v=ID and youtu.be/ID URL formats.
• Do not use this skill for general Q&A, coding help, or non-memory tasks.

Failure Modes

• Editing cards.json directly causes data corruption.
• YouTube transcript fetch fails if the video has no English transcript or transcripts are disabled.
• youtube_quiz.py fails if youtube-transcript-api is not installed.
• Quiz question generation may produce invalid JSON; retry once if validation fails.
• CSV import may have a missing collection column; it falls back to the --collection argument.

Example Review Flow

Agent: "What year did the Berlin Wall fall?" User: "1991" Agent: "Not quite. The Berlin Wall fell in 1989. Next review is tomorrow." Then calls memento_cards.py rate --id CARD_ID --rating hard --user-answer "1991". Then shows the next question: "Who was the first person to walk on the moon?"

Example Quiz Feedback

"Not quite. Answer: {answer}. Next review tomorrow." Followed by the rate command and the next question.

Testing

Run the test suite with:

pytest tests/skills/test_memento_cards.py tests/skills/test_youtube_quiz.py -q

Quick Reference of Commands

• memento_cards.py add -- Add a new flashcard.
• memento_cards.py due -- List due cards (optionally with --collection).
• memento_cards.py rate -- Rate a card after review.
• youtube_quiz.py fetch VIDEO_ID -- Fetch a YouTube transcript.
• memento_cards.py add-quiz -- Add quiz questions from a YouTube video.
• memento_cards.py export --output PATH -- Export cards to CSV.
• memento_cards.py import --file PATH --collection NAME -- Import cards from CSV.
• memento_cards.py stats -- Show statistics.
• memento_cards.py delete --id ID -- Delete a specific card.
• memento_cards.py delete-collection --collection NAME -- Delete an entire collection.

The condition for a card to be due is next_review_at <= now.