Memento Flashcards: Spaced Repetition Skill for Hermes Agent

Memento Flashcards is an optional Hermes Agent skill that turns facts into a local, file-based flashcard deck with spaced-repetition scheduling. You talk to it in plain language, the agent writes the cards, grades your free-text answers, and decides when each card comes back. It suits anyone using Hermes as a study or knowledge-retention assistant: language learners, exam candidates, people who want to remember what they read, and anyone who wants a quiz pulled from a YouTube transcript without leaving the chat.

What it does

The skill gives the agent four jobs. It creates question/answer cards from statements you make or from a manual request. It runs review sessions where you answer in your own words and the agent compares your answer to the stored one, tells you the correct answer, and rates the card. It generates a five-question quiz from a YouTube video transcript. And it manages decks: collections, CSV export and import, statistics, and deletion.

Everything lives in one JSON file on disk. There are no external API keys. The agent itself writes the card content and the quiz questions, so the only moving part is the local script that stores and schedules cards.

A note on tone: the skill instructs the agent to reply in plain text, with no Markdown formatting, and to keep review and quiz feedback brief and neutral. Expect short, factual responses during a session, not encouragement.

Before you start

Memento is an optional skill, so it is not part of a default Hermes install. You install it on demand from the optional-skills/productivity/memento-flashcards path. The skill is version 1.0.0, authored by Memento AI, and released under the MIT licence. It is listed for macOS and Linux only.

You need a working Hermes Agent setup with the terminal tool available, because every operation goes through Python scripts invoked from the shell. The card store is created automatically on first use, so there is no initialisation step.

One dependency is conditional. The YouTube quiz script needs youtube-transcript-api. If it is missing, the script reports missing_dependency and you prepare the declared youtube extra as described in the YouTube section below. Card creation, review, export, import, and statistics do not need it.

Card storage

Cards are kept in a single JSON file:

~/.hermes/skills/productivity/memento-flashcards/data/cards.json

Do not edit that file by hand. The script performs atomic writes, writing to a temporary file and then renaming it, which is what protects the store from corruption. Going around the script gives up that protection. The file appears on first use, so a fresh install has nothing to inspect until you create a card.

Creating cards

The skill does not convert every fact you mention into a card. It applies a three-tier check before acting.

1. Explicit intent. You say something like "memento", "flashcard", "remember this", "save this card", or "add a card". The agent creates the card directly, with no confirmation step.
2. Implicit intent. You state a fact without mentioning flashcards, for example "The speed of light is 299,792 km/s". The agent asks "Want me to save this as a Memento flashcard?" and only creates it if you confirm.
3. No intent. The message is a coding task, a question, instructions, or ordinary conversation. The skill stays out of the way and other behaviour handles the message.

Once a card is warranted, the agent turns the statement into a front-back pair. The question should test recall of the key fact and the answer should be short and direct. The prompt the agent works from is:

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

Statement: "{statement}"

It then stores the card with the add subcommand:

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

The script returns JSON confirming the created card. If you do not name a collection, the card goes into "General".

Manual card creation

When you ask for a flashcard outright, the agent collects three things: the question, the answer, and an optional collection name that defaults to "General". It then calls add exactly as above. This is the path to use when you already know what you want to be tested on and would rather dictate the wording than have the agent phrase it.

Reviewing due cards

A review session starts by fetching everything that is due:

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

This returns a JSON array of cards whose next_review_at is at or before the current time. To narrow the session to one deck:

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

The review loop is strict, and it is worth knowing the shape of it because the agent is required to follow it exactly.

1. The agent shows only the question and waits.
2. You answer in free text.
3. The agent grades the answer as correct, partial, or incorrect. Correct means the key fact is right even if worded differently. Partial means the right track but a missing core detail. Incorrect means wrong or off-topic.
4. The agent must tell you the correct answer and how you did, in plain text, before anything else. The expected formats are: "Correct. Answer: {answer}. Next review in 7 days.", "Close. Answer: {answer}. {what they missed}. Next review in 3 days.", and "Not quite. Answer: {answer}. Next review tomorrow."
5. The agent rates the card, mapping correct to easy, partial to good, and incorrect to hard.
6. The next question appears.

The rating call looks like this:

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

If nothing is due, the agent tells you: "No cards due for review right now. Check back later!"

You can retire a card at any point by saying "retire this card". That is the --rating retire path, and it removes the card from future reviews permanently.

How the schedule moves

The rating sets the next interval and changes the card's status.

Rating	Interval	ease_streak	Status change
hard	+1 day	reset to 0	stays learning
good	+3 days	reset to 0	stays learning
easy	+7 days	+1	if ease_streak >= 3 → retired
retire	permanent	reset to 0	→ retired

A card is either learning, meaning it is in active rotation, or retired, meaning it no longer appears. Three consecutive easy ratings retire a card automatically, on the assumption that you have mastered it. A single hard or good rating resets the streak, so the count has to be unbroken.

Generating a quiz from a YouTube video

This is the part that pulls in an external dependency. The flow has six steps.

Step 1: extract the video ID. Both youtube.com/watch?v=ID and youtu.be/ID URL forms are supported. For example, dQw4w9WgXcQ comes from https://www.youtube.com/watch?v=dQw4w9WgXcQ.

Step 2: fetch the transcript.

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

This returns {"title": "...", "transcript": "..."} or an error.

If the script reports missing_dependency, prepare the declared youtube extra using terminal with a PM-prepared Hermes checkout, then reactivate:

python -c "import pm; pm.sync_venv(['youtube'], explicit=True)"
source ./activate
python -c "import youtube_transcript_api; print(youtube_transcript_api.__file__)"

Follow the isolated development-home setup in Package Management before preparation. Retry youtube_quiz.py with that Python and the actual skill directory returned by skill_view. For a remote or sandbox terminal, prepare an independent helper environment on that host. Never pip-install into Hermes's selected environment.

Step 3: generate five questions. The agent writes them from the transcript, using the first 15,000 characters as context. The selection rules favour important, surprising, or foundational facts and skip filler, obvious details, and facts that need heavy context. True/false questions are out, and so are questions that only ask for a date. Each question tests exactly one discrete fact, uses clear wording, and prefers What, Who, How many, or Which over open-ended Describe or Explain prompts. Each answer stays under 240 characters, leads with the answer itself, and adds only minimal clarification. The instruction the agent follows is:

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.

Step 4: validate. The output must be valid JSON with exactly five items, each carrying non-empty question and answer strings. If validation fails, the agent retries once.

Step 5: store the cards.

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

The script deduplicates by video_id. If cards for that video already exist, it skips creation and reports the existing cards, so re-running a quiz on the same video will not pile up duplicates.

Step 6: run the quiz. Questions are presented one at a time as "Question 1/5: ..." with no answer and no hint about revealing it. You answer in your own words, the agent grades using the same three-level scheme as a review, and it must show you the grade, the correct answer, and when the card is next due before moving on. The rating call is the same rate command shown in the review section. Every answer gets visible feedback before the next question.

Export, import, and statistics

Export writes a three-column CSV with no header row, in the order question,answer,collection:

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

Import reads a CSV with question, answer, and optionally collection in column three. If the collection column is absent, the --collection argument supplies the deck name:

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

Statistics give you a snapshot of the whole store:

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

The JSON includes total for the card count, learning for cards in active rotation, retired for mastered cards, due_now for cards due right now, and collections for a breakdown by collection name.

Deletion uses delete --id ID for a single card and delete-collection --collection NAME for a whole deck.

When not to use it

The skill is scoped to memory work. General Q&A, coding help, and anything that is not a memory task should be handled by other skills or by default behaviour. If you want a one-off explanation rather than something you will be tested on later, a flashcard is the wrong tool. The same applies to facts you will never revisit: a card you never review is just clutter in the store.

Limits and gotchas

• Do not edit cards.json directly. The atomic write behaviour only applies when you go through the script subcommands.
• Transcript failures. Some YouTube videos have no English transcript, or have transcripts disabled. When that happens, the agent should tell you and suggest a different video. There is no fallback transcription path in the skill.
• Optional dependency. youtube_quiz.py needs youtube-transcript-api. Use the PM preparation and interpreter check above if it is missing, and never pip-install into Hermes's selected environment.
• Large imports. CSV imports with thousands of rows work, but the JSON output can be verbose. The agent is expected to summarise the result rather than paste it.
• Video ID extraction. Both youtube.com/watch?v=ID and youtu.be/ID formats are supported, so either style of link works.

Verifying the install

You can exercise the helper scripts directly before trusting a session to them:

python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py stats
python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py add --question "Capital of France?" --answer "Paris" --collection "General"
python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py due

If you are testing from the repo checkout, run:

scripts/run_tests.sh tests/skills/test_memento_cards.py tests/skills/test_youtube_quiz.py -q

At the agent level, two checks matter. Start a review and confirm the feedback is plain text, brief, and always includes the correct answer before the next card. Then run a YouTube quiz flow and confirm each answer receives visible feedback before the next question.

What pairs with it

The YouTube path depends on the package management workflow, so keep the Package Management reference nearby when preparing the youtube extra. Beyond that, Memento sits well alongside any skill that produces facts worth retaining: research and reading skills feed it statements, and the review loop keeps them in rotation.