Phase 1: Sahel-Voice-Lab — The Memory Loop

New project pivot: self-learning voice assistant for Bambara/Fula
using 100% non-Meta tech stack.

New files:
- app_lab.py — Gradio UI: push-to-talk + last 5 words panel
- src/memory/memory_manager.py — persists vocabulary.jsonl to HF Hub
- src/llm/gemma_client.py — Gemma via HF Serverless Inference API
- data/vocabulary.jsonl — empty initial vocabulary store

Flow: audio → Whisper STT → Gemma (with vocabulary context) →
teaching intent → MemoryManager.add_word_pair() → Hub push
question intent → answer from vocabulary
conversation → natural reply

README.md updated: app_file changed to app_lab.py, stack documented.

Stack: openai/whisper-large-v3-turbo (STT), google/gemma-3-4b-it (LLM),
Waxal TTS (Phase 2), HF Dataset for memory.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

README.md

@@ -1,39 +1,50 @@
 ---
-title: Sahel-Agri Voice AI
-emoji: 🌾
-colorFrom: green
-colorTo: yellow
+title: Sahel-Voice-Lab
+emoji: 🌍
+colorFrom: blue
+colorTo: green
 sdk: gradio
 sdk_version: "5.25.0"
-app_file: app.py
+app_file: app_lab.py
 hardware: cpu-basic
 pinned: false
 license: mit
 tags:
-  - agriculture
   - bambara
   - fula
   - speech-recognition
-  - text-to-speech
+  - language-learning
   - west-africa
   - low-resource-nlp
+  - memory
 ---
 
-# 🌾 Sahel-Agri Voice AI
+# 🌍 Sahel-Voice-Lab — Internal Edition
 
-Two-way voice assistant for Malian and Guinean farmers. Speak in **Bambara** or **Fula** — get agricultural insights spoken back in your language.
+**Phase 1 · The Memory Loop**
 
-## Features
-- 🎙️ Voice input via microphone or file upload
-- 🌍 Bambara (bam) and Fula (ful) speech recognition via Whisper + LoRA adapters
-- 🔊 Native-language voice responses via Facebook MMS-TTS
-- 📊 Soil, weather, irrigation, and pest alerts from IoT sensors
-- 💾 Feedback saved to HuggingFace Dataset for continuous improvement
+A self-learning voice assistant for Bambara and Fula. Teach it words — it remembers them forever.
 
-## Languages supported
-| Language | STT | TTS |
-|----------|-----|-----|
-| Bambara (bam) | ✅ Whisper + LoRA | ✅ facebook/mms-tts-bam |
-| Fula (ful) | ✅ Whisper + LoRA | ✅ facebook/mms-tts-ful |
-| French (fr) | ✅ Whisper | ✅ facebook/mms-tts-fra |
-| English (en) | ✅ Whisper | ✅ facebook/mms-tts-eng |
+## Stack (100% non-Meta)
+| Component | Model |
+|-----------|-------|
+| STT | `openai/whisper-large-v3-turbo` |
+| LLM | `google/gemma-3-4b-it` (set `LLM_MODEL_ID` env var for Gemma 4) |
+| TTS | Waxal — Phase 2 |
+| Memory | HF Dataset `vocabulary.jsonl` |
+
+## How it works
+1. Press Push-to-Talk → speak in Bambara, Fula, French, or English
+2. Whisper transcribes your speech
+3. Gemma reads the vocabulary it has learned so far, then:
+   - **Teaching mode**: detects "X means Y" → saves the word pair to the Hub
+   - **Question mode**: answers using vocabulary as source of truth
+   - **Conversation mode**: replies naturally
+4. The last 5 learned words are always visible
+
+## Space secrets required
+| Key | Value |
+|-----|-------|
+| `HF_TOKEN` | Your HF write-access token |
+| `FEEDBACK_REPO_ID` | `ous-sow/sahel-agri-feedback` |
+| `LLM_MODEL_ID` | `google/gemma-3-4b-it` (or Gemma 4 model ID) |

app_lab.py

@@ -0,0 +1,409 @@
+"""
+Sahel-Voice-Lab — Internal Edition  (Phase 1: The Memory Loop)
+
+Stack (100% non-Meta):
+  STT  : openai/whisper-large-v3-turbo
+  LLM  : google/gemma-3-4b-it  (or LLM_MODEL_ID env var — update to Gemma 4)
+  TTS  : Phase 2 — Waxal TTS (not yet integrated)
+  Store: HF Dataset  ous-sow/sahel-agri-feedback  → vocabulary.jsonl
+
+Flow:
+  1. User presses Push-to-Talk → records audio
+  2. Whisper transcribes to text
+  3. MemoryManager injects current vocabulary into Gemma's system prompt
+  4. Gemma returns structured JSON:
+       teaching  → MemoryManager.add_word_pair() → push to Hub
+       question  → answer using vocabulary
+       conversation → natural reply
+  5. UI shows Gemma's reply + last 5 learned words
+"""
+from __future__ import annotations
+
+import os
+import sys
+import threading
+from pathlib import Path
+
+import gradio as gr
+
+ROOT = Path(__file__).parent
+sys.path.insert(0, str(ROOT))
+
+# ── Env ───────────────────────────────────────────────────────────────────────
+HF_TOKEN         = os.environ.get("HF_TOKEN")
+FEEDBACK_REPO_ID = os.environ.get("FEEDBACK_REPO_ID", "ous-sow/sahel-agri-feedback")
+WHISPER_MODEL_ID = os.environ.get("WHISPER_MODEL_ID", "openai/whisper-large-v3-turbo")
+LLM_MODEL_ID     = os.environ.get("LLM_MODEL_ID",     "google/gemma-3-4b-it")
+
+LANGUAGE_NAMES = {
+    "bam": "Bambara",
+    "ful": "Fula / Pular",
+    "fr":  "French",
+    "en":  "English",
+}
+
+# ── Singletons ────────────────────────────────────────────────────────────────
+from src.memory.memory_manager import MemoryManager
+from src.llm.gemma_client      import GemmaClient
+
+_memory  = MemoryManager(repo_id=FEEDBACK_REPO_ID, hf_token=HF_TOKEN)
+_gemma   = GemmaClient(model_id=LLM_MODEL_ID, hf_token=HF_TOKEN)
+
+# Whisper — loaded lazily in background
+_whisper_model     = None
+_whisper_processor = None
+_whisper_lock      = threading.Lock()
+_whisper_status    = "not loaded"
+
+
+# ── Whisper loading ───────────────────────────────────────────────────────────
+
+def _do_load_whisper() -> None:
+    global _whisper_model, _whisper_processor, _whisper_status
+    import torch
+    try:
+        from transformers.models.whisper import WhisperProcessor, WhisperForConditionalGeneration
+    except ImportError:
+        from transformers.models.whisper.processing_whisper import WhisperProcessor
+        from transformers.models.whisper.modeling_whisper  import WhisperForConditionalGeneration
+
+    _whisper_status = "loading…"
+    try:
+        _whisper_processor = WhisperProcessor.from_pretrained(
+            WHISPER_MODEL_ID, token=HF_TOKEN
+        )
+        _whisper_model = WhisperForConditionalGeneration.from_pretrained(
+            WHISPER_MODEL_ID, token=HF_TOKEN
+        )
+        _whisper_model.eval()
+        _whisper_status = f"ready ({WHISPER_MODEL_ID})"
+    except Exception as exc:
+        _whisper_status = f"error: {exc}"
+
+
+def _ensure_whisper() -> str:
+    global _whisper_status
+    with _whisper_lock:
+        if _whisper_model is None and "loading" not in _whisper_status:
+            _whisper_status = "loading…"
+            threading.Thread(target=_do_load_whisper, daemon=True).start()
+    return _whisper_status
+
+
+def _whisper_status_label() -> str:
+    s = _ensure_whisper()
+    if "ready"   in s: return f"🟢 STT {s}"
+    if "loading" in s: return f"🟡 STT {s}"
+    if "error"   in s: return f"🔴 STT {s}"
+    return f"⚪ STT {s}"
+
+
+def _transcribe(audio_path: str, language_hint: str) -> str:
+    """Run Whisper STT. Returns transcribed text."""
+    if _whisper_model is None:
+        return ""
+    import torch, librosa
+    audio_np, _ = librosa.load(audio_path, sr=16_000, mono=True)
+
+    with _whisper_lock:
+        inputs = _whisper_processor.feature_extractor(
+            audio_np, sampling_rate=16_000, return_tensors="pt"
+        )
+        input_features = inputs.input_features
+
+        # Whisper doesn't have Bambara / Fula tokens — let it auto-detect
+        if language_hint in ("bam", "ful"):
+            forced_ids = None
+        else:
+            try:
+                forced_ids = _whisper_processor.get_decoder_prompt_ids(
+                    language=language_hint, task="transcribe"
+                )
+            except Exception:
+                forced_ids = None
+
+        with torch.no_grad():
+            predicted_ids = _whisper_model.generate(
+                input_features,
+                forced_decoder_ids=forced_ids,
+                max_new_tokens=256,
+            )
+
+    return _whisper_processor.batch_decode(predicted_ids, skip_special_tokens=True)[0].strip()
+
+
+# ── Core pipeline ─────────────────────────────────────────────────────────────
+
+def process_audio(audio_path, language_label: str, history: list) -> tuple:
+    """
+    Full pipeline: audio → Whisper → Gemma → (optional) memory update.
+    Returns: (updated_history, last_5_words_md, status_text)
+    """
+    if audio_path is None:
+        return history, _render_recent_words(), "⚠️ No audio recorded."
+
+    lang_code = _label_to_code(language_label)
+
+    # 1. Transcribe
+    status = _ensure_whisper()
+    if _whisper_model is None:
+        return history, _render_recent_words(), f"⏳ {status} — wait a moment and try again."
+
+    transcript = _transcribe(audio_path, lang_code)
+    if not transcript:
+        return history, _render_recent_words(), "⚠️ Could not transcribe audio."
+
+    # 2. Ask Gemma (with vocabulary context)
+    vocab_ctx  = _memory.get_vocabulary_context()
+    llm_result = _gemma.chat(transcript, vocab_ctx)
+    intent     = llm_result.get("intent", "conversation")
+    response   = llm_result.get("response", "…")
+
+    # 3. If teaching intent → persist to memory
+    if intent == "teaching":
+        word     = llm_result.get("word", transcript)
+        lang     = llm_result.get("language", lang_code)
+        trans    = llm_result.get("translation", "")
+        trans_l  = llm_result.get("translation_language", "en")
+        if word and trans:
+            _memory.add_word_pair(
+                word=word,
+                language=lang,
+                translation=trans,
+                translation_language=trans_l,
+                source="user_taught",
+            )
+
+    # 4. Update chat history
+    history = history or []
+    history.append({
+        "role": "user",
+        "content": f"[{LANGUAGE_NAMES.get(lang_code, lang_code)}] {transcript}"
+    })
+    history.append({
+        "role": "assistant",
+        "content": response
+    })
+
+    status_msg = {
+        "teaching":     "✅ Word learned and saved!",
+        "question":     "💬 Answered from vocabulary.",
+        "conversation": "💬 Replied.",
+        "error":        "⚠️ LLM error.",
+    }.get(intent, "💬 Replied.")
+
+    return history, _render_recent_words(), status_msg
+
+
+def process_text(text: str, language_label: str, history: list) -> tuple:
+    """Same as process_audio but takes typed text (fallback path)."""
+    if not text.strip():
+        return history, _render_recent_words(), "⚠️ Please type something."
+
+    lang_code  = _label_to_code(language_label)
+    vocab_ctx  = _memory.get_vocabulary_context()
+    llm_result = _gemma.chat(text.strip(), vocab_ctx)
+    intent     = llm_result.get("intent", "conversation")
+    response   = llm_result.get("response", "…")
+
+    if intent == "teaching":
+        word    = llm_result.get("word", text)
+        lang    = llm_result.get("language", lang_code)
+        trans   = llm_result.get("translation", "")
+        trans_l = llm_result.get("translation_language", "en")
+        if word and trans:
+            _memory.add_word_pair(word, lang, trans, trans_l, source="user_taught")
+
+    history = history or []
+    history.append({"role": "user",      "content": text.strip()})
+    history.append({"role": "assistant", "content": response})
+
+    status_msg = {
+        "teaching":     "✅ Word learned and saved!",
+        "question":     "💬 Answered from vocabulary.",
+        "conversation": "💬 Replied.",
+        "error":        "⚠️ LLM error.",
+    }.get(intent, "💬 Replied.")
+
+    return history, _render_recent_words(), status_msg
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+LANGUAGE_CHOICES = ["Bambara (bam)", "Fula (ful)", "French (fr)", "English (en)"]
+
+def _label_to_code(label: str) -> str:
+    mapping = {
+        "Bambara (bam)": "bam",
+        "Fula (ful)":    "ful",
+        "French (fr)":   "fr",
+        "English (en)":  "en",
+    }
+    return mapping.get(label, "bam")
+
+
+def _render_recent_words() -> str:
+    recent = _memory.get_recent(5)
+    if not recent:
+        return "_No words learned yet. Start teaching me! Say something like: **'I ni ce means hello in Bambara'**_"
+    lines = ["### 📖 Last 5 words learned\n"]
+    for e in reversed(recent):
+        lang = LANGUAGE_NAMES.get(e.get("language", "?"), e.get("language", "?"))
+        word = e.get("word", "")
+        tr   = e.get("translation", "")
+        tr_l = e.get("translation_language", "")
+        lines.append(f"**{word}** `[{lang}]` → {tr} `({tr_l})`")
+    return "\n\n".join(lines)
+
+
+# ── UI ────────────────────────────────────────────────────────────────────────
+
+def build_ui() -> gr.Blocks:
+    with gr.Blocks(title="Sahel-Voice-Lab", theme=gr.themes.Soft()) as demo:
+
+        gr.Markdown(
+            "# 🌍 Sahel-Voice-Lab — Internal Edition\n"
+            "**Phase 1 · The Memory Loop**  \n"
+            "Teach me Bambara and Fula — I will remember every word you share."
+        )
+
+        with gr.Row():
+            # ── Left column: input ────────────────────────────────────────────
+            with gr.Column(scale=2):
+                status_box = gr.Textbox(
+                    value=_whisper_status_label(),
+                    label="Status",
+                    interactive=False,
+                    max_lines=1,
+                )
+                status_timer = gr.Timer(value=3)
+                status_timer.tick(fn=_whisper_status_label, outputs=status_box)
+
+                language_dd = gr.Dropdown(
+                    choices=LANGUAGE_CHOICES,
+                    value="Bambara (bam)",
+                    label="Language you are speaking",
+                )
+
+                with gr.Tab("🎙️ Push-to-Talk"):
+                    audio_input = gr.Audio(
+                        sources=["microphone"],
+                        type="filepath",
+                        label="Hold to record — release to send",
+                    )
+                    talk_btn = gr.Button("▶ Send Recording", variant="primary", size="lg")
+
+                with gr.Tab("⌨️ Type instead"):
+                    text_input = gr.Textbox(
+                        lines=3,
+                        placeholder=(
+                            "Type a message or teach me a word.\n"
+                            "Examples:\n"
+                            "  'I ni ce means hello in Bambara'\n"
+                            "  'How do you say goodbye in Fula?'"
+                        ),
+                        label="Message",
+                    )
+                    text_btn = gr.Button("▶ Send", variant="primary")
+
+                action_status = gr.Textbox(
+                    label="Last action", interactive=False, max_lines=1
+                )
+
+                gr.Markdown(
+                    "**Teaching tips:**\n"
+                    "- Say or type: *'I ni ce means hello in Bambara'*\n"
+                    "- Or: *'Jam waali veut dire bonjour en Fula'*\n"
+                    "- Or: *'How do you say 'rain' in Bambara?'*\n\n"
+                    "Every new word is saved to the Hub automatically."
+                )
+
+            # ── Right column: memory + chat ───────────────────────────────────
+            with gr.Column(scale=3):
+                recent_words = gr.Markdown(value=_render_recent_words())
+
+                gr.Markdown("---")
+
+                chatbot = gr.Chatbot(
+                    label="Conversation",
+                    height=420,
+                    type="messages",
+                    bubble_full_width=False,
+                )
+
+                clear_btn = gr.Button("🗑️ Clear conversation", size="sm", variant="secondary")
+
+        # ── Wiring ────────────────────────────────────────────────────────────
+        history_state = gr.State([])
+
+        talk_btn.click(
+            fn=process_audio,
+            inputs=[audio_input, language_dd, history_state],
+            outputs=[history_state, recent_words, action_status],
+        ).then(
+            fn=lambda h: h,
+            inputs=[history_state],
+            outputs=[chatbot],
+        )
+
+        text_btn.click(
+            fn=process_text,
+            inputs=[text_input, language_dd, history_state],
+            outputs=[history_state, recent_words, action_status],
+        ).then(
+            fn=lambda h: (h, ""),
+            inputs=[history_state],
+            outputs=[chatbot, text_input],
+        )
+
+        text_input.submit(
+            fn=process_text,
+            inputs=[text_input, language_dd, history_state],
+            outputs=[history_state, recent_words, action_status],
+        ).then(
+            fn=lambda h: (h, ""),
+            inputs=[history_state],
+            outputs=[chatbot, text_input],
+        )
+
+        clear_btn.click(
+            fn=lambda: ([], _render_recent_words(), ""),
+            outputs=[history_state, recent_words, action_status],
+        ).then(fn=lambda: [], outputs=[chatbot])
+
+    return demo
+
+
+# ── Entry point ───────────────────────────────────────────────────────────────
+
+# Load vocabulary at startup (background — non-blocking for the UI)
+threading.Thread(target=_memory.load, daemon=True).start()
+# Begin loading Whisper immediately
+_ensure_whisper()
+
+if __name__ == "__main__":
+    from dotenv import load_dotenv
+    load_dotenv()
+    HF_TOKEN         = os.environ.get("HF_TOKEN")
+    FEEDBACK_REPO_ID = os.environ.get("FEEDBACK_REPO_ID", "ous-sow/sahel-agri-feedback")
+    WHISPER_MODEL_ID = os.environ.get("WHISPER_MODEL_ID", "openai/whisper-large-v3-turbo")
+    LLM_MODEL_ID     = os.environ.get("LLM_MODEL_ID",     "google/gemma-3-4b-it")
+
+    _memory._hf_token = HF_TOKEN
+    _memory._repo_id  = FEEDBACK_REPO_ID
+    _gemma._hf_token  = HF_TOKEN
+
+    print(f"STT model : {WHISPER_MODEL_ID}")
+    print(f"LLM model : {LLM_MODEL_ID}")
+    print(f"Store     : {FEEDBACK_REPO_ID}")
+    print(f"HF_TOKEN  : {'set' if HF_TOKEN else 'NOT SET — Hub push disabled'}")
+    print()
+
+    demo = build_ui()
+    demo.launch(
+        server_port=7860,
+        inbrowser=False,
+        share=False,
+        show_api=False,
+        ssr_mode=False,
+    )

src/llm/gemma_client.py

@@ -0,0 +1,135 @@
+"""
+GemmaClient — wraps the HuggingFace Serverless Inference API for Gemma.
+
+The system prompt implements the 'adult-child' logic:
+  - The LLM is a child learning Bambara/Fula from the user (adult/teacher)
+  - vocabulary.jsonl is its primary memory / source of truth
+  - It detects TEACHING intent and returns structured JSON so MemoryManager
+    can persist the new word
+  - It answers QUESTIONS using the vocabulary it has learned
+
+Model: configurable via LLM_MODEL_ID env var.
+Default: google/gemma-3-4b-it  (update to Gemma 4 when available on HF Hub)
+"""
+from __future__ import annotations
+
+import json
+import logging
+import re
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+SYSTEM_PROMPT_TEMPLATE = """\
+You are an AI language assistant learning Bambara and Fula — two West African languages. \
+You behave like an eager child learner: you absorb every word the user teaches you, \
+and you use what you have already learned to answer questions.
+
+YOUR CURRENT VOCABULARY (your only source of truth):
+{vocabulary_context}
+
+RESPONSE RULES — always reply with a single valid JSON object, nothing else:
+
+1. If the user is TEACHING you a word or phrase (e.g. "I ni ce means hello" / \
+"X se dit Y en bambara" / "X veut dire Y"), reply:
+{{
+  "intent": "teaching",
+  "word": "<the word/phrase being taught>",
+  "language": "<bam | ful | fr | en>",
+  "translation": "<the translation given>",
+  "translation_language": "<bam | ful | fr | en>",
+  "response": "<warm acknowledgment in the same language the user used, \
+1-2 sentences, use the word in a sentence if possible>"
+}}
+
+2. If the user is ASKING a question you can answer using the vocabulary:
+{{
+  "intent": "question",
+  "response": "<answer using vocabulary — be honest if you don't know>"
+}}
+
+3. For general CONVERSATION or GREETING:
+{{
+  "intent": "conversation",
+  "response": "<natural, friendly reply — 1-3 sentences>"
+}}
+
+Always be warm, encouraging, and curious. If unsure of intent, choose "conversation".\
+"""
+
+
+class GemmaClient:
+    """Calls Gemma via HF Serverless Inference API."""
+
+    def __init__(
+        self,
+        model_id: str = "google/gemma-3-4b-it",
+        hf_token: Optional[str] = None,
+    ) -> None:
+        self.model_id  = model_id
+        self.hf_token  = hf_token
+        self._client   = None  # lazy init
+
+    def _get_client(self):
+        if self._client is None:
+            from huggingface_hub import InferenceClient
+            self._client = InferenceClient(token=self.hf_token)
+        return self._client
+
+    def chat(self, user_text: str, vocabulary_context: str) -> dict:
+        """
+        Send a message and get a structured response back.
+        Returns a dict with at minimum: intent, response.
+        On any error returns: {"intent": "error", "response": <error message>}
+        """
+        system_prompt = SYSTEM_PROMPT_TEMPLATE.format(
+            vocabulary_context=vocabulary_context or "(no vocabulary yet)"
+        )
+
+        try:
+            client = self._get_client()
+            completion = client.chat_completion(
+                model=self.model_id,
+                messages=[
+                    {"role": "system",    "content": system_prompt},
+                    {"role": "user",      "content": user_text},
+                ],
+                max_tokens=512,
+                temperature=0.4,
+            )
+            raw = completion.choices[0].message.content.strip()
+            logger.debug("Gemma raw response: %s", raw[:200])
+            return self._parse(raw)
+
+        except Exception as exc:
+            logger.error("GemmaClient error: %s", exc)
+            return {
+                "intent": "error",
+                "response": f"(LLM unavailable: {exc})",
+            }
+
+    # ── Parsing ───────────────────────────────────────────────────────────────
+
+    def _parse(self, raw: str) -> dict:
+        """Extract JSON from the model output — handles markdown code fences."""
+        # Strip markdown code fences if present
+        text = raw.strip()
+        fence_match = re.search(r"```(?:json)?\s*(\{.*?\})\s*```", text, re.DOTALL)
+        if fence_match:
+            text = fence_match.group(1)
+        else:
+            # Find first { ... } block
+            brace_match = re.search(r"\{.*\}", text, re.DOTALL)
+            if brace_match:
+                text = brace_match.group(0)
+
+        try:
+            data = json.loads(text)
+            if "intent" not in data:
+                data["intent"] = "conversation"
+            if "response" not in data:
+                data["response"] = raw  # fall back to raw text
+            return data
+        except json.JSONDecodeError:
+            # Return the raw text as a conversation response
+            return {"intent": "conversation", "response": raw}

src/memory/memory_manager.py

@@ -0,0 +1,158 @@
+"""
+MemoryManager — persists the vocabulary the assistant has learned.
+
+Storage:
+  - Local file  : data/vocabulary.jsonl  (fast read/write during session)
+  - HF Hub      : ous-sow/sahel-agri-feedback → vocabulary.jsonl  (survives restarts)
+
+Each line in vocabulary.jsonl is a JSON object:
+  {
+    "timestamp":           "2026-04-07T12:00:00Z",
+    "word":                "I ni ce",
+    "language":            "bam",
+    "translation":         "Hello / Good day",
+    "translation_language":"en",
+    "source":              "user_taught"
+  }
+"""
+from __future__ import annotations
+
+import json
+import logging
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+LOCAL_PATH = Path(__file__).parent.parent.parent / "data" / "vocabulary.jsonl"
+HUB_FILENAME = "vocabulary.jsonl"
+
+
+class MemoryManager:
+    """Thread-safe vocabulary store backed by HF Hub."""
+
+    def __init__(self, repo_id: str, hf_token: Optional[str] = None) -> None:
+        self.repo_id  = repo_id
+        self.hf_token = hf_token
+        self._lock    = threading.Lock()
+        self._entries: list[dict] = []
+        LOCAL_PATH.parent.mkdir(parents=True, exist_ok=True)
+
+    # ── Load ──────────────────────────────────────────────────────────────────
+
+    def load(self) -> None:
+        """Pull vocabulary.jsonl from HF Hub then cache locally. Non-fatal on failure."""
+        if self.hf_token and self.repo_id:
+            try:
+                from huggingface_hub import hf_hub_download
+                local = hf_hub_download(
+                    repo_id=self.repo_id,
+                    filename=HUB_FILENAME,
+                    repo_type="dataset",
+                    token=self.hf_token,
+                    force_download=True,
+                )
+                import shutil
+                shutil.copy2(local, LOCAL_PATH)
+                logger.info("MemoryManager: loaded vocabulary from Hub (%s)", self.repo_id)
+            except Exception as exc:
+                logger.warning("MemoryManager: could not load from Hub (%s) — using local", exc)
+
+        # Read local file (may have been just downloaded, or pre-existing from last session)
+        entries: list[dict] = []
+        if LOCAL_PATH.exists():
+            with open(LOCAL_PATH, encoding="utf-8") as f:
+                for line in f:
+                    line = line.strip()
+                    if line:
+                        try:
+                            entries.append(json.loads(line))
+                        except json.JSONDecodeError:
+                            pass
+
+        with self._lock:
+            self._entries = entries
+
+        logger.info("MemoryManager: %d vocabulary entries loaded", len(entries))
+
+    # ── Read ──────────────────────────────────────────────────────────────────
+
+    def get_recent(self, n: int = 5) -> list[dict]:
+        with self._lock:
+            return list(self._entries[-n:])
+
+    def get_all(self) -> list[dict]:
+        with self._lock:
+            return list(self._entries)
+
+    def count(self) -> int:
+        with self._lock:
+            return len(self._entries)
+
+    def get_vocabulary_context(self, max_entries: int = 150) -> str:
+        """Format vocabulary as a compact string for the LLM system prompt."""
+        with self._lock:
+            recent = self._entries[-max_entries:]
+        if not recent:
+            return "(no vocabulary learned yet)"
+        lines = []
+        for e in recent:
+            lang = e.get("language", "?")
+            word = e.get("word", "")
+            tr   = e.get("translation", "")
+            tr_l = e.get("translation_language", "en")
+            lines.append(f"  [{lang}] {word} = {tr} ({tr_l})")
+        return "\n".join(lines)
+
+    # ── Write ─────────────────────────────────────────────────────────────────
+
+    def add_word_pair(
+        self,
+        word: str,
+        language: str,
+        translation: str,
+        translation_language: str = "en",
+        source: str = "user_taught",
+    ) -> dict:
+        """
+        Append a word pair to local JSONL and push to HF Hub.
+        Returns the new entry dict.
+        """
+        entry = {
+            "timestamp":           datetime.now(timezone.utc).isoformat(),
+            "word":                word.strip(),
+            "language":            language,
+            "translation":         translation.strip(),
+            "translation_language": translation_language,
+            "source":              source,
+        }
+
+        with self._lock:
+            self._entries.append(entry)
+            with open(LOCAL_PATH, "a", encoding="utf-8") as f:
+                f.write(json.dumps(entry, ensure_ascii=False) + "\n")
+
+        # Push to Hub in background so UI is not blocked
+        threading.Thread(target=self._push_to_hub, daemon=True).start()
+
+        logger.info("MemoryManager: added [%s] %s = %s", language, word, translation)
+        return entry
+
+    def _push_to_hub(self) -> None:
+        """Upload the full vocabulary.jsonl to HF Hub."""
+        if not (self.hf_token and self.repo_id):
+            return
+        try:
+            from huggingface_hub import HfApi
+            api = HfApi(token=self.hf_token)
+            api.upload_file(
+                path_or_fileobj=str(LOCAL_PATH),
+                path_in_repo=HUB_FILENAME,
+                repo_id=self.repo_id,
+                repo_type="dataset",
+            )
+            logger.info("MemoryManager: pushed vocabulary to Hub")
+        except Exception as exc:
+            logger.warning("MemoryManager: Hub push failed: %s", exc)