Flashii is an AI-native flashcard system for learning through conversation instead of a traditional flashcard app UI.

The simplest way to understand it: Flashii is a personal memory layer that plugs into AI clients such as Claude Desktop, Claude iOS, or Claude Code through MCP. The learner talks to Claude to create cards, review due cards, and get coaching. Flashii handles the durable backend work: storing cards, scheduling reviews with FSRS, serving mnemonic images, and protecting access with API keys.

Flashii was created as a lightweight Anki replacement for language learning, especially for learning lexical chunks such as collocations, phrase patterns, and useful expressions. It is optimized for depth and explanation rather than high-speed deck drilling.

• A headless flashcard backend exposed through the Model Context Protocol (MCP)
• A spaced-repetition system using FSRS scheduling
• A personal learning database for cards, reviews, tags, progress, and user goals
• An optional mnemonic image pipeline backed by Gemini and Cloudflare R2
• A foundation for future adapters, such as a REST API or web app, without changing the core learning model

As a learner, you do not open a Flashii app. You open Claude and talk naturally.

For card creation:

1. Ask Claude for learning material, for example: "I want to learn lexical chunks about AI."
2. Claude proposes useful chunks and helps refine the list.
3. Claude writes the card content: definition, examples, IPA, tags, and optional image prompt.
4. Claude calls Flashii through MCP to save the finished cards.
5. Flashii stores the cards and, when requested, generates and stores mnemonic images.

For daily review:

1. Say: "Let's review."
2. Claude asks Flashii for cards due now, optionally filtered by tags such as AI or daily-life.
3. Claude quizzes you conversationally.
4. After each answer, Claude submits your rating to Flashii.
5. Flashii updates the FSRS schedule, while Claude can explain mistakes in plain language.

For progress coaching:

1. Ask: "How am I doing against my 1500-chunk goal?"
2. Flashii returns aggregated progress data.
3. Claude interprets the numbers, highlights drift, and suggests what to review or create next.

Flashii is best for learners who already use an AI assistant daily and want the assistant to become their tutor, not just a card generator. The MVP targets personal language learning on iPhone and Mac, with family use planned later through additional API keys.

It is not designed for users who need to blast through very large decks with a tap-only interface, such as medical exam decks with tens of thousands of cards. For that workflow, a traditional app like Anki is still a better fit.

Flashii currently runs as a Cloudflare Worker that exposes an authenticated MCP server. It stores structured learning data in Turso, generated card images in Cloudflare R2, and can optionally call Gemini to create mnemonic images during card creation.

The current production shape is:

• Runtime: Cloudflare Workers + Hono
• API surface: /health, /mcp, and public image serving at /img/:userId/:filename.png
• Database: Turso / libSQL
• Object storage: Cloudflare R2
• Image generation: Gemini image model via GEMINI_API_KEY

• Add, edit, list, suspend, unsuspend, and delete flashcards
• Review cards with FSRS scheduling
• Read coaching-oriented profile and progress data
• Optionally generate and store card images in R2
• Authenticate MCP requests with API keys hashed in the database

Source layout:

• src/index.ts: Worker entrypoint and HTTP routes
• src/adapters/mcp.ts: MCP tool registration and request handling
• src/core: domain logic for cards, reviews, progress, and users
• src/infra: auth, env types, Turso client, Gemini, and R2 helpers
• migrations: SQL schema migrations
• scripts: operational scripts such as key issuance and migrations
• tests: unit tests

• Node.js 20+
• pnpm 9+
• A Cloudflare account with Workers enabled
• A Turso database
• An R2 bucket
• A Gemini API key if you want image generation

Install dependencies:

pnpm install

Create local secrets:

cp .dev.vars.example .dev.vars

Populate .dev.vars with at least:

TURSO_URL=libsql://your-db.turso.io
TURSO_TOKEN=your-token
GEMINI_API_KEY=your-gemini-key

Optional local values:

GEMINI_IMAGE_MODEL=gemini-3-pro-image-preview
LOG_LEVEL=info

Run the Worker locally:

pnpm dev

Run checks:

pnpm typecheck
pnpm test

Apply migrations to your target Turso database:

TURSO_URL=libsql://your-db.turso.io TURSO_TOKEN=your-token pnpm migrate

This project expects the following Cloudflare resources and bindings:

• Worker name: flashii-api
• R2 binding: IMAGES
• R2 bucket name: flashii-card-images by default in wrangler.jsonc

Required secrets on the deployed Worker:

• TURSO_URL
• TURSO_TOKEN
• GEMINI_API_KEY

Optional secret:

• GEMINI_IMAGE_MODEL

Set secrets with Wrangler:

npx wrangler secret put TURSO_URL
npx wrangler secret put TURSO_TOKEN
npx wrangler secret put GEMINI_API_KEY

Deploy:

pnpm run deploy

Alternative explicit command:

pnpm run cf:deploy

Smoke test after deploy:

curl https://<your-worker-url>/health
curl -i https://<your-worker-url>/mcp

/mcp supports two ways to pass an API key:

• Authorization: Bearer <key>
• Query string fallback: /mcp?key=<key>

Header-based auth is the recommended production path. Query-string auth exists mainly for convenience and lightweight testing.

• GET /health: basic health check
• ALL /mcp: authenticated MCP endpoint
• GET /img/:userId/:filename.png: public image fetch from R2

• API keys are stored as SHA-256 hashes in the users table, not in plaintext
• Query-string auth is less safe than bearer headers because it can leak through logs and history
• Image routes are public by design in the current MVP
• This Worker depends on external services and costs can come from Cloudflare, Turso, R2, and Gemini usage

This is an active early-stage project. The core deploy path is working, but the public API and operational model may still change.

See CONTRIBUTING.md.

MIT