flashcards

Files (1)

• SKILL.md

SKILL.md (first lines)

# Flashcards

Flashcards live in the Obsidian vault as callouts and get batch-imported into
Mochi. This skill covers both writing and importing them.

## Writing flashcards

Add flashcards to the `## Flashcards` section of the current daily note (or
whatever file the user specifies). Use this exact callout format:

```
> [!flashcard|Deck Name] - [ ]
> Question text
> ---
> Answer text
```

- **Deck name** goes after the pipe `|`. Ask the user which deck if you're
  unsure. Common decks: Friends and Family, Geography, History, Science.
- `- [ ]` means not yet imported; `- [x]` means already synced to Mochi.
- Question and answer can span multiple lines — every line must start with `> `.
- `> ---` separates question from answer.

Do **not** use `question :: answer` syntax or any other format.

## Importing flashcards to Mochi

When the user asks to sync or import flashcards, run through these steps:

### 1. Get the Mochi API key

```bash
op read "op://Machine/secrets.zshrc/MOCHI_API_KEY"
```

If this fails, tell the user to check their 1Password setup and stop.

### 2. Find unmoved flashcards

Search all `.md` files under `~/workspace/vault/` for flashcard callouts where
the checkbox is `- [ ]`. Skip any marked `- [x]`.

Parse each callout:
- Deck name: text between `|` and `]`
- Question: lines between the header and `> ---`
- Answer: lines after `> ---` until the callout ends

Strip leading `> ` from content lines. Collect file paths and line numbers for
marking later.

### 3. Create cards in Mochi

Fetch existing decks:

```bash
curl -s -u "$MOCHI_API_KEY:" https://app.mochi.cards/api/decks/
```

For each flashcard:

1. **Match or create the deck** (case-insensitive). If the deck name is close
   but not exact (e.g. "social" vs "Friends and Family"), ask the user. If
   creating a new deck, confirm first:
   ```bash
   curl -s -u "$MOCHI_API_KEY:" -X POST https://app.mochi.cards/api/decks/ \
     -H "Content-Type: application/json" \
     -d '{"name": "Deck Name"}'
   ```

2. **Create the card**:
   ```bash
   curl -s -u "$MOCHI_API_KEY:" -X POST https://app.mochi.cards/api/cards/ \
     -H "Content-Type: application/json" \
     -d '{"content": "Question\n---\nAnswer", "deck-id": "deck_id_here"}'
   ```

Make API calls sequentially — Mochi enforces **one concurrent request per account**. Wait for each response before sending the next. Use 5-second gaps when doing bulk operations; use exponential backoff (starting at 5s) on 429.

### 3b. Cards with images

If a flashcard's question includes an Obsidian image embed (`![[filename.jpg]]`), the image must be uploaded as a Mochi attachment and the content reference updated. Do this **after** the card is created.

**Step 1 — Upload the attachment** (multipart form, one per card):

```bash
curl -s -u "$MOCHI_API_KEY:" \
  -X POST "https://app.mochi.cards/api/cards/$CARD_ID/attachments/$SLUG" \
  -F "file=@/path/to/image.jpg"
```

The `$SLUG` must match the regex `/[0-9a-zA-Z]{8,16}\.(jpg|jpeg|png)/` — generate a random 10-char alphanumeric string + extension. Example: `aB3kRt9mXq.jpg`.

**Step 2 — Update the card content** to reference the attachment:

```bash
curl -s -u "$MOCHI_API_KEY:" \
  -X POST "https://app.mochi.cards/api/cards/$CARD_ID" \
  -H "Content-Type: application/json" \
  -d "{\"content\": \"![](@media/$SLUG)\nQuestion text\n---\nAnswer\"}"
```

The `![](@media/slug)` syntax is how Mochi resolves card attachments in markdown. The update endpoint is `POST /api/cards/:id` (not PATCH or PUT — those return 404).

**Important gotchas discovered in practice:**
- The `attachments` key in the card create/update body is deprecated and returns 422 — always use the separate upload endpoint
- The rate limit error "Please wait for the previous request to finish" means a previous request is still processing server-side — wait 5+ seconds, not just until you receive a response
- If the upload succeeds but the content update fails, the attachment persists on the card — just re-run the content update step; no need to re-upload
- Slug filenames: 8–16 alphanumeric chars only (no hyphens or underscores), then the extension

**Python pattern for image cards:**

```python
import random, string, time, os, base64, urllib.request, json

def random_slug(ext, n=10):
    chars = ''.join(random.choices(string.ascii_letters + string.digits, k=n))
    return chars + ext

def upload_attachment(card_id, slug, file_path, api_key):

From jamierumbelow/agentfiles, MIT.

More from jamierumbelow/agentfiles