{"id":21578277,"url":"https://github.com/StephanAkkerman/mnemorai","last_synced_at":"2025-07-16T20:31:28.070Z","repository":{"id":182250123,"uuid":"668185671","full_name":"StephanAkkerman/FluentAI","owner":"StephanAkkerman","description":"Automating language learning with the power of Artificial Intelligence. This repository presents FluentAI, a tool that combines Fluent Forever techniques with AI-driven automation. It streamlines the process of creating Anki flashcards, making language acquisition faster and more efficient.","archived":false,"fork":false,"pushed_at":"2024-11-19T17:20:17.000Z","size":160553,"stargazers_count":9,"open_issues_count":22,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-11-19T17:21:30.431Z","etag":null,"topics":["anki","anki-addon","anki-flashcards","flash-card","flash-cards","fluent-forever","language","language-learning","language-learning-app","language-learning-tool","mnemonic","mnemonics"],"latest_commit_sha":null,"homepage":"https://akkerman.ai/FluentAI/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/StephanAkkerman.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":"supported-languages.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-19T08:15:30.000Z","updated_at":"2024-11-18T08:23:03.000Z","dependencies_parsed_at":"2024-11-19T17:30:12.012Z","dependency_job_id":null,"html_url":"https://github.com/StephanAkkerman/FluentAI","commit_stats":null,"previous_names":["stephanakkerman/fluentai"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StephanAkkerman%2FFluentAI","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StephanAkkerman%2FFluentAI/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StephanAkkerman%2FFluentAI/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StephanAkkerman%2FFluentAI/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/StephanAkkerman","download_url":"https://codeload.github.com/StephanAkkerman/FluentAI/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226165742,"owners_count":17583856,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anki","anki-addon","anki-flashcards","flash-card","flash-cards","fluent-forever","language","language-learning","language-learning-app","language-learning-tool","mnemonic","mnemonics"],"created_at":"2024-11-24T13:10:02.038Z","updated_at":"2025-07-16T20:31:28.053Z","avatar_url":"https://github.com/StephanAkkerman.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mnemorai: remember more with mnemorai 🧠\n\n![mnemorai Banner](img/banner.png)\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eLearn languages faster and remember more with AI-powered mnemonic flashcards seamlessly integrated into Anki.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"GitHub Actions Workflow Status\" src=\"https://img.shields.io/github/actions/workflow/status/StephanAkkerman/mnemorai/pyversions.yml?label=python%203.10%20%7C%203.11%20%7C%203.12\"\u003e\n  \u003cimg src=\"https://img.shields.io/github/license/StephanAkkerman/mnemorai.svg?color=g\" alt=\"License\"\u003e\n  \u003ca href=\"https://github.com/psf/black\"\u003e\u003cimg src=\"https://img.shields.io/badge/code%20style-black-000000.svg\" alt=\"Code style: black\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://discord.gg/z56zRXtNR5\"\u003e\u003cimg src=\"https://dcbadge.limes.pink/api/server/z56zRXtNR5?style=flat\" alt=\"Discord Shield\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\nTired of looking at boring flash cards and manually having to create them yourself? **mnemorai** leverages the power of AI to create unique, memorable connections for new vocabulary. Inspired by the research paper [SmartPhone: Exploring Keyword Mnemonic with Auto-generated Verbal and Visual Cues](https://arxiv.org/pdf/2305.10436.pdf), this tool automatically generates:\n\n*   **Phonetic Keyword Matches:** Finds words in your native language that sound similar to the target word.\n*   **Engaging Verbal Cues:** Creates short, catchy sentences linking the keyword and the target word's meaning.\n*   **Vivid Visual Cues:** Generates unique images based on the verbal cue to create strong memory anchors.\n*   **Anki Integration:** Saves these rich flashcards directly into your Anki decks.\n\n**The result?** More effective, engaging, and scientifically-backed language learning.\n\n➡️ **Explore the [Wiki](https://github.com/StephanAkkerman/mnemorai/wiki) for detailed documentation.** \u003cbr/\u003e\n➡️ **See the list of [Supported Languages](https://github.com/StephanAkkerman/mnemorai/wiki/Supported-languages).**\n\n## Table of Contents 🗂\n\n*   [Key Features](#key-features-)\n*   [How it Works](#how-it-works-%EF%B8%8F)\n*   [Demo](#demo-)\n*   [The Science Behind It](#the-science-behind-it-)\n*   [System Requirements](#system-requirements-%EF%B8%8F)\n*   [Installation](#installation-%EF%B8%8F)\n*   [Usage](#usage-%EF%B8%8F)\n*   [Docker](#docker-)\n*   [Citation](#citation-%EF%B8%8F)\n*   [Contributing](#contributing-)\n*   [License](#license-)\n*   [Contact](#contact-)\n\n## Key Features ✨\n\n*   **🤖 AI-Powered Mnemonics:** Automatically generates phonetic keywords, verbal cues, and visual aids.\n*   **🖼️ Custom Image Generation:** Creates unique images tailored to each mnemonic cue using models like SDXL-Turbo or Sana.\n*   **🗣️ Text-to-Speech:** Includes audio pronunciation for target words.\n*   **🃏 Anki Integration:** Seamlessly saves generated flashcards to your specified Anki deck via AnkiConnect.\n*   **🔧 Model Customization:** Choose preferred LLMs and Image Generation models (via `config.yaml`).\n*   **🌐 Multi-Language Support:** Designed to work with a growing list of languages.\n*   **💻 Optional Web UI:** Includes a Next.js frontend for easy card generation and library browsing.\n*   **Gpu Offloading:** Automatically manages GPU memory to run larger models on systems with limited VRAM (experimental).\n*   **Gpu Quantization:** Supports 4-bit and 8-bit quantization for reduced memory usage (experimental).\n*   **❤️ Open Source:** Free to use, modify, and contribute to!\n\n## How it Works ⚙️\n\nmnemorai streamlines the mnemonic creation process:\n\n```mermaid\ngraph LR\n    A[User Input: Word \u0026 Language] --\u003e B(mnemorai Backend);\n    B --\u003e C{Translate \u0026 Transliterate};\n    C --\u003e D{Find Phonetic Keyword Match};\n    D --\u003e E{Generate Verbal Cue};\n    E --\u003e F{Generate Visual Cue };\n    F --\u003e G{Generate TTS Audio};\n    G --\u003e H[Output: Flashcard Data];\n    H --\u003e I(Save to Anki);\n```\n\n1.  **Input:** You provide a word and its language.\n2.  **Processing:** The backend translates the word, finds a phonetically similar keyword in English, generates a linking sentence (verbal cue) using an LLM, and creates an image based on that sentence.\n3.  **Output:** A complete flashcard package (word, translation, IPA, keyword, verbal cue, image, audio) is prepared.\n4.  **Anki Sync:** The flashcard is sent to your running Anki instance via AnkiConnect and added to your chosen deck.\n\n## Demo 🎬\n\nSee mnemorai in action!\n\nhttps://github.com/user-attachments/assets/89927ebb-91b2-4883-bd65-df8b3706852d\n\n## The Science Behind It 🔬\n\nmnemorai utilizes the **Keyword Mnemonic** technique, a scientifically validated method for vocabulary acquisition. It works by creating an acoustic link (a similar-sounding keyword in your native language) and an imagery link (a mental image connecting the keyword to the target word's meaning). This dual-coding approach enhances memory encoding and retrieval.\n\nOur implementation automates this process using AI, drawing inspiration from the methodologies presented in the [SmartPhone paper](https://arxiv.org/pdf/2305.10436.pdf).\n\n## System Requirements 🖥️\n\n**Operating System:**\n\nmnemorai is designed to run on **Linux** and **Windows**. It has been tested on Ubuntu 22.04 and Windows 10 and 11.\n\n**Hardware (Backend):**\n\nAn NVIDIA GPU is necessary for the backend to function optimally. The software can run on CPU (theoretically), but performance will be significantly slower and is not recommended.\n\n- **Minimum**:\n    - **RAM:** 16 GB\n    - **GPU**: NVIDIA GPU with at least 6 GB VRAM\n\n- **Recommended**:\n    - **RAM:** 32 GB or more\n    - **GPU**: NVIDIA GPU with 12 GB VRAM\n\n**Software:**\n\n*   Python 3.9 or newer.\n*   [Anki](https://apps.ankiweb.net/) (Desktop version) installed and running.\n*   [AnkiConnect Add-on](https://foosoft.net/projects/anki-connect/) installed in Anki.\n*   `pip` and `venv` (recommended for Python environment management).\n*   (Optional Frontend) Node.js and npm/yarn.\n\n## Installation 🛠️\nWe provide two installation methods: **Docker** and **Local Installation**. The local installation is recommended for most users, while Docker is useful for containerized environments.\n\n### Docker 🐋\n\nFor a containerized setup, refer to the Docker instructions: [backend/docker/README.md](backend/docker/README.md).\n\n### Local Installation\n\n1.  **Clone the Repository:**\n    ```bash\n    git clone https://github.com/StephanAkkerman/mnemorai.git\n    cd mnemorai\n    ```\n\n2.  **Set up Python Environment (Recommended):**\n    ```bash\n    python -m venv venv\n    source venv/bin/activate  # On Windows use `venv\\Scripts\\activate`\n    ```\n\n3.  **Install Backend Dependencies:**\n    *   Navigate to the backend directory and install the dependencies.\n    ```bash\n    cd backend\n    pip install .\n    ```\n\n4.  **Install GPU Dependencies (Highly Recommended):**\n    *   Ensure you have NVIDIA drivers and CUDA toolkit compatible with PyTorch installed. See [PyTorch installation guide](https://pytorch.org/get-started/locally/).\n    *   Install GPU-specific requirements:\n        ```bash\n        cd backend\n        pip install . --extra-index-url https://download.pytorch.org/whl/cu128\n        ```\n        \n5.  **Configure AnkiConnect:**\n    *   Open Anki, go to `Tools` -\u003e `Add-ons` -\u003e `AnkiConnect` -\u003e `Config`.\n    *   Restart Anki after changing the config.\n\n6.  **(Optional) Install Frontend Dependencies:**\n    ```bash\n    cd frontend\n    npm install\n    cd ..\n    ```\n\n7.  **Configuration:**\n    *   Copy `config.example.yaml` to `config.yaml`.\n    *   Review `config.yaml` and adjust model names, paths, or API keys if necessary.\n\n## Usage ▶️\n\n1.  **Start Anki:** Ensure Anki desktop application is running with AnkiConnect installed.\n\n2.  **Start the Backend API:**\n    ```bash\n    # Make sure your virtual environment is activated\n    # source venv/bin/activate\n    cd backend\n    python mnemorai/api/app.py --config path/to/your/config.yaml\n    ```\n    The API will typically be available at `http://localhost:8000`.\n\n3.  **Use the Frontend:**\n    *   **Option A: Run Locally (if installed):**\n        ```bash\n        cd frontend\n        npm run dev\n        ```\n        Access the web UI in your browser at `http://localhost:3000`.\n    *   **Option B: Use the Demo Site:**\n        Visit [https://demo.mnemorai.com](https://demo.mnemorai.com). This site will connect to **your locally running backend API** (`http://localhost:8000`). Ensure your backend is running first!\n\n4.  **Generate Cards:** Use the web interface (local or demo) to input words and languages, customize models if desired, and generate your mnemonic flashcards. They will be automatically saved to your selected Anki deck.\n\n## Citation ✍️\n\nIf you use mnemorai in your research or work, please cite it:\n\n```bibtex\n@misc{mnemorai,\n  author       = {Stephan Akkerman and Winston Lam and Tim Koornstra},\n  title        = {mnemorai: AI-Powered Mnemonic Flashcards for Language Learning},\n  year         = {2024},\n  publisher    = {GitHub},\n  journal      = {GitHub repository},\n  howpublished = {\\url{https://github.com/StephanAkkerman/mnemorai}}\n}\n```\n\nAnd consider citing the original paper that inspired this work:\n\n```bibtex\n@misc{lee2023smartphone,\n      title={SmartPhone: Exploring Keyword Mnemonic with Auto-generated Verbal and Visual Cues},\n      author={Jaewook Lee and Andrew Lan},\n      year={2023},\n      eprint={2305.10436},\n      archivePrefix={arXiv},\n      primaryClass={cs.CL}\n}\n```\n\n## Contributing 🤝\n\nContributions are welcome! Whether it's bug reports, feature requests, or code contributions, please feel free to open an issue or pull request.\n\nPlease read [CONTRIBUTING.MD](CONTRIBUTING.md) for guidelines.\n\n[![Contributors](https://contributors-img.firebaseapp.com/image?repo=StephanAkkerman/mnemorai)](https://github.com/StephanAkkerman/mnemorai/graphs/contributors)\n\n## License 📜\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n## Contact 💬\n\nJoin our [Discord Community](https://discord.gg/z56zRXtNR5) to discuss the project, ask questions, and connect with other users!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FStephanAkkerman%2Fmnemorai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FStephanAkkerman%2Fmnemorai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FStephanAkkerman%2Fmnemorai/lists"}