feat: OpenRouter as primary LLM with Mem0/Graphiti intelligence layer

MAJOR REFACTOR: Complete LLM provider architecture overhaul with knowledge graph
and memory system integration. User-scoped intelligence for multi-tenant safety.

### Backend Changes:
- llm_service: Rewrote with OpenRouter (pony-alpha) as primary provider
* Multi-tier fallback: OpenRouter pony-alpha → solar-pro-3:free → Gemini → Ollama
* Full streaming support with in-band model fallback
* Enhanced system prompt with source attribution rules for citations

- assistant_service: Integrated RAG + Memory (Mem0) + Knowledge Graph (Graphiti)
* Structured context gathering returns source metadata for citations
* Citation extraction from all three intelligence layers
* Updated docstring: "OpenRouter primary → Gemini → Ollama last resort"

- graph_service: Major refactor with user-scoping for multi-tenancy
* Added _user_node_label() and _is_user_scoped_result() for tenant isolation
* New methods: add_user_episode(), add_user_facts(), search_user()
* Groq support as alternative to Ollama for LLM operations
* Cross-encoder and embedder initialization for Graphiti

- memory_service: Groq rate-limit mitigation and exponential backoff
* New _GroqThrottle class enforces minimum interval between calls
* Configurable retry logic with jitter for 429 handling
* Batch add support for report sync operations
* Config candidates system with Groq/Ollama fallback permutations

- rag_service: Structured context with source metadata
* New get_user_context_structured() returns {"text": "...", "sources": [...]}
* Each source includes type, filename, report_id, and excerpt for citations

- document_processing: Updated to use new user-scoped graph API
* Syncs only abnormal observations to knowledge graph (prevents bloat)
* Batch memory sync to avoid Groq TPM exhaustion
* Both services called asynchronously to avoid request blocking

- enhanced_report_service: Background sync task for Memory/Graph/RAG
* New _sync_to_memory_and_graph() handles post-processing
* Syncs to ChromaDB (RAG), Neo4j (abnormal findings), Mem0 (summaries)
* Non-blocking async task spawned after report processing

- grok_recommendation_service: Updated graph search to use search_user()

### Configuration:
- settings.py: Added OpenRouter settings (key, base URL, models, timeout)
* Fallback model to upstage/solar-pro-3:free
* Mem0 rate-limit tuning params (MEM0_CALL_INTERVAL_SECONDS, retries, backoff)
* Groq support for Mem0 and Graphiti
* Marked Ollama as "LAST RESORT fallback"

- docker-compose.yml:
* Added 5 OPENROUTER_* env vars (API_KEY, BASE_URL, MODEL, FALLBACK, TIMEOUT)
* Added 7 MEM0/Graphiti rate-limit and config env vars
* Neo4j performance tuning (heap/pagecache sizing)
* Separate mem0_chroma volume to prevent ChromaDB singleton conflict

- requirements.txt:
* Added openai>=1.0.0 (used as OpenRouter SDK)
* Constrained transformers <5.0.0 (5.x breaks sentence-transformers paths)
* Added graphiti-core (core version, not extras that pull legacy deps)
* Added langchain-neo4j and rank-bm25 for Mem0 graph backend

### Frontend:
- HealthGraph.tsx:
* Added "Sync Profile Data" button to force user-scoped graph update
* Added AI-powered insights panel (temporal, relationships, contradictions)
* Normalized node IDs for consistent reference

- Features.tsx:
* Profile sync overlay with animated step indicators
* Shows progress: "Analysing profile" → "Syncing to Memory" → "Building Graph"
* Forces child components (MemoryDashboard, HealthGraph) to remount and fetch fresh data
* Auto-dismiss after 2.2s on success, 3.5s on error

- DashboardNavbar.tsx: Added Features route to nav and user dropdown

- ProfileSuccessScreen.tsx: Updated redirect to /features with sync state flag

- Styling:
* HealthGraph.css: New sync button and insights panel styles
* Features.css: Profile sync overlay with step counters and animations

### Schemas:
- schemas_memory.py: Added InsightType enum and Insight{Request,Response} models

### Tests:
- Updated test_assistant_*.py, test_graph_service.py, test_routes_*.py
* Changed graph_service.search() → search_user()
* Changed graph_service.add_episode() → add_user_episode()
* Fixed mock assertions for new user-scoped signatures

### Key Behavioral Changes:
1. **Provider Chain (Priority):**
- OpenRouter pony-alpha (primary, 200K context, free)
- OpenRouter solar-pro-3:free (fallback, 128K context, free, retiring 2 March 2026)
- Gemini Flash (Google fallback)
- Ollama MedGemma (local last resort)

2. **User-Scoped Queries:**
- All graph and memory queries now filtered by user_id
- Tenant isolation prevents cross-user data leakage
- Graph facts and memories are user-specific

3. **Citation Support:**
- Chat responses include structured citations with sources
- LLM prompted to attribute information to reports/memory/graph
- Frontend can display: "[Source: Lab Results 2024]"

4. **Rate-Limit Protection:**
- Groq calls throttled to 3.0s minimum interval
- Exponential backoff + jitter on 429 errors
- Batch operations to reduce API call volume

5. **Profile Sync Flow:**
- User completes health profile questionnaire
- Success screen redirects to /features
- Sync overlay triggers async profile→memory→graph sync
- Components remount to display fresh data

### Dependencies:
- Must set OPENROUTER_API_KEY in .env (user responsibility)
- OpenRouter account required (free tier for pony-alpha, solar-pro-3)
- Groq API key optional (auto-selects if available, falls back to Ollama)
- Solar-pro-3:free retiring 2 March 2026 (plan replacement)

### BREAKING CHANGES:
- graph_service.search() is now search_user(user_id, query) — requires user_id
- graph_service.add_episode() is now add_user_episode(user_id, content) — must scope
- RAG context is now structured dict {text, sources} instead of plain string
- Mem0 config candidates system replaces hardcoded single config

### Testing:
`docker compose up --build` and:
- POST /api/assistant/chat with test message
- WebSocket /ws for streaming responses with citations
- GET /api/graph/insights?insight_type=temporal for AI analysis
- Verify citations in Response, users scoped in memory/graph

.env.example

@@ -43,21 +43,33 @@ FRONTEND_ORIGIN=http://localhost:5173
 # =============================================================================
 # SECTION 3: AI/LLM PROVIDERS [AT LEAST ONE REQUIRED]
 # =============================================================================
-# Choose at least ONE provider for AI responses:
-# Primary: GROK_API_KEY (recommended - most medical-focused)
-# Fallback: GEMINI_API_KEY (free tier available)
-# Alternative: OPENAI_API_KEY (premium)
-# Local: OLLAMA_BASE_URL (self-hosted)
-
-# ---- GROK API (xAI) - RECOMMENDED ----
-# Get from: https://console.x.ai/
-# Free tier: 1M tokens/month available
+# Provider priority for the chat assistant:
+#   1. OpenRouter (pony-alpha)               - PRIMARY
+#   2. OpenRouter (solar-pro-3:free)         - FREE FALLBACK
+#   3. Gemini (gemini-flash-latest)          - Google fallback
+#   4. Ollama (MedGemma GGUF)               - Local last resort
+#
+# Set OPENROUTER_API_KEY to enable the primary chain.
+# Gemini & Ollama act as fallbacks if OpenRouter is unavailable.
+
+# ---- OPENROUTER - PRIMARY [RECOMMENDED] ----
+# Get from: https://openrouter.ai/settings/keys
+# Provides access to hundreds of models via a single endpoint.
+# Models: openrouter/pony-alpha (primary), upstage/solar-pro-3:free (fallback)
+OPENROUTER_API_KEY=
+OPENROUTER_MODEL=openrouter/pony-alpha
+OPENROUTER_FALLBACK_MODEL=upstage/solar-pro-3:free
+
+# ---- GROQ API ----
+# Used for Mem0 memory layer, Graphiti knowledge graph, and extraction pipeline.
+# Get from: https://console.groq.com/
+GROQ_API_KEY=
 GROK_API_KEY=
 
 # ---- GOOGLE GEMINI - FALLBACK ----
 # Get from: https://aistudio.google.com/apikey
 # Free tier: 15 requests/min, 1M tokens/day
-# Enable as fallback if Grok not available
+# Acts as fallback if OpenRouter is not available
 USE_GEMINI_FALLBACK=true
 GEMINI_API_KEY=
 
@@ -65,9 +77,10 @@ GEMINI_API_KEY=
 # Get from: https://platform.openai.com/api-keys
 OPENAI_API_KEY=
 
-# ---- OLLAMA - LOCAL/SELF-HOSTED ----
+# ---- OLLAMA - LOCAL/SELF-HOSTED (LAST RESORT) ----
 # For Docker: Use host.docker.internal:11434
 # For Linux: Update extra_hosts in docker-compose.yml
+# Ollama is now the LAST fallback in the provider chain.
 OLLAMA_BASE_URL=http://host.docker.internal:11434
 OLLAMA_MODEL=hf.co/unsloth/medgemma-4b-it-GGUF:Q6_K_XL
 
@@ -100,6 +113,10 @@ NEO4J_URI=bolt://neo4j:7687
 NEO4J_USER=neo4j
 NEO4J_PASSWORD=changeme
 MEM0_COLLECTION=user_memories
+MEM0_EMBED_MODEL=nomic-embed-text
+MEM0_GROQ_MODEL=llama-3.1-8b-instant
+MEM0_PREFER_GROQ=true
+GRAPHITI_GROQ_MODEL=moonshotai/kimi-k2-instruct-0905
 GRAPHITI_DATABASE=neo4j
 
 # ---- GOOGLE PLACES API (Pharmacy Locator) ----

backend/.env.example

@@ -39,22 +39,30 @@ FRONTEND_ORIGIN=http://localhost:5173
 # =============================================================================
 # SECTION 2: AI/LLM PROVIDERS [ONE REQUIRED]
 # =============================================================================
-# Choose at least ONE LLM provider:
-# - Grok API (xAI) - RECOMMENDED, most medical-focused
-# - Google Gemini - FREE tier available, good fallback
-# - OpenAI - Premium option
-# - Ollama - Local/self-hosted option
-
-# ---- GROK API (xAI) - PRIMARY [RECOMMENDED] ----
-# Get from: https://console.x.ai/
-# Free tier available with 1M tokens/month
+# Provider priority for the chat assistant:
+#   1. OpenRouter (pony-alpha)               - PRIMARY
+#   2. OpenRouter (solar-pro-3:free)         - FREE FALLBACK
+#   3. Gemini (gemini-flash-latest)          - Google fallback
+#   4. Ollama (MedGemma GGUF)               - Local last resort
+
+# ---- OPENROUTER - PRIMARY [RECOMMENDED] ----
+# Get from: https://openrouter.ai/settings/keys
+# Provides access to hundreds of models via a single endpoint.
+OPENROUTER_API_KEY=sk-or-v1-...your_openrouter_key_here
+OPENROUTER_MODEL=openrouter/pony-alpha
+OPENROUTER_FALLBACK_MODEL=upstage/solar-pro-3:free
+
+# ---- GROQ API ----
+# Used by Mem0 memory layer, Graphiti knowledge graph, and extraction pipeline.
+# Get from: https://console.groq.com/
+GROQ_API_KEY=gsk_your_groq_api_key_here
 GROK_API_KEY=gsk_your_grok_api_key_here
 GROK_MODEL=grok-beta
 
 # ---- GOOGLE GEMINI - FALLBACK ----
 # Get from: https://aistudio.google.com/apikey
 # Free tier: 15 requests/min, 1M tokens/day
-# Supported free models: gemini-flash-latest, gemini-1.5-flash-8b
+# Acts as fallback if OpenRouter is not available
 USE_GEMINI_FALLBACK=true
 GEMINI_API_KEY=AIzaSy...your_gemini_key_here
 
@@ -65,7 +73,8 @@ OPENAI_API_KEY=sk_...your_openai_key_here
 OPENAI_API_BASE=https://api.openai.com/v1
 OPENAI_MODEL=gpt-4o-mini
 
-# ---- OLLAMA - LOCAL/SELF-HOSTED ----
+# ---- OLLAMA - LOCAL/SELF-HOSTED (LAST RESORT) ----
+# Ollama is now the LAST fallback in the provider chain.
 # Run local: ollama pull medgemma
 # For Docker: Use host.docker.internal:11434
 OLLAMA_BASE_URL=http://host.docker.internal:11434
@@ -165,6 +174,10 @@ NEO4J_PASSWORD=changeme
 
 # Memory and Graph Settings
 MEM0_COLLECTION=user_memories
+MEM0_EMBED_MODEL=nomic-embed-text
+MEM0_GROQ_MODEL=llama-3.1-8b-instant
+MEM0_PREFER_GROQ=true
+GRAPHITI_GROQ_MODEL=moonshotai/kimi-k2-instruct-0905
 GRAPHITI_DATABASE=neo4j
 
 # =============================================================================

backend/alembic/versions/8f1b6c345678_add_profile_completion_columns.py

@@ -20,11 +20,11 @@ depends_on: Union[str, Sequence[str], None] = None
 
 def upgrade() -> None:
     # Add is_completed and completed_at columns to user_profiles
-    op.add_column('user_profiles', sa.Column('is_completed', sa.Boolean(), nullable=True, default=False))
+    op.add_column('user_profiles', sa.Column('is_completed', sa.Boolean(), nullable=False, server_default=sa.false()))
     op.add_column('user_profiles', sa.Column('completed_at', sa.DateTime(), nullable=True))
-    
-    # Set default value for existing rows
-    op.execute("UPDATE user_profiles SET is_completed = false WHERE is_completed IS NULL")
+
+    # Keep the table aligned with ORM behavior (application sets value explicitly).
+    op.alter_column('user_profiles', 'is_completed', server_default=None)
 
 
 def downgrade() -> None:

backend/app/core/audit.py

@@ -9,6 +9,7 @@ Logs are structured for easy parsing and compliance reporting.
 import json
 import logging
 import os
+import tempfile
 from datetime import datetime
 from typing import Optional, Dict, Any, Union
 from uuid import UUID
@@ -99,7 +100,7 @@ class AuditLogger:
         # Prevent duplicate handlers
         if not self._audit_logger.handlers:
             # JSON file handler for compliance
-            audit_file = os.path.join(log_dir, "hipaa_audit.jsonl")
+            audit_file = os.path.join(self.log_dir, "hipaa_audit.jsonl")
             file_handler = logging.FileHandler(audit_file)
             file_handler.setFormatter(logging.Formatter("%(message)s"))
             self._audit_logger.addHandler(file_handler)
@@ -113,10 +114,18 @@ class AuditLogger:
     
     def _ensure_log_dir(self):
         """Create log directory if it doesn't exist"""
-        try:
-            os.makedirs(self.log_dir, exist_ok=True)
-        except Exception as e:
-            logging.warning(f"Could not create audit log directory: {e}")
+        candidate_dirs = [
+            self.log_dir,
+            os.path.join(tempfile.gettempdir(), "lumea-audit"),
+        ]
+
+        for directory in candidate_dirs:
+            try:
+                os.makedirs(directory, exist_ok=True)
+                self.log_dir = directory
+                return
+            except Exception as e:
+                logging.warning(f"Could not create audit log directory '{directory}': {e}")
     
     def _serialize_id(self, value: Any) -> Optional[str]:
         """Convert UUID or other ID types to string"""

backend/app/core/rate_limit.py

@@ -8,6 +8,7 @@ Uses in-memory storage by default. For production, configure Redis backend.
 """
 import time
 import logging
+import os
 from typing import Callable, Optional, Dict, Tuple
 from collections import defaultdict
 from functools import wraps
@@ -106,20 +107,35 @@ class InMemoryRateLimiter:
 rate_limiter = InMemoryRateLimiter()
 
 
+def _env_int(name: str, default: int) -> int:
+    """Read integer env var with safe fallback."""
+    raw = os.getenv(name)
+    if raw is None:
+        return default
+    try:
+        return int(raw)
+    except (TypeError, ValueError):
+        logger.warning("Invalid %s=%r; using default=%s", name, raw, default)
+        return default
+
+
 # Rate limit configurations for different endpoints
 RATE_LIMITS = {
     # Auth endpoints - strict limits to prevent brute force
-    "login": (5, 60),       # 5 attempts per minute
-    "signup": (3, 60),      # 3 signups per minute per IP
-    "password_reset": (3, 300),  # 3 reset requests per 5 minutes
+    "login": (_env_int("RATE_LIMIT_LOGIN", 5), 60),       # 5 attempts per minute
+    "signup": (_env_int("RATE_LIMIT_SIGNUP", 3), 60),     # 3 signups per minute per IP
+    "password_reset": (_env_int("RATE_LIMIT_PASSWORD_RESET", 3), 300),  # 3 reset requests per 5 minutes
     
     # API endpoints - moderate limits
-    "api_default": (100, 60),    # 100 requests per minute
-    "upload": (10, 60),          # 10 uploads per minute
-    "ai_summary": (20, 60),      # 20 AI requests per minute
+    "api_default": (_env_int("RATE_LIMIT_API_DEFAULT", 240), 60),     # 240 requests per minute
+    "upload": (_env_int("RATE_LIMIT_UPLOAD", 10), 60),                # 10 uploads per minute
+    "ai_summary": (_env_int("RATE_LIMIT_AI_SUMMARY", 20), 60),        # 20 AI requests per minute
+    "dashboard_read": (_env_int("RATE_LIMIT_DASHBOARD_READ", 240), 60),  # 240 reads/min for dashboard polling
+    "memory_graph": (_env_int("RATE_LIMIT_MEMORY_GRAPH", 180), 60),      # 180 reads/min for memory/graph UIs
+    "profile_sync": (_env_int("RATE_LIMIT_PROFILE_SYNC", 40), 60),       # 40 sync requests/min
     
     # Sensitive data endpoints - stricter
-    "phi_access": (50, 60),      # 50 PHI accesses per minute
+    "phi_access": (_env_int("RATE_LIMIT_PHI_ACCESS", 50), 60),        # 50 PHI accesses per minute
 }
 
 
@@ -208,9 +224,21 @@ class RateLimitMiddleware(BaseHTTPMiddleware):
         "/api/reports/upload": "upload",
         "/api/documents/upload": "upload",
         "/api/ai/": "ai_summary",
+        "/api/profile/sync-to-memory": "profile_sync",
+        "/api/memory/": "memory_graph",
+        "/api/graph/": "memory_graph",
+        "/api/me/bootstrap": "dashboard_read",
+        "/api/dashboard/": "dashboard_read",
+        "/api/recommendations": "dashboard_read",
+        "/api/health-index": "dashboard_read",
+        "/api/reports": "dashboard_read",
     }
     
     async def dispatch(self, request: Request, call_next):
+        # CORS preflight and HEAD requests should not consume API quota.
+        if request.method in {"OPTIONS", "HEAD"}:
+            return await call_next(request)
+
         client_ip = get_client_ip(request)
         path = request.url.path
         

backend/app/routes/graph.py

@@ -5,14 +5,12 @@ Exposes Neo4j/Graphiti knowledge graph to frontend for viewing health relationsh
 and facts.
 """
 import logging
+import re
 from fastapi import APIRouter, Depends, Query
-from sqlalchemy.ext.asyncio import AsyncSession
-from typing import List
-
-from app.db import get_db
 from app.models import User
 from app.security import get_current_user
 from app.services.graph_service import get_graph_service
+from app.services.llm_service import LLMService
 from app.schemas_memory import (
     GraphDataResponse,
     GraphNode,
@@ -20,6 +18,9 @@ from app.schemas_memory import (
     GraphFactsResponse,
     GraphSearchRequest,
     GraphSearchResponse,
+    InsightType,
+    InsightRequest,
+    InsightResponse,
 )
 
 logger = logging.getLogger(__name__)
@@ -27,6 +28,15 @@ logger = logging.getLogger(__name__)
 router = APIRouter(prefix="/api/graph", tags=["graph"])
 
 
+def _normalize_node_id(name: str) -> str:
+    return re.sub(r"\s+", "_", name.strip().lower())
+
+
+def _sanitize_user_label(value: str) -> str:
+    # Hide internal user scoping labels from API consumers.
+    return re.sub(r"User_[0-9a-fA-F-]{36}", "You", value)
+
+
 def _parse_graph_result_to_relationship(result: str) -> GraphRelationship:
     """
     Parse a Graphiti search result string into a GraphRelationship.
@@ -38,9 +48,9 @@ def _parse_graph_result_to_relationship(result: str) -> GraphRelationship:
             parts = result.split(" -> ")
             if len(parts) >= 3:
                 return GraphRelationship(
-                    source=parts[0].strip(),
+                    source=_sanitize_user_label(parts[0].strip()),
                     relation=parts[1].strip(),
-                    target=parts[2].strip(),
+                    target=_sanitize_user_label(parts[2].strip()),
                     properties={}
                 )
         
@@ -48,14 +58,14 @@ def _parse_graph_result_to_relationship(result: str) -> GraphRelationship:
         return GraphRelationship(
             source="System",
             relation="states",
-            target=result.strip(),
+            target=_sanitize_user_label(result.strip()),
             properties={}
         )
     except Exception:
         return GraphRelationship(
             source="Unknown",
             relation="related_to",
-            target=result if isinstance(result, str) else str(result),
+            target=_sanitize_user_label(result if isinstance(result, str) else str(result)),
             properties={}
         )
 
@@ -86,7 +96,11 @@ async def get_user_graph_facts(
     
     try:
         # Search for user-relevant facts
-        results = await graph_service.search(query=query, limit=limit)
+        results = await graph_service.search_user(
+            user_id=str(current_user.id),
+            query=query,
+            limit=limit,
+        )
         
         facts = []
         for result in results:
@@ -134,13 +148,14 @@ async def search_graph(
         )
     
     try:
-        results = await graph_service.search(
+        results = await graph_service.search_user(
+            user_id=str(current_user.id),
             query=request.query,
             limit=request.limit
         )
         
         return GraphSearchResponse(
-            results=results if isinstance(results, list) else [],
+            results=[_sanitize_user_label(item) for item in results] if isinstance(results, list) else [],
             count=len(results) if isinstance(results, list) else 0,
             available=True,
             message=None
@@ -180,7 +195,11 @@ async def get_graph_visualization_data(
         )
     
     try:
-        results = await graph_service.search(query=query, limit=limit)
+        results = await graph_service.search_user(
+            user_id=str(current_user.id),
+            query=query,
+            limit=limit,
+        )
         
         # Build nodes and relationships from search results
         nodes_dict = {}  # Use dict to avoid duplicates
@@ -193,7 +212,7 @@ async def get_graph_visualization_data(
             # Add source node
             if rel.source not in nodes_dict:
                 nodes_dict[rel.source] = GraphNode(
-                    id=rel.source.lower().replace(" ", "_"),
+                    id=_normalize_node_id(rel.source),
                     name=rel.source,
                     type=_infer_node_type(rel.source),
                     properties={}
@@ -202,7 +221,7 @@ async def get_graph_visualization_data(
             # Add target node
             if rel.target not in nodes_dict:
                 nodes_dict[rel.target] = GraphNode(
-                    id=rel.target.lower().replace(" ", "_"),
+                    id=_normalize_node_id(rel.target),
                     name=rel.target,
                     type=_infer_node_type(rel.target),
                     properties={}
@@ -251,3 +270,151 @@ def _infer_node_type(node_name: str) -> str:
         return "user"
     else:
         return "entity"
+
+
+# ============================================================================
+# INSIGHT PROMPTS
+# ============================================================================
+
+INSIGHT_PROMPTS = {
+    InsightType.TEMPORAL: """You are a health data analyst. Analyze these health facts and describe how the user's metrics have changed over time.
+
+**Health Data:**
+{facts}
+
+**Instructions:**
+- Identify any temporal trends (improving, worsening, stable)
+- Highlight significant changes between readings
+- Note dates/timestamps when available
+- Be clear and concise (2-3 paragraphs max)
+- If no temporal data is available, say so clearly""",
+
+    InsightType.RELATIONSHIPS: """You are a health data analyst. Explain the connections between conditions, medications, and health factors in this user's data.
+
+**Health Data:**
+{facts}
+
+**Instructions:**
+- Identify how conditions relate to each other
+- Explain medication-condition relationships
+- Highlight any lifestyle factors and their connections
+- Keep explanations patient-friendly (2-3 paragraphs max)
+- If relationships are unclear, note what additional data would help""",
+
+    InsightType.CONTRADICTIONS: """You are a health data analyst. Look for any data conflicts or inconsistencies in this user's health information.
+
+**Health Data:**
+{facts}
+
+**Instructions:**
+- Identify any values that seem inconsistent with each other
+- Note any concerning changes between readings
+- Flag potential data entry errors
+- Be specific but non-alarming (2-3 paragraphs max)
+- If no contradictions are found, say "No obvious data conflicts detected" """,
+}
+
+INSIGHT_QUERIES = {
+    InsightType.TEMPORAL: "health metrics changes values dates time readings results",
+    InsightType.RELATIONSHIPS: "conditions medications relationships interactions causes effects",
+    InsightType.CONTRADICTIONS: "health values changes abnormal conflicts inconsistent readings",
+}
+
+
+# Singleton LLM service for insights
+_llm_service: LLMService | None = None
+
+
+def _get_llm_service() -> LLMService:
+    global _llm_service
+    if _llm_service is None:
+        _llm_service = LLMService()
+    return _llm_service
+
+
+@router.post("/insights", response_model=InsightResponse)
+async def generate_graph_insight(
+    request: InsightRequest,
+    current_user: User = Depends(get_current_user),
+) -> InsightResponse:
+    """
+    Generate LLM-powered insights from the user's knowledge graph.
+    
+    Queries Graphiti for relevant facts, then uses LLM to generate
+    human-readable analysis based on the insight type:
+    - temporal: Timeline and trend analysis
+    - relationships: Health factor connections
+    - contradictions: Data inconsistencies
+    """
+    graph_service = get_graph_service()
+    llm_service = _get_llm_service()
+    
+    # Check if Graphiti is available
+    if graph_service.client is None:
+        return InsightResponse(
+            insight_type=request.insight_type,
+            content="",
+            sources=[],
+            available=False,
+            message="Knowledge graph service is not available"
+        )
+    
+    try:
+        # 1. Get relevant facts from the graph
+        query = INSIGHT_QUERIES.get(request.insight_type, "health data")
+        facts = await graph_service.search_user(
+            user_id=str(current_user.id),
+            query=query,
+            limit=request.context_limit,
+        )
+        
+        if not facts:
+            return InsightResponse(
+                insight_type=request.insight_type,
+                content="No health data found in your knowledge graph yet. Upload reports or sync your profile to build your health graph.",
+                sources=[],
+                available=True,
+                message=None
+            )
+        
+        # 2. Sanitize user labels from facts
+        sanitized_facts = [_sanitize_user_label(f) for f in facts]
+        facts_text = "\n".join(f"• {fact}" for fact in sanitized_facts)
+        
+        # 3. Build prompt and generate insight
+        prompt_template = INSIGHT_PROMPTS.get(request.insight_type)
+        if not prompt_template:
+            return InsightResponse(
+                insight_type=request.insight_type,
+                content="Unknown insight type",
+                sources=[],
+                available=True,
+                message="Invalid insight type"
+            )
+        
+        prompt = prompt_template.format(facts=facts_text)
+        
+        # 4. Generate insight using LLM
+        insight_content = await llm_service.generate(
+            user_message=prompt,
+            context="",  # Context is already in the prompt
+            chat_history=None,
+        )
+        
+        return InsightResponse(
+            insight_type=request.insight_type,
+            content=insight_content,
+            sources=sanitized_facts,
+            available=True,
+            message=None
+        )
+        
+    except Exception as e:
+        logger.error(f"Error generating insight for user {current_user.id}: {e}")
+        return InsightResponse(
+            insight_type=request.insight_type,
+            content="",
+            sources=[],
+            available=True,
+            message=f"Error generating insight: {str(e)}"
+        )

backend/app/routes/memory.py

@@ -4,11 +4,9 @@ Memory API Routes
 Exposes Mem0 memory layer to frontend for viewing, managing, and searching user memories.
 """
 import logging
-from fastapi import APIRouter, Depends, HTTPException, Query
-from sqlalchemy.ext.asyncio import AsyncSession
-from typing import Dict, Any
+from fastapi import APIRouter, Depends
+from typing import Any
 
-from app.db import get_db
 from app.models import User
 from app.security import get_current_user
 from app.services.memory_service import get_memory_service
@@ -26,6 +24,12 @@ logger = logging.getLogger(__name__)
 router = APIRouter(prefix="/api/memory", tags=["memory"])
 
 
+def _extract_memory_id(item: Any) -> str:
+    if isinstance(item, dict):
+        return str(item.get("id", item.get("memory_id", "")))
+    return ""
+
+
 def _normalize_memory_item(item: Any) -> MemoryFact:
     """
     Normalize a Mem0 memory item to our MemoryFact schema.
@@ -74,7 +78,11 @@ async def get_user_memories(
         
         # Handle different response formats from Mem0
         facts = []
+        raw_service_error = getattr(memory_service, "last_error", None)
+        service_error = raw_service_error if isinstance(raw_service_error, str) and raw_service_error else None
         if isinstance(memories, dict):
+            if "error" in memories:
+                service_error = str(memories["error"])
             # Mem0 might return {"results": [...]} or {"memories": [...]}
             memory_list = memories.get("results", memories.get("memories", []))
         elif isinstance(memories, list):
@@ -92,8 +100,8 @@ async def get_user_memories(
         return MemoryListResponse(
             facts=facts,
             total_count=len(facts),
-            available=True,
-            message=None
+            available=not (service_error and len(facts) == 0),
+            message=service_error
         )
         
     except Exception as e:
@@ -180,12 +188,16 @@ async def delete_memory(
         )
     
     try:
+        # Attempt the delete directly.  Mem0 memory IDs are UUIDs and are
+        # implicitly scoped to the user who created them via the vector store.
+        # Doing a full get_all() just for ownership verification is extremely
+        # slow because every Mem0 call goes through the Groq throttle (3s+).
         success = await memory_service.delete(memory_id)
         
         return MemoryDeleteResponse(
             success=success,
             deleted_count=1 if success else 0,
-            message="Memory deleted successfully" if success else "Failed to delete memory"
+            message="Memory deleted successfully" if success else "Memory not found or already deleted"
         )
         
     except Exception as e:
@@ -262,8 +274,19 @@ async def search_memories(
         
         # Handle different response formats
         facts = []
-        if isinstance(results, list):
-            for item in results:
+        raw_service_error = getattr(memory_service, "last_error", None)
+        service_error = raw_service_error if isinstance(raw_service_error, str) and raw_service_error else None
+        if isinstance(results, dict):
+            if "error" in results:
+                service_error = str(results["error"])
+            result_items = results.get("results", results.get("memories", []))
+        elif isinstance(results, list):
+            result_items = results
+        else:
+            result_items = []
+
+        if isinstance(result_items, list):
+            for item in result_items:
                 try:
                     facts.append(_normalize_memory_item(item))
                 except Exception as e:
@@ -273,8 +296,8 @@ async def search_memories(
         return MemoryListResponse(
             facts=facts,
             total_count=len(facts),
-            available=True,
-            message=None
+            available=not (service_error and len(facts) == 0),
+            message=service_error
         )
         
     except Exception as e:

backend/app/routes/profile.py

@@ -8,9 +8,11 @@ Provides endpoints for managing user health profiles, including:
 - Completion tracking and derived features
 - Recompute trigger
 """
+import asyncio
 import logging
+import re
 from datetime import datetime
-from typing import List, Optional
+from typing import Any, Dict, List, Optional
 from uuid import UUID
 from fastapi import APIRouter, Depends, HTTPException, BackgroundTasks
 from sqlalchemy.ext.asyncio import AsyncSession
@@ -19,6 +21,7 @@ from pydantic import BaseModel
 from app.db import get_db, async_session_maker
 from app.security import get_current_user
 from app.models import User
+from app.settings import settings
 from app.services.profile_service import ProfileService
 from app.services.recompute_service import RecomputeService
 from app.schemas import (
@@ -37,6 +40,9 @@ from app.schemas import (
 logger = logging.getLogger(__name__)
 
 router = APIRouter(prefix="/api/profile", tags=["profile"])
+MEMORY_SYNC_TIMEOUT_SECONDS = 60.0
+MEMORY_SYNC_MAX_RETRIES = 2
+MEMORY_SYNC_RETRY_BASE_SECONDS = 3.0
 
 
 # ============================================================================
@@ -594,6 +600,137 @@ async def update_wizard_state(
 # MEMORY & GRAPH SYNC
 # ============================================================================
 
+def _safe_float(value: Any) -> Optional[float]:
+    try:
+        if value is None:
+            return None
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _normalize_fact(text: str) -> str:
+    return " ".join(text.strip().split())
+
+
+def _build_profile_sync_facts(profile_data: Dict[str, Any]) -> List[str]:
+    """Build direct profile facts + lightweight inferred insights for memory/graph sync."""
+    facts: List[str] = []
+
+    profile = profile_data.get("profile")
+    if profile:
+        if profile.height_cm:
+            facts.append(f"height is {profile.height_cm} cm")
+        if profile.weight_kg:
+            facts.append(f"weight is {profile.weight_kg} kg")
+        if profile.sex_at_birth:
+            facts.append(f"sex at birth is {profile.sex_at_birth}")
+        if profile.activity_level:
+            facts.append(f"activity level is {profile.activity_level}")
+        if profile.sleep_hours_avg:
+            facts.append(f"sleep is about {profile.sleep_hours_avg} hours per night")
+        if profile.diet_pattern:
+            facts.append(f"diet pattern is {profile.diet_pattern}")
+        if profile.smoking:
+            facts.append(f"smoking status is {profile.smoking}")
+        if profile.alcohol:
+            facts.append(f"alcohol use is {profile.alcohol}")
+
+    # Conditions
+    conditions = profile_data.get("conditions", []) or []
+    for condition in conditions:
+        if condition.condition_name:
+            facts.append(f"has condition {condition.condition_name}")
+
+    # Medications
+    medications = profile_data.get("medications", []) or []
+    for med in medications:
+        if med.name:
+            fact = f"takes medication {med.name}"
+            if med.dose:
+                fact += f" at dose {med.dose}"
+            facts.append(fact)
+
+    # Supplements
+    supplements = profile_data.get("supplements", []) or []
+    for supp in supplements:
+        if supp.name:
+            fact = f"takes supplement {supp.name}"
+            if supp.dose:
+                fact += f" at dose {supp.dose}"
+            facts.append(fact)
+
+    # Allergies
+    allergies = profile_data.get("allergies", []) or []
+    for allergy in allergies:
+        if allergy.allergen:
+            facts.append(f"is allergic to {allergy.allergen}")
+
+    # Family history
+    family_history = profile_data.get("family_history", []) or []
+    for history in family_history:
+        if history.condition_name and history.relative_type:
+            facts.append(f"family history includes {history.relative_type} with {history.condition_name}")
+
+    # Lightweight, deterministic inferences from questionnaire data.
+    if profile:
+        height_cm = _safe_float(profile.height_cm)
+        weight_kg = _safe_float(profile.weight_kg)
+        if height_cm and height_cm > 0 and weight_kg and weight_kg > 0:
+            bmi = round(weight_kg / ((height_cm / 100.0) ** 2), 1)
+            if bmi < 18.5:
+                bmi_band = "underweight"
+            elif bmi < 25:
+                bmi_band = "normal"
+            elif bmi < 30:
+                bmi_band = "overweight"
+            else:
+                bmi_band = "obesity"
+            facts.append(f"inference: bmi is {bmi} which falls in {bmi_band} range")
+
+        exercise_minutes = _safe_float(profile.exercise_minutes_per_week)
+        if exercise_minutes is not None:
+            if exercise_minutes < 90:
+                facts.append("inference: weekly activity is low and may increase cardiometabolic risk")
+            elif exercise_minutes >= 150:
+                facts.append("inference: weekly activity meets or exceeds recommended baseline")
+
+        sleep_hours = _safe_float(profile.sleep_hours_avg)
+        if sleep_hours is not None:
+            if sleep_hours < 6:
+                facts.append("inference: habitual short sleep may affect recovery and metabolic health")
+            elif sleep_hours >= 7:
+                facts.append("inference: sleep duration is within a generally healthy range")
+
+        smoking_value = str(profile.smoking or "").strip().lower()
+        if smoking_value in {"yes", "current", "daily", "sometimes"}:
+            facts.append("inference: smoking status indicates elevated cardiovascular and respiratory risk")
+
+        alcohol_value = str(profile.alcohol or "").strip().lower()
+        if alcohol_value in {"heavy", "daily", "frequent"}:
+            facts.append("inference: alcohol pattern may impact liver and cardiometabolic risk profile")
+
+    if conditions and family_history:
+        facts.append("inference: combined personal and family history increases value of preventive monitoring")
+    if medications and allergies:
+        facts.append("inference: medication planning should remain allergy-aware")
+
+    # De-duplicate while preserving order and keeping text normalized.
+    deduped: List[str] = []
+    seen = set()
+    for fact in facts:
+        normalized = _normalize_fact(fact)
+        if not normalized:
+            continue
+        key = normalized.lower()
+        if key in seen:
+            continue
+        seen.add(key)
+        deduped.append(normalized)
+
+    return deduped
+
+
 @router.post("/sync-to-memory")
 async def sync_profile_to_memory(
     current_user: User = Depends(get_current_user),
@@ -612,83 +749,155 @@ async def sync_profile_to_memory(
     profile_data = await service.get_full_profile()
     
     user_id = str(current_user.id)
-    synced = {"memory": False, "graph": False, "facts_synced": 0}
-    
-    # Build facts from profile data
-    facts_to_sync = []
-    
-    # Basic profile info
-    profile = profile_data.get("profile")
-    if profile:
-        if profile.height_cm:
-            facts_to_sync.append(f"User height is {profile.height_cm}cm")
-        if profile.weight_kg:
-            facts_to_sync.append(f"User weight is {profile.weight_kg}kg")
-        if profile.biological_sex:
-            facts_to_sync.append(f"User's biological sex is {profile.biological_sex}")
-        if profile.activity_level:
-            facts_to_sync.append(f"User's activity level is {profile.activity_level}")
-        if profile.sleep_hours:
-            facts_to_sync.append(f"User sleeps about {profile.sleep_hours} hours per night")
-    
-    # Conditions
-    for condition in profile_data.get("conditions", []):
-        if condition.condition_name:
-            facts_to_sync.append(f"User has condition: {condition.condition_name}")
-    
-    # Medications
-    for med in profile_data.get("medications", []):
-        if med.medication_name:
-            fact = f"User takes medication: {med.medication_name}"
-            if med.dosage:
-                fact += f" ({med.dosage})"
-            facts_to_sync.append(fact)
-    
-    # Allergies
-    for allergy in profile_data.get("allergies", []):
-        if allergy.allergen:
-            facts_to_sync.append(f"User is allergic to: {allergy.allergen}")
-    
-    # Family history
-    for history in profile_data.get("family_history", []):
-        if history.condition_name and history.relation:
-            facts_to_sync.append(f"Family history: {history.relation} has {history.condition_name}")
-    
+    facts_to_sync = _build_profile_sync_facts(profile_data)
+    synced = {
+        "memory": False,
+        "graph": False,
+        "facts_attempted": len(facts_to_sync),
+        "facts_synced": 0,
+        "memory_facts_synced": 0,
+        "graph_facts_synced": 0,
+    }
+    errors: List[str] = []
+
+    if not facts_to_sync:
+        return {
+            "success": False,
+            "synced": synced,
+            "errors": ["No profile facts were available to sync yet."],
+            "message": "No profile facts available to sync",
+        }
+
     # Sync to Memory (Mem0)
     memory_service = get_memory_service()
-    if memory_service.is_available and facts_to_sync:
-        try:
-            for fact in facts_to_sync:
-                await memory_service.add(
-                    messages=fact,
-                    user_id=user_id,
-                    metadata={"source": "questionnaire_sync"}
+    if not memory_service.is_available:
+        errors.append("Memory service (Mem0) is not available.")
+    else:
+        batch_size = settings.MEM0_SYNC_BATCH_SIZE
+        batch_delay = settings.MEM0_BATCH_DELAY_SECONDS
+        memory_batches = [
+            facts_to_sync[i : i + batch_size]
+            for i in range(0, len(facts_to_sync), batch_size)
+        ]
+
+        async def _sync_batch(batch_index: int, batch: List[str]) -> bool:
+            batch_content = "profile sync snapshot facts:\n" + "\n".join(f"- {fact}" for fact in batch)
+
+            for attempt in range(1, MEMORY_SYNC_MAX_RETRIES + 1):
+                try:
+                    result = await asyncio.wait_for(
+                        memory_service.add(
+                            content=batch_content,
+                            user_id=user_id,
+                            metadata={
+                                "source": "questionnaire_sync",
+                                "kind": "profile_fact_batch",
+                                "batch_index": batch_index,
+                                "batch_size": len(batch),
+                            },
+                        ),
+                        timeout=MEMORY_SYNC_TIMEOUT_SECONDS,
+                    )
+                except asyncio.TimeoutError:
+                    logger.warning(
+                        "Timed out syncing Mem0 batch %s for user %s after %.1fs (attempt %s/%s)",
+                        batch_index,
+                        user_id,
+                        MEMORY_SYNC_TIMEOUT_SECONDS,
+                        attempt,
+                        MEMORY_SYNC_MAX_RETRIES,
+                    )
+                    if attempt < MEMORY_SYNC_MAX_RETRIES:
+                        await asyncio.sleep(MEMORY_SYNC_RETRY_BASE_SECONDS * attempt)
+                        continue
+                    return False
+                except Exception as exc:
+                    logger.warning(
+                        "Unexpected Mem0 batch sync error for user %s (batch %s, attempt %s/%s): %s",
+                        user_id,
+                        batch_index,
+                        attempt,
+                        MEMORY_SYNC_MAX_RETRIES,
+                        exc,
+                    )
+                    if attempt < MEMORY_SYNC_MAX_RETRIES:
+                        await asyncio.sleep(MEMORY_SYNC_RETRY_BASE_SECONDS * attempt)
+                        continue
+                    return False
+
+                # memory_service.add() now self-retries on 429; a returned error
+                # here means retries were exhausted or a non-429 failure occurred.
+                if isinstance(result, dict) and result.get("error"):
+                    err_text = str(result["error"])
+                    logger.warning(
+                        "Mem0 batch sync failed for user %s (batch %s, attempt %s/%s): %s",
+                        user_id,
+                        batch_index,
+                        attempt,
+                        MEMORY_SYNC_MAX_RETRIES,
+                        err_text,
+                    )
+                    if attempt < MEMORY_SYNC_MAX_RETRIES:
+                        await asyncio.sleep(MEMORY_SYNC_RETRY_BASE_SECONDS * attempt)
+                        continue
+                    return False
+
+                return True
+
+            return False
+
+        memory_sync_count = 0
+        for batch_index, batch in enumerate(memory_batches, start=1):
+            batch_synced = await _sync_batch(batch_index, batch)
+            if batch_synced:
+                memory_sync_count += len(batch)
+            # Proactive inter-batch delay to avoid Groq TPM exhaustion
+            if batch_index < len(memory_batches) and batch_delay > 0:
+                logger.debug(
+                    "Mem0 sync: proactive %.1fs delay before batch %s/%s",
+                    batch_delay, batch_index + 1, len(memory_batches),
                 )
-            synced["memory"] = True
-            synced["facts_synced"] = len(facts_to_sync)
-            logger.info(f"Synced {len(facts_to_sync)} facts to Mem0 for user {user_id}")
-        except Exception as e:
-            logger.warning(f"Failed to sync to Mem0: {e}")
+                await asyncio.sleep(batch_delay)
+
+        if memory_sync_count < len(facts_to_sync):
+            logger.info("Mem0 sync partial success for user %s: %s/%s facts", user_id, memory_sync_count, len(facts_to_sync))
+
+        synced["memory_facts_synced"] = memory_sync_count
+        synced["memory"] = memory_sync_count > 0
+        if memory_sync_count > 0:
+            logger.info("Synced %s facts to Mem0 for user %s", memory_sync_count, user_id)
+        else:
+            errors.append(memory_service.last_error or "Failed to sync questionnaire data to Mem0.")
     
     # Sync to Graph (Neo4j/Graphiti)
     graph_service = get_graph_service()
-    if graph_service.client is not None and facts_to_sync:
+    if graph_service.client is not None:
         try:
-            # Graphiti/Neo4j usually expects episodes or structured data
-            # For now, add as text-based facts
-            for fact in facts_to_sync:
-                await graph_service.add_fact(
-                    fact=fact,
-                    source="questionnaire"
-                )
+            await graph_service.add_user_facts(
+                user_id=user_id,
+                facts=facts_to_sync,
+                source="questionnaire_sync",
+                timestamp=datetime.utcnow().isoformat(),
+            )
             synced["graph"] = True
-            logger.info(f"Synced {len(facts_to_sync)} facts to Neo4j for user {user_id}")
+            synced["graph_facts_synced"] = len(facts_to_sync)
+            logger.info("Synced %s facts to Neo4j for user %s", len(facts_to_sync), user_id)
         except Exception as e:
-            logger.warning(f"Failed to sync to Neo4j (may not support add_fact): {e}")
-    
+            logger.warning("Failed to sync to Neo4j: %s", e)
+            errors.append(f"Graph sync failed: {e}")
+    else:
+        errors.append("Knowledge graph service is not available.")
+
+    synced["facts_synced"] = max(synced["memory_facts_synced"], synced["graph_facts_synced"])
+    overall_success = synced["memory"] or synced["graph"]
+
     return {
-        "success": True,
+        "success": overall_success,
         "synced": synced,
-        "message": f"Synced {synced['facts_synced']} profile facts to memory/graph layers"
+        "errors": errors,
+        "message": (
+            f"Synced {synced['facts_synced']} profile facts to memory/graph layers"
+            if overall_success
+            else "Profile sync failed for both memory and graph layers"
+        ),
     }
-

backend/app/routes/websocket.py

@@ -103,11 +103,15 @@ async def handle_chat_request(
 ):
     """
     Handle streaming chat request via WebSocket.
-    
+
+    Leverages RAG, Mem0 (long-term memory), and Graphiti (knowledge graph)
+    to build rich context, then streams the LLM response and sends
+    structured source references alongside the answer.
+
     Sends:
-    - chat_start: Indicates response generation started
+    - chat_start: Indicates response generation started (includes sources summary)
     - chat_token: Each token as it's generated
-    - chat_complete: Final message with citations
+    - chat_complete: Final message with citations / references
     - chat_error: On any error
     """
     import uuid as uuid_module
@@ -116,7 +120,7 @@ async def handle_chat_request(
     from app.services.graph_service import get_graph_service
     from app.services.llm_service import get_llm_service
     from app.db import async_session
-    
+
     try:
         if not message_content or not str(message_content).strip():
             await websocket.send_json({
@@ -129,32 +133,36 @@ async def handle_chat_request(
         # Send start event
         await websocket.send_json({
             "type": "chat_start",
-            "data": {"message": "Generating response..."},
+            "data": {"message": "Gathering context from your health data, memories, and knowledge graph..."},
             "timestamp": datetime.utcnow().isoformat()
         })
-        
+
         # Get services
         rag_service = get_rag_service()
         memory_service = get_memory_service()
         graph_service = get_graph_service()
         llm_service = get_llm_service()
-        
-        # Get user context from RAG
+
+        # ---- Parallel context retrieval from all 3 sources ----
+        user_uuid = uuid_module.UUID(user_id)
+
         async with async_session() as db:
-            context = await rag_service.get_user_context(
-                user_id=uuid_module.UUID(user_id),
+            rag_structured = await rag_service.get_user_context_structured(
+                user_id=user_uuid,
                 query=message_content,
-                db=db
+                db=db,
             )
 
-        # Retrieve long-term memory and graph facts (best-effort)
         memories = await memory_service.search(message_content, user_id=user_id, limit=5)
-        graph_facts = await graph_service.search(message_content, limit=5)
+        graph_facts = await graph_service.search_user(user_id=user_id, query=message_content, limit=5)
 
-        # Assemble context for LLM in a consistent, structured format
+        # ---- Assemble structured context for the LLM ----
         parts = []
+
+        # Memories (Mem0)
         if memories:
             parts.append("--- RELEVANT MEMORIES (User Facts & Preferences) ---")
+            parts.append("[Source: User Memory / Health Profile]")
             for m in memories:
                 if isinstance(m, str):
                     text = m
@@ -172,18 +180,62 @@ async def handle_chat_request(
                 if text:
                     parts.append(f"- {text}")
 
+        # Knowledge Graph (Graphiti)
         if graph_facts:
             parts.append("\n--- MEDICAL KNOWLEDGE GRAPH (Relationships & Facts) ---")
+            parts.append("[Source: Medical Knowledge Graph / Graphiti]")
             for f in graph_facts:
                 parts.append(f"- {f}")
 
-        if context:
+        # RAG documents (ChromaDB)
+        rag_text = rag_structured.get("text", "") if isinstance(rag_structured, dict) else str(rag_structured)
+        if rag_text:
             parts.append("\n--- MEDICAL DATA & REPORTS ---")
-            parts.append(context)
+            parts.append(rag_text)
 
         full_context = "\n".join(parts)
-        
-        # Stream response from LLM
+
+        # ---- Build structured citations / references ----
+        citations = []
+        rag_sources = rag_structured.get("sources", []) if isinstance(rag_structured, dict) else []
+
+        for src in rag_sources:
+            if src.get("type") == "report":
+                citations.append({
+                    "source_type": "report",
+                    "label": f"Report: {src.get('filename', 'Unknown')}",
+                    "report_id": src.get("report_id"),
+                    "excerpt": src.get("excerpt", ""),
+                })
+            elif src.get("type") == "observations":
+                citations.append({
+                    "source_type": "observations",
+                    "label": f"Lab Data: {src.get('metric_name', 'health metric')}",
+                    "excerpt": src.get("excerpt", ""),
+                })
+
+        if memories:
+            mem_excerpts = []
+            for m in memories:
+                if isinstance(m, str):
+                    mem_excerpts.append(m[:120])
+                elif isinstance(m, dict):
+                    t = m.get("memory") or m.get("text") or m.get("content") or ""
+                    mem_excerpts.append(t[:120])
+            citations.append({
+                "source_type": "memory",
+                "label": f"User Memory ({len(memories)} facts)",
+                "excerpt": "; ".join(mem_excerpts)[:300],
+            })
+
+        if graph_facts:
+            citations.append({
+                "source_type": "knowledge_graph",
+                "label": f"Knowledge Graph ({len(graph_facts)} facts)",
+                "excerpt": "; ".join(str(f)[:80] for f in graph_facts)[:300],
+            })
+
+        # ---- Stream response from LLM ----
         full_response = ""
         async for token in llm_service.stream_generate(
             user_message=message_content,
@@ -195,31 +247,37 @@ async def handle_chat_request(
                 "data": {"token": token},
                 "timestamp": datetime.utcnow().isoformat()
             })
-        
-        # Send completion event
+
+        # ---- Send completion event with references ----
         await websocket.send_json({
             "type": "chat_complete",
             "data": {
                 "full_response": full_response,
-                "citations": [],  # TODO: Extract citations from context
+                "citations": citations,
+                "sources_summary": {
+                    "rag_documents": len(rag_sources),
+                    "memories_used": len(memories),
+                    "graph_facts_used": len(graph_facts),
+                },
                 "session_id": session_id
             },
             "timestamp": datetime.utcnow().isoformat()
         })
 
-        # Update memory and graph in background; don't block client completion.
+        # ---- Update memory and graph in background ----
         interaction = f"User: {message_content}\nAssistant: {full_response}"
         asyncio.create_task(
             memory_service.add(interaction, user_id=user_id, metadata={"source": "websocket_chat"})
         )
         asyncio.create_task(
-            graph_service.add_episode(
-                f"User asked: {message_content}\nAssistant answered: {full_response}",
+            graph_service.add_user_episode(
+                user_id=user_id,
+                content=f"User asked: {message_content}\nAssistant answered: {full_response}",
                 source="user_chat_websocket",
                 timestamp=datetime.utcnow().isoformat(),
             )
         )
-        
+
     except Exception as e:
         import traceback
         traceback.print_exc()

backend/app/schemas_memory.py

@@ -107,3 +107,32 @@ class GraphFactsResponse(BaseModel):
     count: int = Field(0, description="Number of facts")
     available: bool = Field(True, description="Whether graph service is available")
     message: Optional[str] = Field(None, description="Optional status message")
+
+
+# ============================================================================
+# GRAPH INSIGHTS (LLM-powered analysis) SCHEMAS
+# ============================================================================
+
+from enum import Enum
+
+
+class InsightType(str, Enum):
+    """Types of AI-powered graph insights."""
+    TEMPORAL = "temporal"           # Timeline analysis - trends over time
+    RELATIONSHIPS = "relationships"  # Health connections - conditions/meds/factors
+    CONTRADICTIONS = "contradictions"  # Data conflicts - inconsistencies
+
+
+class InsightRequest(BaseModel):
+    """Request for LLM-powered graph insight."""
+    insight_type: InsightType = Field(..., description="Type of insight to generate")
+    context_limit: int = Field(default=10, ge=1, le=20, description="Max graph facts to use as context")
+
+
+class InsightResponse(BaseModel):
+    """Response containing LLM-generated insight."""
+    insight_type: InsightType = Field(..., description="Type of insight generated")
+    content: str = Field(..., description="LLM-generated insight text")
+    sources: List[str] = Field(default_factory=list, description="Graph facts used as context")
+    available: bool = Field(True, description="Whether service is available")
+    message: Optional[str] = Field(None, description="Optional status/error message")

backend/app/services/assistant_service.py

@@ -27,7 +27,7 @@ class AssistantService:
     1. Mem0: Long-term memory for user preferences and facts
     2. Graphiti: Knowledge graph for medical reasoning and temporal facts
     3. RAG: Retrieval from uploaded reports and observations
-    4. LLM: Generative response (Ollama MedGemma / Gemini)
+    4. LLM: Generative response (OpenRouter primary → Gemini → Ollama last resort)
     """
 
     def __init__(self, db: AsyncSession):
@@ -80,12 +80,12 @@ class AssistantService:
         await self.db.commit()
 
         # 3. Parallel Retrieval Phase
-        # We gather context from RAG, Memory, and Graph
-        rag_context, memory_context, graph_context = await self._gather_context(user_id, message)
+        # We gather context from RAG (structured), Memory, and Graph
+        rag_structured, memory_context, graph_context = await self._gather_context(user_id, message)
 
         # 4. Context Assembly
         full_context = self._assemble_context(
-            rag_context=rag_context,
+            rag_context=rag_structured,
             memory_context=memory_context,
             graph_context=graph_context
         )
@@ -105,17 +105,18 @@ class AssistantService:
         # Update Memory & Graph with new interaction
         await self._update_memory_and_graph(user_id, message, response_content)
 
-        # Extract citations (placeholder logic, usually LLM would provide them structured)
-        citations = self._extract_citations(rag_context)
+        # Extract citations from structured RAG sources + memory/graph flags
+        citations = self._extract_citations(rag_structured, memory_context, graph_context)
 
         # Save assistant message
+        rag_sources = rag_structured.get("sources", []) if isinstance(rag_structured, dict) else []
         assistant_msg = ChatMessage(
             session_id=session_id,
             role="assistant",
             content=response_content,
             message_metadata={
                 "citations": [c.dict() for c in citations],
-                "rag_sources": len(rag_context),
+                "rag_sources": len(rag_sources),
                 "memories_used": len(memory_context),
                 "graph_facts_used": len(graph_context)
             },
@@ -127,31 +128,30 @@ class AssistantService:
 
         return response_content, citations, session_id, assistant_msg.id
 
-    async def _gather_context(self, user_id: uuid.UUID, query: str) -> Tuple[str, List[Dict], List[str]]:
+    async def _gather_context(self, user_id: uuid.UUID, query: str) -> Tuple[Dict[str, Any], List[Dict], List[str]]:
         """
         Retrieve context from all sources.
-        Returns: (rag_text, memories, graph_facts)
+        Returns: (rag_structured, memories, graph_facts)
         """
-        # A. RAG Retrieval (Documents & Observations)
-        # Note: get_user_context returns a formatted string, we might want raw docs too if we want citations
-        # For now, we'll use the service's high-level method for the text, and query again if we need citation metadata
-        rag_text = await self.rag_service.get_user_context(user_id, query, self.db)
+        # A. RAG Retrieval – structured (includes source metadata for citations)
+        rag_structured = await self.rag_service.get_user_context_structured(user_id, query, self.db)
 
         # B. Memory Retrieval (User facts/prefs)
         memories = await self.memory_service.search(query, user_id=str(user_id), limit=5)
 
         # C. Graph Retrieval (Medical knowledge/relationships)
-        graph_facts = await self.graph_service.search(query, limit=5)
+        graph_facts = await self.graph_service.search_user(str(user_id), query, limit=5)
 
-        return rag_text, memories, graph_facts
+        return rag_structured, memories, graph_facts
 
-    def _assemble_context(self, rag_context: str, memory_context: List[Dict], graph_context: List[str]) -> str:
+    def _assemble_context(self, rag_context: Dict[str, Any], memory_context: List[Dict], graph_context: List[str]) -> str:
         """Combine all context sources into a structured string for the LLM."""
         parts = []
 
         # 1. User Memories (Preferences, facts)
         if memory_context:
             parts.append("--- RELEVANT MEMORIES (User Facts & Preferences) ---")
+            parts.append("[Source: User Memory / Health Profile]")
             for m in memory_context:
                 if isinstance(m, str):
                     text = m
@@ -173,13 +173,15 @@ class AssistantService:
         # 2. Knowledge Graph (Medical connections)
         if graph_context:
             parts.append("\n--- MEDICAL KNOWLEDGE GRAPH (Relationships & Facts) ---")
+            parts.append("[Source: Medical Knowledge Graph / Graphiti]")
             for f in graph_context:
                 parts.append(f"- {f}")
 
-        # 3. RAG Data (Reports & Lab Results)
-        if rag_context:
+        # 3. RAG Data (Reports & Lab Results) – use the structured text
+        rag_text = rag_context.get("text", "") if isinstance(rag_context, dict) else rag_context
+        if rag_text:
             parts.append("\n--- MEDICAL DATA & REPORTS ---")
-            parts.append(rag_context)
+            parts.append(rag_text)
 
         return "\n".join(parts)
 
@@ -197,30 +199,68 @@ class AssistantService:
             )
 
             # Add to Graphiti (structured episodes)
-            await self.graph_service.add_episode(
-                f"User asked: {user_msg}\nAssistant answered: {assistant_msg}",
+            await self.graph_service.add_user_episode(
+                user_id=str(user_id),
+                content=f"User asked: {user_msg}\nAssistant answered: {assistant_msg}",
                 source="user_chat"
             )
         except Exception as e:
             logger.error(f"Error updating memory/graph: {e}")
 
-    def _extract_citations(self, rag_context_str: str) -> List[Citation]:
+    def _extract_citations(
+        self,
+        rag_structured: Dict[str, Any],
+        memory_context: List[Dict],
+        graph_context: List[str],
+    ) -> List[Citation]:
         """
-        Attempt to reconstruct citations from the RAG context string.
-        This is a simplification. Ideally, we pass the raw RAG docs through.
+        Build Citation objects from the structured context sources.
         """
-        # Since we only have the string from `get_user_context`, we can't easily rebuild
-        # precise Citation objects without parsing or changing RAGService to return structured data.
-        # For MVP, we return empty citations or generic ones if we detect report content.
-        citations = []
-        if "From report" in rag_context_str:
-            # Minimal dummy citation to indicate source usage
+        citations: List[Citation] = []
+
+        # RAG document sources
+        rag_sources = rag_structured.get("sources", []) if isinstance(rag_structured, dict) else []
+        for src in rag_sources:
+            if src.get("type") == "report":
+                citations.append(Citation(
+                    report_id=src.get("report_id"),
+                    metric_name=src.get("filename", "Report"),
+                    value="Referenced Report",
+                    excerpt=src.get("excerpt", ""),
+                ))
+            elif src.get("type") == "observations":
+                citations.append(Citation(
+                    report_id=None,
+                    metric_name=src.get("metric_name", "Lab Observation"),
+                    value="Lab Data",
+                    excerpt=src.get("excerpt", ""),
+                ))
+
+        # Memory source indicator
+        if memory_context:
+            mem_texts = []
+            for m in memory_context:
+                if isinstance(m, str):
+                    mem_texts.append(m[:100])
+                elif isinstance(m, dict):
+                    t = m.get("memory") or m.get("text") or m.get("content") or ""
+                    mem_texts.append(t[:100])
             citations.append(Citation(
                 report_id=None,
-                metric_name="General",
-                value="Referenced Report",
-                excerpt="See context for details"
+                metric_name="User Memory (Mem0)",
+                value=f"{len(memory_context)} memories referenced",
+                excerpt="; ".join(mem_texts)[:300],
             ))
+
+        # Graph source indicator
+        if graph_context:
+            citations.append(Citation(
+                report_id=None,
+                metric_name="Medical Knowledge Graph",
+                value=f"{len(graph_context)} graph facts referenced",
+                excerpt="; ".join(str(f)[:80] for f in graph_context)[:300],
+            ))
+
         return citations
 
     async def get_session_history(

backend/app/services/document_processing.py

@@ -604,10 +604,12 @@ class DocumentProcessingService:
 
                 if report:
                     graph_service = get_graph_service()
+                    memory_service = get_memory_service()
 
                     # Add episode about the upload
-                    await graph_service.add_episode(
-                        f"User uploaded medical report: {report.filename} (Type: {report.doc_type})",
+                    await graph_service.add_user_episode(
+                        user_id=str(self.user.id),
+                        content=f"uploaded medical report: {report.filename} (Type: {report.doc_type})",
                         source="document_upload",
                         timestamp=report.uploaded_at.isoformat() if report.uploaded_at else datetime.utcnow().isoformat()
                     )
@@ -619,19 +621,93 @@ class DocumentProcessingService:
                     observations = obs_result.scalars().all()
 
                     if observations:
-                        # Format observations for graph
-                        obs_texts = []
-                        for obs in observations:
-                            status = "Abnormal" if obs.is_abnormal else "Normal"
+                        # -------------------------------------------------------
+                        # Only sync *clinically relevant* data to the knowledge
+                        # graph – abnormal findings plus a brief overall summary.
+                        # Dumping every normal reading would bloat the graph and
+                        # dilute the signal used by the recommendation engine.
+                        # -------------------------------------------------------
+                        abnormal_obs = [obs for obs in observations if obs.is_abnormal]
+                        normal_count = len(observations) - len(abnormal_obs)
+
+                        obs_texts = [
+                            f"Report {report.filename}: {len(observations)} total observations, "
+                            f"{len(abnormal_obs)} abnormal, {normal_count} normal"
+                        ]
+                        for obs in abnormal_obs:
                             obs_texts.append(
-                                f"{obs.metric_name}: {obs.value} {obs.unit} ({status})"
+                                f"{obs.metric_name}: {obs.value} {obs.unit} "
+                                f"(flagged {obs.flag or 'abnormal'})"
                             )
 
-                        await graph_service.add_observations(
-                            obs_texts,
+                        await graph_service.add_user_facts(
+                            user_id=str(self.user.id),
+                            facts=obs_texts,
                             source=f"report_{report.filename}"
                         )
 
+                        # Sync report-level inferences to Mem0 so the "Health Memory"
+                        # reflects document findings as well.
+                        if memory_service.is_available:
+                            abnormal_observations = abnormal_obs  # already computed above
+                            # normal_count already calculated above
+
+                            summary_parts = [
+                                f"report {report.filename} processed",
+                                f"{len(observations)} observations extracted",
+                                f"{len(abnormal_observations)} abnormal and {normal_count} normal flags",
+                            ]
+                            if report.doc_type:
+                                summary_parts.append(f"document type {report.doc_type}")
+                            report_summary = "; ".join(summary_parts)
+
+                            summary_result = await memory_service.add(
+                                content=f"report inference summary: {report_summary}",
+                                user_id=str(self.user.id),
+                                metadata={
+                                    "source": "report_inference",
+                                    "report_id": str(report.id),
+                                    "doc_type": report.doc_type,
+                                },
+                            )
+                            if isinstance(summary_result, dict) and summary_result.get("error"):
+                                logger.warning(
+                                    "Failed to sync report summary to Mem0 for report %s: %s",
+                                    report_id,
+                                    summary_result["error"],
+                                )
+
+                            # Store abnormal findings as a single combined memory
+                            # instead of individual calls to avoid Groq TPM exhaustion.
+                            if abnormal_observations:
+                                abnormal_lines = []
+                                for obs in abnormal_observations[:12]:
+                                    abnormal_lines.append(
+                                        f"{obs.metric_name} measured {obs.value} {obs.unit} "
+                                        f"flagged {obs.flag or 'abnormal'}"
+                                    )
+                                combined_text = (
+                                    f"report inference abnormal findings from {report.filename}:\n- "
+                                    + "\n- ".join(abnormal_lines)
+                                )
+                                abnormal_result = await memory_service.add(
+                                    content=combined_text,
+                                    user_id=str(self.user.id),
+                                    metadata={
+                                        "source": "report_inference",
+                                        "report_id": str(report.id),
+                                        "kind": "abnormal_findings_batch",
+                                        "abnormal_count": len(abnormal_observations),
+                                    },
+                                )
+                                if isinstance(abnormal_result, dict) and abnormal_result.get("error"):
+                                    logger.warning(
+                                        "Failed to sync abnormal observations to Mem0 "
+                                        "(report=%s): %s",
+                                        report_id,
+                                        abnormal_result["error"],
+                                    )
+
             logger.info(f"Background sync complete for report {report_id}")
 
         except Exception as e:

backend/app/services/enhanced_report_service.py

@@ -6,17 +6,20 @@ Integrates:
 - Lab report parsing  
 - Observation storage
 - WebSocket event emission
+- Memory / Knowledge Graph / RAG sync
 """
 import logging
 import os
+import asyncio
 from pathlib import Path
-from typing import Optional
+from typing import Optional, List
 from datetime import datetime
 from uuid import UUID
 
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy import select
 
+from app.db import async_session_maker
 from app.models import Report, Observation, ReportStatus, ObservationType
 from app.services.pdf_extractor import PDFExtractor
 from app.services.lab_parser import LabParser
@@ -189,6 +192,10 @@ class EnhancedReportService:
             
             # Trigger health index recomputation
             await self._recompute_health_index_and_emit(user_id)
+
+            # Sync to Memory (Mem0), Knowledge Graph (Neo4j), and RAG (ChromaDB)
+            # in the background so the endpoint doesn't block.
+            asyncio.create_task(self._sync_to_memory_and_graph(report_id, user_id))
             
             logger.info(f"Report {report_id} processing complete with {observation_count} observations")
             
@@ -239,3 +246,162 @@ class EnhancedReportService:
                 
         except Exception as e:
             logger.exception(f"Error computing health index for user {user_id}: {e}")
+
+    # ------------------------------------------------------------------
+    # Memory / Knowledge Graph / RAG sync  (background task)
+    # ------------------------------------------------------------------
+
+    async def _sync_to_memory_and_graph(self, report_id: UUID, user_id: UUID):
+        """
+        Background task to sync processed report data to:
+        1. RAG (ChromaDB) – for retrieval-augmented generation
+        2. Knowledge Graph (Neo4j/Graphiti) – abnormal findings only
+        3. Memory (Mem0) – report summary + abnormal observations
+
+        This bridges the gap between the active upload pipeline
+        (EnhancedReportService) and the intelligence layers.
+        """
+        from app.services.memory_service import get_memory_service
+        from app.services.graph_service import get_graph_service
+        from app.services.rag_service import get_rag_service
+
+        try:
+            logger.info("Starting background memory/graph/RAG sync for report %s", report_id)
+
+            # Use a fresh session so we don't interfere with the caller's session.
+            async with async_session_maker() as session:
+                # ---- 1. RAG sync (ChromaDB) ----
+                try:
+                    rag_service = get_rag_service()
+                    await rag_service.sync_user_reports(user_id, session)
+                    await rag_service.sync_user_observations(user_id, session)
+                    logger.info("RAG sync complete for report %s", report_id)
+                except Exception as e:
+                    logger.warning("RAG sync failed for report %s: %s", report_id, e)
+
+                # ---- Fetch report + observations ----
+                result = await session.execute(
+                    select(Report).where(Report.id == report_id)
+                )
+                report = result.scalar_one_or_none()
+                if not report:
+                    logger.warning("Report %s not found during sync", report_id)
+                    return
+
+                obs_result = await session.execute(
+                    select(Observation).where(Observation.report_id == report_id)
+                )
+                observations: List[Observation] = list(obs_result.scalars().all())
+
+                if not observations:
+                    logger.info("No observations for report %s – skipping graph/memory sync", report_id)
+                    return
+
+                abnormal_obs = [obs for obs in observations if obs.is_abnormal]
+                normal_count = len(observations) - len(abnormal_obs)
+                uid = str(user_id)
+
+                # ---- 2. Knowledge Graph sync (Neo4j) — abnormal only ----
+                graph_service = get_graph_service()
+                if graph_service.client is not None:
+                    try:
+                        # Episode about the upload
+                        await graph_service.add_user_episode(
+                            user_id=uid,
+                            content=(
+                                f"uploaded medical report: {report.filename} "
+                                f"(Type: {report.doc_type or 'unknown'})"
+                            ),
+                            source="document_upload",
+                            timestamp=(
+                                report.uploaded_at.isoformat()
+                                if report.uploaded_at
+                                else datetime.utcnow().isoformat()
+                            ),
+                        )
+
+                        # Only clinically relevant (abnormal) observations
+                        obs_texts = [
+                            f"Report {report.filename}: {len(observations)} total observations, "
+                            f"{len(abnormal_obs)} abnormal, {normal_count} normal"
+                        ]
+                        for obs in abnormal_obs:
+                            obs_texts.append(
+                                f"{obs.metric_name}: {obs.value} {obs.unit} "
+                                f"(flagged {obs.flag or 'abnormal'})"
+                            )
+
+                        await graph_service.add_user_facts(
+                            user_id=uid,
+                            facts=obs_texts,
+                            source=f"report_{report.filename}",
+                        )
+                        logger.info(
+                            "Graph sync complete for report %s (%d abnormal facts)",
+                            report_id, len(abnormal_obs),
+                        )
+                    except Exception as e:
+                        logger.warning("Graph sync failed for report %s: %s", report_id, e)
+                else:
+                    logger.debug("Graph service unavailable – skipping graph sync for report %s", report_id)
+
+                # ---- 3. Memory sync (Mem0) — summary + abnormal findings ----
+                memory_service = get_memory_service()
+                if memory_service.is_available:
+                    try:
+                        # Report-level summary
+                        summary_parts = [
+                            f"report {report.filename} processed",
+                            f"{len(observations)} observations extracted",
+                            f"{len(abnormal_obs)} abnormal and {normal_count} normal flags",
+                        ]
+                        if report.doc_type:
+                            summary_parts.append(f"document type {report.doc_type}")
+                        report_summary = "; ".join(summary_parts)
+
+                        await memory_service.add(
+                            content=f"report inference summary: {report_summary}",
+                            user_id=uid,
+                            metadata={
+                                "source": "report_inference",
+                                "report_id": str(report_id),
+                                "doc_type": report.doc_type,
+                            },
+                        )
+
+                        # Batch abnormal findings into one memory
+                        if abnormal_obs:
+                            abnormal_lines = []
+                            for obs in abnormal_obs[:12]:
+                                abnormal_lines.append(
+                                    f"{obs.metric_name} measured {obs.value} {obs.unit} "
+                                    f"flagged {obs.flag or 'abnormal'}"
+                                )
+                            combined = (
+                                f"report inference abnormal findings from {report.filename}:\n- "
+                                + "\n- ".join(abnormal_lines)
+                            )
+                            await memory_service.add(
+                                content=combined,
+                                user_id=uid,
+                                metadata={
+                                    "source": "report_inference",
+                                    "report_id": str(report_id),
+                                    "kind": "abnormal_findings_batch",
+                                    "abnormal_count": len(abnormal_obs),
+                                },
+                            )
+
+                        logger.info(
+                            "Memory sync complete for report %s (%d abnormal findings)",
+                            report_id, len(abnormal_obs),
+                        )
+                    except Exception as e:
+                        logger.warning("Memory sync failed for report %s: %s", report_id, e)
+                else:
+                    logger.debug("Memory service unavailable – skipping Mem0 sync for report %s", report_id)
+
+            logger.info("Background sync complete for report %s", report_id)
+
+        except Exception as e:
+            logger.error("Background sync failed for report %s: %s", report_id, e)

backend/app/services/graph_service.py

@@ -1,16 +1,23 @@
 import logging
 import asyncio
+import inspect
+from datetime import datetime, timezone
 from typing import List, Dict, Any, Optional
 
 try:
     from graphiti_core import Graphiti
     from graphiti_core.llm_client import OpenAIClient, LLMConfig
+    from graphiti_core.embedder.openai import OpenAIEmbedder, OpenAIEmbedderConfig
+    from graphiti_core.cross_encoder.openai_reranker_client import OpenAIRerankerClient
     GRAPHITI_AVAILABLE = True
 except ImportError:
     GRAPHITI_AVAILABLE = False
     Graphiti = None
     OpenAIClient = None
     LLMConfig = None
+    OpenAIEmbedder = None
+    OpenAIEmbedderConfig = None
+    OpenAIRerankerClient = None
 
 from app.settings import settings
 
@@ -40,6 +47,16 @@ class GraphService:
         self._initialized = True
         logger.info("GraphService initialized (lazy loading client)")
 
+    @staticmethod
+    def _user_node_label(user_id: str) -> str:
+        """Deterministic user node label used for graph tenant scoping."""
+        return f"User_{user_id}"
+
+    @classmethod
+    def _is_user_scoped_result(cls, result: str, user_id: str) -> bool:
+        label = cls._user_node_label(user_id)
+        return label.lower() in result.lower()
+
     async def initialize(self):
         """
         Initialize the Neo4j driver and Graphiti client asynchronously.
@@ -53,28 +70,64 @@ class GraphService:
             return
 
         try:
-            logger.info("Initializing Graphiti with Neo4j and Ollama...")
-
-            # 1. Initialize LLM Client (Ollama via OpenAI compatible endpoint)
-            llm_config = LLMConfig(
-                api_key="ollama",  # Dummy key for Ollama
-                base_url=f"{settings.OLLAMA_BASE_URL}/v1",
-                model=settings.OLLAMA_MODEL,
-                temperature=0.1,
-                max_tokens=4096
-            )
+            use_groq = self._should_use_groq_llm()
+            if use_groq:
+                logger.info("Initializing Graphiti with Neo4j and Groq (OpenAI-compatible)...")
+                llm_config = LLMConfig(
+                    api_key=settings.groq_api_key,
+                    base_url=settings.groq_api_base,
+                    model=settings.GRAPHITI_GROQ_MODEL,
+                    small_model=settings.GRAPHITI_GROQ_MODEL,
+                    temperature=0.1,
+                    max_tokens=4096,
+                )
+            else:
+                logger.info("Initializing Graphiti with Neo4j and Ollama...")
+                # Ollama via OpenAI-compatible endpoint.
+                llm_config = LLMConfig(
+                    api_key="ollama",  # Dummy key for Ollama
+                    base_url=f"{settings.OLLAMA_BASE_URL}/v1",
+                    model=settings.OLLAMA_MODEL,
+                    small_model=settings.OLLAMA_MODEL,
+                    temperature=0.1,
+                    max_tokens=4096,
+                )
 
             llm_client = OpenAIClient(
-                config=llm_config
+                config=llm_config,
+                max_tokens=2048,
             )
 
-            # 2. Initialize Graphiti Client with Neo4j connection
+            # 2. Initialize embedder explicitly to avoid default OpenAI embedder
+            # requiring OPENAI_API_KEY. Use Ollama's OpenAI-compatible embeddings API.
+            embedder_client = None
+            if OpenAIEmbedder and OpenAIEmbedderConfig:
+                embedder_client = OpenAIEmbedder(
+                    config=OpenAIEmbedderConfig(
+                        embedding_model=settings.MEM0_EMBED_MODEL,
+                        embedding_dim=768,  # `nomic-embed-text` dimension
+                        api_key="ollama",
+                        base_url=f"{settings.OLLAMA_BASE_URL}/v1",
+                    )
+                )
+            else:
+                logger.warning(
+                    "Graphiti OpenAIEmbedder not available; falling back to Graphiti default embedder"
+                )
+
+            cross_encoder_client = None
+            if OpenAIRerankerClient:
+                cross_encoder_client = OpenAIRerankerClient(config=llm_config)
+
+            # 3. Initialize Graphiti Client with Neo4j connection
             # Pass uri, user, password directly - Graphiti creates the driver internally
             self.client = Graphiti(
                 uri=settings.NEO4J_URI,
                 user=settings.NEO4J_USER,
                 password=settings.NEO4J_PASSWORD,
-                llm_client=llm_client
+                llm_client=llm_client,
+                embedder=embedder_client,
+                cross_encoder=cross_encoder_client,
             )
 
             # Build indices (this is an async operation)
@@ -87,7 +140,51 @@ class GraphService:
             # Service will be degraded (graph features won't work)
             self.client = None
 
-    async def add_episode(self, content: str, source: str = "user_input", timestamp: Optional[str] = None):
+    @staticmethod
+    def _should_use_groq_llm() -> bool:
+        """
+        Prefer Groq whenever an API key is configured.
+        Ollama remains fallback when no Groq key is present.
+        """
+        return bool(settings.groq_api_key)
+
+    @staticmethod
+    async def _await_if_needed(value: Any) -> Any:
+        """
+        Graphiti SDK methods differ by version: some are sync, some are async.
+        Await only when the returned object is awaitable.
+        """
+        if inspect.isawaitable(value):
+            return await value
+        return value
+
+    @staticmethod
+    def _coerce_reference_time(timestamp: Optional[str]) -> datetime:
+        """
+        Graphiti requires a datetime reference_time. Accept optional ISO string
+        from callers and default to current UTC when not provided.
+        """
+        if isinstance(timestamp, str) and timestamp.strip():
+            raw = timestamp.strip()
+            # Support trailing Z timestamps.
+            if raw.endswith("Z"):
+                raw = raw[:-1] + "+00:00"
+            try:
+                parsed = datetime.fromisoformat(raw)
+                if parsed.tzinfo is None:
+                    return parsed.replace(tzinfo=timezone.utc)
+                return parsed
+            except Exception:
+                logger.warning("Invalid timestamp passed to GraphService.add_episode: %s", timestamp)
+        return datetime.now(timezone.utc)
+
+    async def add_episode(
+        self,
+        content: str,
+        source: str = "user_input",
+        timestamp: Optional[str] = None,
+        group_id: Optional[str] = None,
+    ):
         """
         Add a new episode to the knowledge graph.
 
@@ -100,16 +197,17 @@ class GraphService:
             logger.warning("GraphService not initialized, skipping add_episode")
             return
 
-        def _sync_add():
-            self.client.add_episode(
-                name=f"Episode from {source}",
-                episode_body=content,
-                source_description=source,
-                reference_time=timestamp
-            )
-
         try:
-            await asyncio.to_thread(_sync_add)
+            reference_time = self._coerce_reference_time(timestamp)
+            await self._await_if_needed(
+                self.client.add_episode(
+                    name=f"Episode from {source}",
+                    episode_body=content,
+                    source_description=source,
+                    reference_time=reference_time,
+                    group_id=group_id,
+                )
+            )
             logger.info(f"Added episode to graph from source: {source}")
         except Exception as e:
             logger.error(f"Error adding episode to graph: {e}")
@@ -126,18 +224,73 @@ class GraphService:
         content = "Medical System Observations:\n- " + "\n- ".join(observations)
         await self.add_episode(content, source=source)
 
-    async def search(self, query: str, limit: int = 10) -> List[str]:
+    async def add_user_episode(
+        self,
+        user_id: str,
+        content: str,
+        source: str = "user_input",
+        timestamp: Optional[str] = None,
+    ) -> None:
+        """
+        Add an episode that is explicitly scoped to a single user.
+        """
+        user_label = self._user_node_label(user_id)
+        scoped_content = f"[{user_label}] {content}"
+        scoped_source = f"{source}|{user_label}"
+        await self.add_episode(
+            scoped_content,
+            source=scoped_source,
+            timestamp=timestamp,
+            group_id=user_id,
+        )
+
+    async def add_user_facts(
+        self,
+        user_id: str,
+        facts: List[str],
+        source: str = "profile_sync",
+        timestamp: Optional[str] = None,
+    ) -> bool:
+        """
+        Add a batch of user-scoped facts as one episode.
+        """
+        if not facts:
+            return False
+        user_label = self._user_node_label(user_id)
+        content = f"{user_label} profile facts:\n- " + "\n- ".join(facts)
+        await self.add_user_episode(
+            user_id=user_id,
+            content=content,
+            source=source,
+            timestamp=timestamp,
+        )
+        return True
+
+    async def search(
+        self,
+        query: str,
+        limit: int = 10,
+        group_ids: Optional[List[str]] = None,
+    ) -> List[str]:
         """
         Search the knowledge graph for relevant facts.
         """
         if not self.client:
             return []
 
-        def _sync_search():
-            # Graphiti search returns SearchResult objects
-            results = self.client.search(query, limit=limit)
+        try:
+            # Graphiti parameter name changed across versions (`limit` vs `num_results`).
+            search_kwargs: Dict[str, Any] = {}
+            if group_ids:
+                search_kwargs["group_ids"] = group_ids
+
+            try:
+                raw_results = self.client.search(query, num_results=limit, **search_kwargs)
+            except TypeError:
+                raw_results = self.client.search(query, limit=limit, **search_kwargs)
+
+            results = await self._await_if_needed(raw_results)
 
-            # Format results into strings
             formatted_results = []
             if results and hasattr(results, 'edges'):
                 for edge in results.edges:
@@ -145,30 +298,64 @@ class GraphService:
                         f"{edge.source_node.name} -> {edge.relation} -> {edge.target_node.name}"
                     )
             elif isinstance(results, list):
-                # Handle case where it might return a list directly
                 for item in results:
-                    formatted_results.append(str(item))
+                    # Newer Graphiti search returns EntityEdge objects (no source/target names).
+                    if hasattr(item, "fact") and hasattr(item, "name"):
+                        relation = getattr(item, "name", "states") or "states"
+                        fact = getattr(item, "fact", None)
+                        if fact:
+                            formatted_results.append(f"System -> {relation} -> {fact}")
+                            continue
+                    if (
+                        hasattr(item, "source_node_uuid")
+                        and hasattr(item, "target_node_uuid")
+                        and hasattr(item, "name")
+                    ):
+                        formatted_results.append(
+                            f"{item.source_node_uuid} -> {item.name} -> {item.target_node_uuid}"
+                        )
+                    else:
+                        formatted_results.append(str(item))
 
             return formatted_results
-
-        try:
-            return await asyncio.to_thread(_sync_search)
         except Exception as e:
             logger.error(f"Error searching graph: {e}")
             return []
 
+    async def search_user(self, user_id: str, query: str, limit: int = 10) -> List[str]:
+        """
+        Search graph facts and return only facts scoped to a specific user.
+
+        Uses ``group_ids`` to scope the Graphiti query.  A secondary client-
+        side filter removes any leaked cross-user data.  If nothing passes
+        the filter, an empty list is returned (never unfiltered results).
+        """
+        scoped_query = f"{self._user_node_label(user_id)} {query}".strip()
+        results = await self.search(scoped_query, limit=limit, group_ids=[user_id])
+        filtered = [item for item in results if self._is_user_scoped_result(item, user_id)]
+        return filtered[:limit]
+
     async def close(self):
         """Close the Neo4j driver"""
-        # Graphiti driver doesn't explicitly expose close, but we can try
-        if self.client and self.client.graph_driver:
-            try:
-                if hasattr(self.client.graph_driver, 'close'):
-                    await asyncio.to_thread(self.client.graph_driver.close)
-                elif hasattr(self.client.graph_driver, 'driver'):
-                     await asyncio.to_thread(self.client.graph_driver.driver.close)
-                logger.info("Graphiti driver closed")
-            except Exception as e:
-                logger.warning(f"Error closing graph driver: {e}")
+        if not self.client:
+            return
+
+        try:
+            # Newer Graphiti versions expose `close()` directly on client.
+            if hasattr(self.client, "close"):
+                await self._await_if_needed(self.client.close())
+            # Backward compatibility for older client shapes.
+            elif hasattr(self.client, "graph_driver"):
+                graph_driver = self.client.graph_driver
+                if hasattr(graph_driver, "close"):
+                    await self._await_if_needed(graph_driver.close())
+                elif hasattr(graph_driver, "driver"):
+                    await self._await_if_needed(graph_driver.driver.close())
+            elif hasattr(self.client, "driver") and hasattr(self.client.driver, "close"):
+                await self._await_if_needed(self.client.driver.close())
+            logger.info("Graphiti driver closed")
+        except Exception as e:
+            logger.warning(f"Error closing graph driver: {e}")
 
 # Global instance
 graph_service = GraphService()

backend/app/services/grok_recommendation_service.py

@@ -517,7 +517,8 @@ async def _gather_user_context(user_id: str, db: AsyncSession) -> Dict[str, Any]
                 return []
             
             # Search for relevant medical knowledge
-            results = await graph_service.search(
+            results = await graph_service.search_user(
+                user_id=user_id,
                 query="health conditions medications recommendations risk factors",
                 limit=10
             )

backend/app/services/llm_service.py

@@ -1,11 +1,16 @@
 """
-LLM Service - Ollama streaming with Gemini fallback
+LLM Service - OpenRouter primary with multi-tier fallback
 
-Provides async streaming generation using MedGemma via Ollama,
-with automatic fallback to Gemini API if Ollama is unavailable.
+Provider priority:
+  1. OpenRouter  (openrouter/pony-alpha)
+  2. OpenRouter  (upstage/solar-pro-3:free)  – free fallback
+  3. Gemini      (gemini-flash-latest)        – Google fallback
+  4. Ollama      (MedGemma via GGUF)          – local last resort
+
+Uses the OpenAI Python SDK pointed at OpenRouter's OpenAI-compatible endpoint.
 """
 import asyncio
-from typing import AsyncGenerator, Optional
+from typing import AsyncGenerator, Optional, List, Dict, Any
 import logging
 
 from app.settings import settings
@@ -17,8 +22,10 @@ logger = logging.getLogger(__name__)
 # inside Docker).
 _resolved_ollama_base_url: Optional[str] = None
 
-# Medical system prompt for the LLM
-MEDICAL_SYSTEM_PROMPT = """You are a knowledgeable and empathetic AI medical health assistant. 
+# ---------------------------------------------------------------------------
+# System prompt
+# ---------------------------------------------------------------------------
+MEDICAL_SYSTEM_PROMPT = """You are a knowledgeable and empathetic AI medical health assistant.
 Your role is to help users understand their health data, lab results, and medical information.
 
 Guidelines:
@@ -29,6 +36,14 @@ Guidelines:
 - Never diagnose conditions - only explain what the data indicates
 - Be supportive and non-alarmist while being honest about concerning values
 
+IMPORTANT - Source Attribution Rules:
+When you use information from the context provided below, you MUST cite the source inline:
+- For report data, say: "Based on your report '[filename]' ..."  or  "From your uploaded report ..."
+- For memory/preferences, say: "From your health profile, I recall that ..."  or  "According to your stored preferences ..."
+- For knowledge graph facts, say: "From the medical knowledge graph, I can see that ..."  or  "Based on your medical history graph ..."
+- If combining multiple sources, mention each one.
+- If you don't have relevant data, say so clearly.
+
 You have access to the user's personal health data provided in the context below.
 Answer based on their specific data when available."""
 
@@ -36,200 +51,305 @@ Answer based on their specific data when available."""
 class LLMService:
     """
     LLM Service for generating responses with streaming support.
-    
-    Primary: Ollama (MedGemma)
-    Fallback: Gemini API
+
+    Priority chain:
+      1. OpenRouter  – pony-alpha  (primary)
+      2. OpenRouter  – solar-pro-3:free  (fallback)
+      3. Gemini API  (Google fallback)
+      4. Ollama      (local last-resort)
     """
-    
+
     def __init__(self):
         self._ollama_available: Optional[bool] = None
         self._gemini_client = None
-    
+        self._openrouter_client = None
+
+    # ------------------------------------------------------------------
+    # OpenRouter (OpenAI-compatible SDK)
+    # ------------------------------------------------------------------
+    def _get_openrouter_client(self):
+        """Lazy-init the OpenAI client pointed at OpenRouter."""
+        if self._openrouter_client is None:
+            from openai import AsyncOpenAI
+
+            self._openrouter_client = AsyncOpenAI(
+                base_url=settings.OPENROUTER_BASE_URL,
+                api_key=settings.OPENROUTER_API_KEY,
+                default_headers={
+                    "HTTP-Referer": settings.frontend_origin,
+                    "X-Title": "Lumea Health Assistant",
+                },
+                timeout=settings.OPENROUTER_TIMEOUT,
+            )
+        return self._openrouter_client
+
+    # ------------------------------------------------------------------
+    # Ollama health check (kept for last-resort fallback)
+    # ------------------------------------------------------------------
     async def check_ollama_health(self) -> bool:
         """Check if Ollama is available and the model is loaded."""
         global _resolved_ollama_base_url
 
-        # Prefer a previously successful URL if we discovered one.
         base_url = _resolved_ollama_base_url or settings.OLLAMA_BASE_URL
 
         try:
             import ollama
             client = ollama.AsyncClient(host=base_url)
-            # Try to list models to check connectivity
-            models = await asyncio.wait_for(
-                client.list(),
-                timeout=5.0
-            )
-            # We only care that the server is reachable. The model might not be
-            # pulled yet; Ollama will automatically pull it on first use.
-            model_names = [m.get('name', '') for m in models.get('models', [])]
-            if settings.OLLAMA_MODEL in model_names or any(
-                settings.OLLAMA_MODEL.split(':')[0] in m for m in model_names
-            ):
-                logger.info(f"Ollama available with model {settings.OLLAMA_MODEL} at {base_url}")
-            else:
-                logger.warning(
-                    "Ollama reachable at %s but model %s not found. "
-                    "Available models: %s. The server will attempt to pull the "
-                    "model on first use.",
-                    base_url,
-                    settings.OLLAMA_MODEL,
-                    model_names,
-                )
-
+            await asyncio.wait_for(client.list(), timeout=5.0)
             _resolved_ollama_base_url = base_url
+            logger.info("Ollama available at %s", base_url)
             return True
         except Exception as e:
-            logger.warning(f"Ollama not available at {base_url}: {e}")
+            logger.warning("Ollama not available at %s: %s", base_url, e)
 
-            # Common misconfig: using http://localhost:11434 from inside Docker.
-            # If we see that, try host.docker.internal automatically so the
-            # container can reach the host's Ollama daemon.
             if "localhost" in base_url or "127.0.0.1" in base_url:
                 fallback_url = base_url.replace("localhost", "host.docker.internal").replace(
                     "127.0.0.1", "host.docker.internal"
                 )
                 try:
                     import ollama
-
-                    logger.info(
-                        "Retrying Ollama health check using %s "
-                        "(likely running from inside Docker).",
-                        fallback_url,
-                    )
                     client = ollama.AsyncClient(host=fallback_url)
                     await asyncio.wait_for(client.list(), timeout=5.0)
                     _resolved_ollama_base_url = fallback_url
                     logger.info("Ollama available at %s", fallback_url)
                     return True
                 except Exception as e2:
-                    logger.warning(
-                        "Fallback Ollama check at %s also failed: %s",
-                        fallback_url,
-                        e2,
-                    )
+                    logger.warning("Fallback Ollama check at %s also failed: %s", fallback_url, e2)
 
             return False
-    
+
+    # ------------------------------------------------------------------
+    # Provider resolution
+    # ------------------------------------------------------------------
     async def _ensure_provider(self) -> str:
-        """Determine which provider to use. Returns 'ollama', 'gemini', or 'disabled'."""
-        # If Gemini is configured, use it directly - no need to check Ollama
+        """
+        Determine which provider to use.
+
+        Returns one of: 'openrouter', 'gemini', 'ollama', 'disabled'.
+        """
+        # 1. OpenRouter (primary) – needs API key
+        if settings.OPENROUTER_API_KEY:
+            return "openrouter"
+
+        # 2. Gemini – needs API key
         if settings.USE_GEMINI_FALLBACK and settings.GEMINI_API_KEY:
-            logger.info("Using Gemini API (configured)")
+            logger.info("OpenRouter not configured; falling back to Gemini")
             return "gemini"
-        
-        # Only check Ollama if Gemini is not configured
+
+        # 3. Ollama – local, needs running daemon
         if self._ollama_available is None:
             self._ollama_available = await self.check_ollama_health()
-        
         if self._ollama_available:
+            logger.info("Using Ollama as last-resort provider")
             return "ollama"
-        
-        # Make LLM optional: return a friendly message rather than hard-failing
-        # core app features when neither provider is configured.
+
         return "disabled"
-    
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
     async def stream_generate(
         self,
         user_message: str,
         context: str,
-        chat_history: Optional[list] = None
+        chat_history: Optional[list] = None,
     ) -> AsyncGenerator[str, None]:
-        """
-        Generate a streaming response from the LLM.
-        
-        Args:
-            user_message: The user's question/message
-            context: Retrieved context from RAG (user's health data)
-            chat_history: Optional list of previous messages
-            
-        Yields:
-            String tokens as they are generated
-        """
+        """Yield tokens as they are generated."""
         provider = await self._ensure_provider()
-        
-        # Build the full prompt
-        full_prompt = self._build_prompt(user_message, context, chat_history)
-        
-        if provider == "ollama":
-            async for token in self._stream_ollama(full_prompt):
+        messages = self._build_messages(user_message, context, chat_history)
+
+        if provider == "openrouter":
+            async for token in self._stream_openrouter(messages):
                 yield token
         elif provider == "gemini":
-            async for token in self._stream_gemini(full_prompt):
+            prompt = self._build_prompt(user_message, context, chat_history)
+            async for token in self._stream_gemini(prompt):
+                yield token
+        elif provider == "ollama":
+            prompt = self._build_prompt(user_message, context, chat_history)
+            async for token in self._stream_ollama(prompt):
                 yield token
         else:
             yield (
                 "LLM is not configured. "
-                "Start Ollama (and set `OLLAMA_BASE_URL`/`OLLAMA_MODEL`) "
-                "or set `GEMINI_API_KEY` with `USE_GEMINI_FALLBACK=true`."
+                "Set `OPENROUTER_API_KEY` for the primary provider, "
+                "or configure Gemini / Ollama as fallbacks."
             )
-    
+
+    async def generate(
+        self,
+        user_message: str,
+        context: str,
+        chat_history: Optional[list] = None,
+    ) -> str:
+        """Generate a complete (non-streaming) response."""
+        parts: list[str] = []
+        async for token in self.stream_generate(user_message, context, chat_history):
+            parts.append(token)
+        return "".join(parts)
+
+    # ------------------------------------------------------------------
+    # Message / prompt builders
+    # ------------------------------------------------------------------
+    def _build_messages(
+        self,
+        user_message: str,
+        context: str,
+        chat_history: Optional[list] = None,
+    ) -> List[Dict[str, str]]:
+        """Build OpenAI-style messages array for OpenRouter."""
+        messages: List[Dict[str, str]] = [
+            {"role": "system", "content": MEDICAL_SYSTEM_PROMPT},
+        ]
+
+        if context:
+            messages.append({
+                "role": "system",
+                "content": f"--- USER'S HEALTH DATA ---\n{context}\n--- END HEALTH DATA ---",
+            })
+
+        if chat_history:
+            for msg in chat_history[-10:]:
+                role = msg.get("role", "user")
+                messages.append({"role": role, "content": msg.get("content", "")})
+
+        messages.append({"role": "user", "content": user_message})
+        return messages
+
     def _build_prompt(
         self,
         user_message: str,
         context: str,
-        chat_history: Optional[list] = None
+        chat_history: Optional[list] = None,
     ) -> str:
-        """Build the full prompt with system instructions, context, and history."""
-        prompt_parts = [MEDICAL_SYSTEM_PROMPT]
-        
+        """Build a flat prompt string (Gemini / Ollama)."""
+        parts = [MEDICAL_SYSTEM_PROMPT]
+
         if context:
-            prompt_parts.append(f"\n\n--- USER'S HEALTH DATA ---\n{context}\n--- END HEALTH DATA ---")
-        
+            parts.append(f"\n\n--- USER'S HEALTH DATA ---\n{context}\n--- END HEALTH DATA ---")
+
         if chat_history:
-            prompt_parts.append("\n\n--- CONVERSATION HISTORY ---")
-            for msg in chat_history[-10:]:  # Last 10 messages
+            parts.append("\n\n--- CONVERSATION HISTORY ---")
+            for msg in chat_history[-10:]:
                 role = "User" if msg.get("role") == "user" else "Assistant"
-                prompt_parts.append(f"{role}: {msg.get('content', '')}")
-            prompt_parts.append("--- END HISTORY ---")
-        
-        prompt_parts.append(f"\n\nUser: {user_message}\n\nAssistant:")
-        
-        return "\n".join(prompt_parts)
-    
+                parts.append(f"{role}: {msg.get('content', '')}")
+            parts.append("--- END HISTORY ---")
+
+        parts.append(f"\n\nUser: {user_message}\n\nAssistant:")
+        return "\n".join(parts)
+
+    # ------------------------------------------------------------------
+    # OpenRouter streaming (primary + in-band fallback model)
+    # ------------------------------------------------------------------
+    async def _stream_openrouter(
+        self,
+        messages: List[Dict[str, str]],
+    ) -> AsyncGenerator[str, None]:
+        """Stream from OpenRouter, falling back through models then providers."""
+        models_to_try = [
+            settings.OPENROUTER_MODEL,           # openrouter/pony-alpha
+            settings.OPENROUTER_FALLBACK_MODEL,   # upstage/solar-pro-3:free
+        ]
+
+        last_error: Optional[Exception] = None
+
+        for model in models_to_try:
+            try:
+                client = self._get_openrouter_client()
+                logger.info("Streaming from OpenRouter model: %s", model)
+
+                stream = await client.chat.completions.create(
+                    model=model,
+                    messages=messages,
+                    stream=True,
+                    temperature=0.7,
+                    top_p=0.9,
+                    max_tokens=2048,
+                )
+
+                had_content = False
+                async for chunk in stream:
+                    delta = chunk.choices[0].delta if chunk.choices else None
+                    if delta and delta.content:
+                        had_content = True
+                        yield delta.content
+
+                if had_content:
+                    return  # success – done
+                else:
+                    logger.warning("OpenRouter model %s returned empty stream", model)
+
+            except Exception as e:
+                last_error = e
+                logger.warning("OpenRouter model %s failed: %s", model, e)
+                continue
+
+        # All OpenRouter models failed – cascade to Gemini → Ollama
+        logger.error("All OpenRouter models exhausted. Cascading to Gemini/Ollama...")
+
+        # Try Gemini
+        if settings.USE_GEMINI_FALLBACK and settings.GEMINI_API_KEY:
+            logger.info("Falling back to Gemini after OpenRouter failure")
+            prompt = "\n".join(
+                m["content"] for m in messages
+            )
+            async for token in self._stream_gemini(prompt):
+                yield token
+            return
+
+        # Try Ollama (last resort)
+        if self._ollama_available is None:
+            self._ollama_available = await self.check_ollama_health()
+        if self._ollama_available:
+            logger.info("Falling back to Ollama after OpenRouter failure")
+            prompt = "\n".join(
+                m["content"] for m in messages
+            )
+            async for token in self._stream_ollama(prompt):
+                yield token
+            return
+
+        yield f"Error: All LLM providers failed. Last error: {last_error}"
+
+    # ------------------------------------------------------------------
+    # Ollama streaming (last resort)
+    # ------------------------------------------------------------------
     async def _stream_ollama(self, prompt: str) -> AsyncGenerator[str, None]:
         """Stream response from Ollama."""
         import ollama
-        
-        # Use any resolved URL from health checks, falling back to settings.
+
         host = _resolved_ollama_base_url or settings.OLLAMA_BASE_URL
         client = ollama.AsyncClient(host=host)
-        
+
         try:
             response = await client.chat(
                 model=settings.OLLAMA_MODEL,
                 messages=[{"role": "user", "content": prompt}],
                 stream=True,
-                options={
-                    "temperature": 0.7,
-                    "top_p": 0.9,
-                }
+                options={"temperature": 0.7, "top_p": 0.9},
             )
-            
+
             async for chunk in response:
                 if chunk.get("message", {}).get("content"):
                     yield chunk["message"]["content"]
-                    
+
         except Exception as e:
-            logger.error(f"Ollama streaming error: {e}")
-            # Mark as unavailable and try fallback
+            logger.error("Ollama streaming error: %s", e)
             self._ollama_available = False
-            if settings.USE_GEMINI_FALLBACK and settings.GEMINI_API_KEY:
-                logger.info("Falling back to Gemini after Ollama error")
-                async for token in self._stream_gemini(prompt):
-                    yield token
-            else:
-                yield f"Error: Unable to generate response. {str(e)}"
-    
+            yield f"Error: Ollama failed – {e}"
+
+    # ------------------------------------------------------------------
+    # Gemini streaming
+    # ------------------------------------------------------------------
     async def _stream_gemini(self, prompt: str) -> AsyncGenerator[str, None]:
         """Stream response from Gemini API."""
         try:
             import google.generativeai as genai
-            
+
             if not self._gemini_client:
                 genai.configure(api_key=settings.GEMINI_API_KEY)
                 self._gemini_client = genai.GenerativeModel("gemini-flash-latest")
-            
+
             response = await asyncio.to_thread(
                 lambda: self._gemini_client.generate_content(
                     prompt,
@@ -238,35 +358,22 @@ class LLMService:
                         "temperature": 0.7,
                         "top_p": 0.9,
                         "max_output_tokens": 2048,
-                    }
+                    },
                 )
             )
-            
+
             for chunk in response:
                 if chunk.text:
                     yield chunk.text
-                    
+
         except Exception as e:
-            logger.error(f"Gemini streaming error: {e}")
-            yield f"Error: Unable to generate response. {str(e)}"
-    
-    async def generate(
-        self,
-        user_message: str,
-        context: str,
-        chat_history: Optional[list] = None
-    ) -> str:
-        """
-        Generate a complete (non-streaming) response.
-        Useful for testing or when streaming is not needed.
-        """
-        response_parts = []
-        async for token in self.stream_generate(user_message, context, chat_history):
-            response_parts.append(token)
-        return "".join(response_parts)
+            logger.error("Gemini streaming error: %s", e)
+            yield f"Error: Gemini failed ��� {e}"
 
 
-# Singleton instance
+# ---------------------------------------------------------------------------
+# Singleton
+# ---------------------------------------------------------------------------
 _llm_service: Optional[LLMService] = None
 
 

backend/app/services/memory_service.py

@@ -1,7 +1,11 @@
 import logging
 import asyncio
+import random
+import re
 import threading
-from typing import List, Dict, Any, Optional
+import copy
+import time
+from typing import List, Dict, Any, Optional, Tuple
 from app.settings import settings
 
 # Configure logger
@@ -23,10 +27,78 @@ def _import_mem0_memory():
             return None
 
 
+# ---------------------------------------------------------------------------
+# Groq / LLM call throttle
+# ---------------------------------------------------------------------------
+
+def _extract_retry_seconds(error_text: str) -> float:
+    """Parse 'try again in <N>s' from Groq 429 responses."""
+    match = re.search(r"try again in ([0-9.]+)s", error_text, re.IGNORECASE)
+    if match:
+        try:
+            return float(match.group(1))
+        except (TypeError, ValueError):
+            pass
+    return 0.0
+
+
+def _is_rate_limit_error(error_text: str) -> bool:
+    """Check if an error string indicates a Groq/OpenAI 429 rate limit."""
+    lower = error_text.lower()
+    return "rate_limit" in lower or "429" in lower or "rate limit" in lower
+
+
+class _GroqThrottle:
+    """
+    Async token-bucket style throttle for outbound Mem0→Groq calls.
+
+    Enforces a minimum interval between consecutive calls so the
+    aggregate tokens-per-minute stays under Groq's free-tier quota.
+    All callers in the process share a single lock.
+    """
+
+    def __init__(self, min_interval: float):
+        self._min_interval = max(min_interval, 0.0)
+        self._lock: Optional[asyncio.Lock] = None
+        self._last_call: float = 0.0
+
+    def _ensure_lock(self) -> asyncio.Lock:
+        """Lazily create the lock inside the running event loop."""
+        if self._lock is None:
+            self._lock = asyncio.Lock()
+        return self._lock
+
+    async def acquire(self) -> None:
+        """Wait until enough time has elapsed since the last call."""
+        lock = self._ensure_lock()
+        async with lock:
+            now = time.monotonic()
+            elapsed = now - self._last_call
+            if elapsed < self._min_interval:
+                wait = self._min_interval - elapsed
+                logger.debug("GroqThrottle: waiting %.2fs before next Mem0 call", wait)
+                await asyncio.sleep(wait)
+            self._last_call = time.monotonic()
+
+    async def backoff(self, seconds: float) -> None:
+        """Push the next-allowed timestamp forward (e.g. after a 429)."""
+        lock = self._ensure_lock()
+        async with lock:
+            self._last_call = time.monotonic() + seconds - self._min_interval
+
+
+# Module-level throttle shared by every MemoryService instance.
+_groq_throttle = _GroqThrottle(settings.MEM0_CALL_INTERVAL_SECONDS)
+
+
 class MemoryService:
     """
     Service for interacting with Mem0 memory layer.
     Stores unstructured user preferences, facts, and conversation history.
+
+    All outbound calls are throttled through ``_groq_throttle`` so that
+    aggregate Groq TPM usage stays within quota.  Individual ``add()``
+    calls self-retry with exponential back-off on 429 errors.
     """
 
     _instance = None
@@ -41,42 +113,176 @@ class MemoryService:
         if self._initialized:
             return
 
-        self.config = {
+        # Lazy initialization of the Memory client
+        self._memory_cls = _import_mem0_memory()
+        self.memory_client = None
+        self._client_lock = threading.Lock()
+        self._last_init_error: Optional[str] = None
+        self._last_init_attempt_at: float = 0.0
+        self._init_retry_cooldown_seconds = 10
+        self._active_config_name: Optional[str] = None
+
+        self.last_error: Optional[str] = None
+        self.config_candidates = self._build_config_candidates()
+        # For compatibility/debugging: populated with the selected config after init.
+        self.config: Optional[Dict[str, Any]] = None
+        self._initialized = True
+        logger.info("MemoryService initialized (lazy loading client)")
+
+    @property
+    def is_available(self) -> bool:
+        return self._memory_cls is not None
+
+    def _base_store_config(self) -> Dict[str, Any]:
+        return {
             "vector_store": {
                 "provider": "chroma",
                 "config": {
                     "collection_name": settings.MEM0_COLLECTION,
-                    "path": settings.CHROMA_PERSIST_DIR,
-                }
-            },
-            "llm": {
-                "provider": "ollama",
-                "config": {
-                    "model": settings.OLLAMA_MODEL,
-                    "base_url": settings.OLLAMA_BASE_URL,
-                    "timeout": settings.OLLAMA_TIMEOUT,
-                }
+                    "path": settings.MEM0_CHROMA_DIR,  # Separate from RAG's ChromaDB
+                },
             },
             "graph_store": {
                 "provider": "neo4j",
                 "config": {
                     "url": settings.NEO4J_URI,
                     "username": settings.NEO4J_USER,
-                    "password": settings.NEO4J_PASSWORD
-                }
-            }
+                    "password": settings.NEO4J_PASSWORD,
+                },
+            },
         }
 
-        # Lazy initialization of the Memory client
-        self._memory_cls = _import_mem0_memory()
-        self.memory_client = None
-        self._client_lock = threading.Lock()
-        self._initialized = True
-        logger.info("MemoryService initialized (lazy loading client)")
+    def _build_llm_candidates(self) -> List[Tuple[str, Dict[str, Any]]]:
+        groq_candidates: List[Tuple[str, Dict[str, Any]]] = []
+        ollama_candidates: List[Tuple[str, Dict[str, Any]]] = []
 
-    @property
-    def is_available(self) -> bool:
-        return self._memory_cls is not None
+        # Groq support via OpenAI-compatible config (preferred).
+        if settings.groq_api_key:
+            groq_candidates.append(
+                (
+                    "groq_openai_compat",
+                    {
+                        "provider": "openai",
+                        "config": {
+                            "api_key": settings.groq_api_key,
+                            "model": settings.MEM0_GROQ_MODEL,
+                            "openai_base_url": settings.groq_api_base,
+                            "temperature": 0.1,
+                        },
+                    },
+                )
+            )
+
+        # Only add Ollama candidates if Groq is not preferred or not available.
+        # This prevents noisy "Failed to connect to Ollama" warnings.
+        if not (settings.MEM0_PREFER_GROQ and settings.groq_api_key):
+            ollama_model = settings.OLLAMA_MODEL
+            ollama_url = settings.OLLAMA_BASE_URL
+            ollama_candidates.extend(
+                [
+                    (
+                        "ollama_ollama_base_url",
+                        {
+                            "provider": "ollama",
+                            "config": {
+                                "model": ollama_model,
+                                "ollama_base_url": ollama_url,
+                            },
+                        },
+                    ),
+                    (
+                        "ollama_model_only",
+                        {
+                            "provider": "ollama",
+                            "config": {
+                                "model": ollama_model,
+                            },
+                        },
+                    ),
+                ]
+            )
+
+        return groq_candidates + ollama_candidates
+
+    def _build_embedder_candidates(self) -> List[Tuple[str, Dict[str, Any]]]:
+        # Prefer local sentence-transformers embedder (works without Ollama or external APIs).
+        # Only include Ollama embedder candidates if we're not preferring Groq (i.e., Ollama is expected to run).
+        candidates = [
+            (
+                "huggingface_local",
+                {
+                    "provider": "huggingface",
+                    "config": {
+                        "model": settings.EMBEDDING_MODEL,
+                    },
+                },
+            ),
+        ]
+
+        # Skip Ollama embedder candidates when using Groq for LLM (Ollama likely not running).
+        if not (settings.MEM0_PREFER_GROQ and settings.groq_api_key):
+            embed_model = settings.MEM0_EMBED_MODEL
+            ollama_url = settings.OLLAMA_BASE_URL
+            candidates.extend([
+                (
+                    "ollama_embed_ollama_base_url",
+                    {
+                        "provider": "ollama",
+                        "config": {
+                            "model": embed_model,
+                            "ollama_base_url": ollama_url,
+                        },
+                    },
+                ),
+                (
+                    "ollama_embed_model_only",
+                    {
+                        "provider": "ollama",
+                        "config": {
+                            "model": embed_model,
+                        },
+                    },
+                ),
+            ])
+
+        return candidates
+
+    def _build_config_candidates(self) -> List[Tuple[str, Dict[str, Any]]]:
+        base = self._base_store_config()
+        llm_candidates = self._build_llm_candidates()
+        embedder_candidates = self._build_embedder_candidates()
+
+        configs: List[Tuple[str, Dict[str, Any]]] = []
+        seen_signatures = set()
+
+        for llm_name, llm_config in llm_candidates:
+            # With explicit embedder config
+            for embed_name, embedder_config in embedder_candidates:
+                cfg = copy.deepcopy(base)
+                cfg["llm"] = copy.deepcopy(llm_config)
+                cfg["embedder"] = copy.deepcopy(embedder_config)
+
+                signature = repr(cfg)
+                if signature in seen_signatures:
+                    continue
+                seen_signatures.add(signature)
+                configs.append((f"{llm_name}+{embed_name}", cfg))
+
+            # Fallback: let Mem0 decide embedder defaults
+            cfg = copy.deepcopy(base)
+            cfg["llm"] = copy.deepcopy(llm_config)
+            signature = repr(cfg)
+            if signature not in seen_signatures:
+                seen_signatures.add(signature)
+                configs.append((f"{llm_name}+default_embedder", cfg))
+
+        return configs
+
+    def _set_error(self, message: str) -> None:
+        self.last_error = message
+
+    def _clear_error(self) -> None:
+        self.last_error = None
 
     def _get_client(self):
         """Get or initialize the Mem0 client"""
@@ -88,38 +294,166 @@ class MemoryService:
         if self.memory_client is None:
             with self._client_lock:
                 if self.memory_client is None:
+                    now = time.time()
+                    if (
+                        self._last_init_error
+                        and (now - self._last_init_attempt_at) < self._init_retry_cooldown_seconds
+                    ):
+                        raise RuntimeError(self._last_init_error)
                     try:
                         logger.info("Initializing Mem0 client connection...")
-                        self.memory_client = self._memory_cls.from_config(self.config)
+                        self._last_init_attempt_at = now
+
+                        init_errors = []
+                        for config_name, candidate in self.config_candidates:
+                            try:
+                                self.memory_client = self._memory_cls.from_config(candidate)
+                                self._active_config_name = config_name
+                                self.config = candidate
+                                self._last_init_error = None
+                                self._clear_error()
+                                logger.info(
+                                    "Mem0 client initialized successfully (config=%s)",
+                                    config_name,
+                                )
+                                break
+                            except Exception as candidate_error:
+                                err = f"{config_name}: {candidate_error}"
+                                init_errors.append(err)
+                                logger.warning("Mem0 config attempt failed (%s)", err)
+
+                        if self.memory_client is None:
+                            joined = "; ".join(init_errors) if init_errors else "Unknown Mem0 init error"
+                            self._last_init_error = f"Mem0 initialization failed: {joined}"
+                            raise RuntimeError(self._last_init_error)
                         logger.info("Mem0 client initialized successfully")
                     except Exception as e:
                         logger.error(f"Failed to initialize Mem0 client: {e}")
+                        self._set_error(str(e))
                         raise
         return self.memory_client
 
-    async def add(self, content: str, user_id: str, metadata: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+    async def add(
+        self,
+        content: str,
+        user_id: str,
+        metadata: Optional[Dict[str, Any]] = None,
+        *,
+        _max_retries: Optional[int] = None,
+    ) -> Dict[str, Any]:
         """
         Add a memory for a user asynchronously.
 
+        Automatically throttles outbound Groq calls and retries on 429
+        rate-limit errors with exponential back-off + jitter.
+
         Args:
             content: The text content to remember
             user_id: The user ID (will be used as user_id in Mem0)
             metadata: Optional metadata to attach
+            _max_retries: Override default retry count (settings.MEM0_MAX_RETRIES)
         """
+        max_retries = _max_retries if _max_retries is not None else settings.MEM0_MAX_RETRIES
+        base_backoff = settings.MEM0_RETRY_BASE_SECONDS
+
         def _sync_add():
             client = self._get_client()
             return client.add(content, user_id=user_id, metadata=metadata)
 
-        try:
-            return await asyncio.to_thread(_sync_add)
-        except Exception as e:
-            logger.error(f"Error adding memory for user {user_id}: {e}")
-            return {"error": str(e)}
+        last_err: Optional[str] = None
+
+        for attempt in range(1, max_retries + 1):
+            # ---- throttle: wait for our turn ----
+            await _groq_throttle.acquire()
+
+            try:
+                result = await asyncio.to_thread(_sync_add)
+            except Exception as e:
+                err_text = str(e)
+                if _is_rate_limit_error(err_text):
+                    retry_after = _extract_retry_seconds(err_text)
+                    wait = max(retry_after, base_backoff * attempt) + random.uniform(0.5, 1.5)
+                    logger.warning(
+                        "Groq 429 during Mem0 add for user %s (attempt %s/%s). "
+                        "Backing off %.1fs",
+                        user_id, attempt, max_retries, wait,
+                    )
+                    await _groq_throttle.backoff(wait)
+                    await asyncio.sleep(wait)
+                    last_err = err_text
+                    continue
+                # Non-rate-limit error → don't retry
+                logger.error("Error adding memory for user %s: %s", user_id, e)
+                self._set_error(err_text)
+                return {"error": err_text}
+
+            # Mem0 may return success dict but with error payload
+            if isinstance(result, dict) and result.get("error"):
+                err_text = str(result["error"])
+                if _is_rate_limit_error(err_text) and attempt < max_retries:
+                    retry_after = _extract_retry_seconds(err_text)
+                    wait = max(retry_after, base_backoff * attempt) + random.uniform(0.5, 1.5)
+                    logger.warning(
+                        "Groq 429 in Mem0 result for user %s (attempt %s/%s). "
+                        "Backing off %.1fs",
+                        user_id, attempt, max_retries, wait,
+                    )
+                    await _groq_throttle.backoff(wait)
+                    await asyncio.sleep(wait)
+                    last_err = err_text
+                    continue
+                # Non-retryable error in result
+                self._set_error(err_text)
+                return result
+
+            # ---- success ----
+            self._clear_error()
+            return result
+
+        # Exhausted all retries
+        logger.error(
+            "Mem0 add exhausted %s retries for user %s. Last error: %s",
+            max_retries, user_id, last_err,
+        )
+        self._set_error(last_err or "Rate limit retries exhausted")
+        return {"error": last_err or "Rate limit retries exhausted"}
+
+    async def add_batch(
+        self,
+        items: List[Dict[str, Any]],
+        user_id: str,
+        *,
+        inter_call_delay: Optional[float] = None,
+    ) -> List[Dict[str, Any]]:
+        """
+        Add multiple memories sequentially with throttling between each.
+
+        Each item dict must have at minimum ``content`` (str).
+        Optional keys: ``metadata`` (dict).
+
+        Returns a list of results (one per item).
+        """
+        delay = inter_call_delay if inter_call_delay is not None else settings.MEM0_BATCH_DELAY_SECONDS
+        results: List[Dict[str, Any]] = []
+        for idx, item in enumerate(items):
+            result = await self.add(
+                content=item["content"],
+                user_id=user_id,
+                metadata=item.get("metadata"),
+            )
+            results.append(result)
+            # Proactive delay between items (throttle.acquire also enforces min interval)
+            if idx < len(items) - 1 and delay > 0:
+                await asyncio.sleep(delay)
+        return results
 
     async def search(self, query: str, user_id: str, limit: int = 5) -> List[Dict[str, Any]]:
         """
         Search memories for a user asynchronously.
 
+        Throttled to respect Groq TPM limits (search also triggers LLM calls
+        inside Mem0 for query expansion).
+
         Args:
             query: Search query
             user_id: The user ID to scope search to
@@ -129,10 +463,33 @@ class MemoryService:
             client = self._get_client()
             return client.search(query, user_id=user_id, limit=limit)
 
+        await _groq_throttle.acquire()
         try:
-            return await asyncio.to_thread(_sync_search)
+            result = await asyncio.to_thread(_sync_search)
+            self._clear_error()
+            return result
         except Exception as e:
-            logger.error(f"Error searching memories for user {user_id}: {e}")
+            err_text = str(e)
+            if _is_rate_limit_error(err_text):
+                retry_after = _extract_retry_seconds(err_text)
+                wait = max(retry_after, settings.MEM0_RETRY_BASE_SECONDS) + random.uniform(0.5, 1.5)
+                logger.warning(
+                    "Groq 429 during Mem0 search for user %s — backing off %.1fs and retrying once",
+                    user_id, wait,
+                )
+                await _groq_throttle.backoff(wait)
+                await asyncio.sleep(wait)
+                await _groq_throttle.acquire()
+                try:
+                    result = await asyncio.to_thread(_sync_search)
+                    self._clear_error()
+                    return result
+                except Exception as e2:
+                    logger.error("Mem0 search retry also failed for user %s: %s", user_id, e2)
+                    self._set_error(str(e2))
+                    return []
+            logger.error("Error searching memories for user %s: %s", user_id, e)
+            self._set_error(err_text)
             return []
 
     async def get_all(self, user_id: str) -> List[Dict[str, Any]]:
@@ -144,9 +501,12 @@ class MemoryService:
             return client.get_all(user_id=user_id)
 
         try:
-            return await asyncio.to_thread(_sync_get_all)
+            result = await asyncio.to_thread(_sync_get_all)
+            self._clear_error()
+            return result
         except Exception as e:
             logger.error(f"Error getting all memories for user {user_id}: {e}")
+            self._set_error(str(e))
             return []
 
     async def delete(self, memory_id: str) -> bool:
@@ -159,9 +519,12 @@ class MemoryService:
             return True
 
         try:
-            return await asyncio.to_thread(_sync_delete)
+            result = await asyncio.to_thread(_sync_delete)
+            self._clear_error()
+            return result
         except Exception as e:
             logger.error(f"Error deleting memory {memory_id}: {e}")
+            self._set_error(str(e))
             return False
 
     async def delete_all(self, user_id: str) -> bool:
@@ -174,9 +537,12 @@ class MemoryService:
             return True
 
         try:
-            return await asyncio.to_thread(_sync_delete_all)
+            result = await asyncio.to_thread(_sync_delete_all)
+            self._clear_error()
+            return result
         except Exception as e:
             logger.error(f"Error deleting all memories for user {user_id}: {e}")
+            self._set_error(str(e))
             return False
 
 # Global instance

backend/app/services/rag_service.py

@@ -314,6 +314,80 @@ class RAGService:
                 context_parts.append(doc["content"])
         
         return "\n\n---\n\n".join(context_parts)
+
+    async def get_user_context_structured(
+        self,
+        user_id: uuid.UUID,
+        query: str,
+        db: Optional[AsyncSession] = None,
+    ) -> Dict[str, Any]:
+        """
+        Get structured context for the LLM along with source metadata for citations.
+
+        Returns:
+            {
+                "text": "<formatted context string for the LLM>",
+                "sources": [
+                    {"type": "report", "filename": "...", "report_id": "...", "excerpt": "..."},
+                    {"type": "observations", "metric_name": "...", "excerpt": "..."},
+                    ...
+                ]
+            }
+        """
+        # Sync user data if db provided
+        if db:
+            try:
+                await self.sync_user_reports(user_id, db)
+                await self.sync_user_observations(user_id, db)
+            except Exception as e:
+                logger.warning(f"RAG sync failed for user {user_id}: {e}")
+
+        try:
+            docs = await self.query(user_id, query)
+        except Exception as e:
+            logger.warning(f"RAG context unavailable for user {user_id}: {e}")
+            return {"text": "No health data available for this user yet.", "sources": []}
+
+        if not docs:
+            return {"text": "No health data available for this user yet.", "sources": []}
+
+        context_parts: list[str] = []
+        sources: list[dict] = []
+
+        for doc in docs:
+            meta = doc.get("metadata", {})
+            source_type = meta.get("source_type", "unknown")
+            content = doc.get("content", "")
+
+            if source_type == "report":
+                filename = meta.get("filename", "Unknown report")
+                report_id = meta.get("report_id")
+                context_parts.append(f"[Source: Report '{filename}']\n{content}")
+                sources.append({
+                    "type": "report",
+                    "filename": filename,
+                    "report_id": report_id,
+                    "excerpt": content[:200] + ("..." if len(content) > 200 else ""),
+                })
+            elif source_type == "observations":
+                metric = meta.get("metric_name", "health metric")
+                context_parts.append(f"[Source: Lab observations – {metric}]\n{content}")
+                sources.append({
+                    "type": "observations",
+                    "metric_name": metric,
+                    "excerpt": content[:200] + ("..." if len(content) > 200 else ""),
+                })
+            else:
+                context_parts.append(content)
+                sources.append({
+                    "type": source_type,
+                    "excerpt": content[:200] + ("..." if len(content) > 200 else ""),
+                })
+
+        return {
+            "text": "\n\n---\n\n".join(context_parts),
+            "sources": sources,
+        }
     
     async def add_test_document(self, user_id: uuid.UUID) -> str:
         """

backend/app/settings.py

@@ -22,7 +22,16 @@ class Settings(BaseSettings):
     # so existing databases get schema changes (new columns/indexes).
     AUTO_MIGRATE: bool = False  # Disabled - using create_all instead
 
-    # Ollama LLM Configuration
+    # =====================
+    # OpenRouter Configuration (PRIMARY LLM)
+    # =====================
+    OPENROUTER_API_KEY: Optional[str] = None
+    OPENROUTER_BASE_URL: str = "https://openrouter.ai/api/v1"
+    OPENROUTER_MODEL: str = "openrouter/pony-alpha"
+    OPENROUTER_FALLBACK_MODEL: str = "upstage/solar-pro-3:free"
+    OPENROUTER_TIMEOUT: int = 120  # seconds
+
+    # Ollama LLM Configuration (LAST RESORT fallback)
     # Default to localhost for direct (non‑Docker) runs.
     # When running via Docker, docker-compose.yml overrides this to use
     # http://host.docker.internal:11434 so the container can reach the host.
@@ -44,6 +53,9 @@ class Settings(BaseSettings):
     groq_api_key: Optional[str] = None
     groq_api_base: str = "https://api.groq.com/openai/v1"
     groq_model: str = "llama-3.3-70b-versatile"  # Updated to current model
+    MEM0_GROQ_MODEL: str = "llama-3.1-8b-instant"
+    # Graphiti requires JSON-schema structured outputs; use a Groq model that supports it.
+    GRAPHITI_GROQ_MODEL: str = "moonshotai/kimi-k2-instruct-0905"
 
     # Grok/xAI API (alternative)
     grok_api_key: Optional[str] = None
@@ -70,6 +82,21 @@ class Settings(BaseSettings):
 
     # Memory service (Mem0)
     MEM0_COLLECTION: str = "user_memories"
+    MEM0_EMBED_MODEL: str = "nomic-embed-text"
+    MEM0_CHROMA_DIR: str = "/app/mem0_chroma"  # Separate from RAG to avoid singleton conflict
+    MEM0_PREFER_GROQ: bool = True
+
+    # Groq / Mem0 rate-limit mitigation
+    # Minimum seconds between consecutive Mem0 LLM calls (prevents TPM exhaustion)
+    MEM0_CALL_INTERVAL_SECONDS: float = 3.0
+    # Max retries per individual add() call when Groq returns 429
+    MEM0_MAX_RETRIES: int = 5
+    # Base backoff (seconds) for exponential retry on 429
+    MEM0_RETRY_BASE_SECONDS: float = 2.0
+    # Proactive delay (seconds) between profile sync batches
+    MEM0_BATCH_DELAY_SECONDS: float = 5.0
+    # Number of facts per Mem0 batch (larger = fewer API calls)
+    MEM0_SYNC_BATCH_SIZE: int = 15
 
     # Graph service (Graphiti)
     # Note: Neo4j Community Edition only supports "neo4j" database name
@@ -109,4 +136,3 @@ logger.info(f"  SMS_TEST_TO_NUMBER: {settings.SMS_TEST_TO_NUMBER}")
 logger.info(f"  TWILIO_ACCOUNT_SID configured: {bool(settings.TWILIO_ACCOUNT_SID)}")
 logger.info(f"  TWILIO_AUTH_TOKEN configured: {bool(settings.TWILIO_AUTH_TOKEN)}")
 logger.info(f"  TWILIO_FROM_NUMBER: {settings.TWILIO_FROM_NUMBER}")
-

backend/requirements.txt

@@ -38,9 +38,12 @@ chromadb>=0.4.0
 sentence-transformers>=2.2.0
 ollama>=0.1.0
 google-generativeai>=0.4.0
+openai>=1.0.0  # Used as OpenRouter SDK (OpenAI-compatible API)
 
 # Local MedGemma via Hugging Face
-transformers>=4.56.0
+# Keep transformers on the 4.x line; 5.x requires newer torch and breaks
+# sentence-transformers import paths used by Mem0 huggingface embeddings.
+transformers>=4.56.0,<5.0.0
 # CPU-only torch to avoid pulling CUDA/NVIDIA wheels.
 # Note: Some PyTorch CPU indexes don't publish a `+cpu` local version tag for older releases,
 # so pin the plain version.
@@ -53,8 +56,16 @@ huggingface_hub>=0.23.0
 # Memory layer (Mem0)
 mem0ai>=0.1.0
 
-# Knowledge graph (Graphiti with Gemini support)
-graphiti-core[google-genai]>=0.5.0
+# Knowledge graph (Graphiti)
+# Note: Older `[google-genai]` extra variants pull legacy graph-service deps and
+# can fail resolver on modern environments/architectures.
+graphiti-core>=0.12.0
 
 # Neo4j driver (required by both Mem0 and Graphiti)
 neo4j>=5.26.0
+
+# Mem0 graph backend dependency (required when graph_store is enabled)
+langchain-neo4j>=0.1.1
+
+# Mem0 Neo4j graph backend also requires BM25 helper package
+rank-bm25>=0.2.2

backend/tests/test_assistant_integration.py

@@ -1,10 +1,8 @@
 import pytest
 import uuid
 from unittest.mock import MagicMock, patch, AsyncMock
-from typing import List, Dict, Any
 from app.services.assistant_service import AssistantService
 from app.models import ChatSession, ChatMessage
-from app.schemas import Citation
 
 # Mock the entire database session
 @pytest.fixture
@@ -44,8 +42,8 @@ def assistant_service(mock_db):
         mock_mem.return_value = mem_service
 
         graph_service = MagicMock()
-        graph_service.search = AsyncMock(return_value=["HbA1c -> indicates -> Diabetes"])
-        graph_service.add_episode = AsyncMock(return_value=None)
+        graph_service.search_user = AsyncMock(return_value=["HbA1c -> indicates -> Diabetes"])
+        graph_service.add_user_episode = AsyncMock(return_value=None)
         mock_graph.return_value = graph_service
 
         rag_service = MagicMock()

backend/tests/test_assistant_service.py

@@ -7,7 +7,6 @@ Uses mocks to avoid needing actual Neo4j/Chroma/Ollama instances.
 import pytest
 from unittest.mock import AsyncMock, MagicMock, patch
 import uuid
-from datetime import datetime
 
 from app.services.assistant_service import AssistantService
 from app.models import ChatSession, ChatMessage
@@ -65,7 +64,7 @@ def mock_services():
 
         # Setup Graph Service mocks
         graph_svc = AsyncMock()
-        graph_svc.search.return_value = ["Diabetes relates to High Glucose"]
+        graph_svc.search_user.return_value = ["Diabetes relates to High Glucose"]
         mock_graph.return_value = graph_svc
 
         # Setup RAG Service mocks
@@ -116,7 +115,7 @@ async def test_chat_uses_all_contexts(mock_db_session, mock_services):
     mock_services["memory"].search.assert_called_once_with(message, user_id=str(user_id), limit=5)
 
     # 3. Verify Graph Search called
-    mock_services["graph"].search.assert_called_once_with(message, limit=5)
+    mock_services["graph"].search_user.assert_called_once_with(str(user_id), message, limit=5)
 
     # 4. Verify LLM called with combined context
     call_args = mock_services["llm"].generate.call_args
@@ -145,6 +144,8 @@ async def test_chat_updates_memory_and_graph(mock_db_session, mock_services):
     assert "Assistant: Based on" in content
 
     # Verify Graph Update
-    mock_services["graph"].add_episode.assert_called_once()
-    args, _ = mock_services["graph"].add_episode.call_args
-    assert "User asked: I feel tired" in args[0]
+    mock_services["graph"].add_user_episode.assert_called_once()
+    _, kwargs = mock_services["graph"].add_user_episode.call_args
+    assert kwargs["user_id"] == str(user_id)
+    assert kwargs["source"] == "user_chat"
+    assert "User asked: I feel tired" in kwargs["content"]

backend/tests/test_graph_service.py

@@ -22,12 +22,13 @@ async def test_add_episode(graph_service):
     await graph_service.add_episode(content, source)
 
     # Verify
-    graph_service.client.add_episode.assert_called_once_with(
-        name=f"Episode from {source}",
-        episode_body=content,
-        source_description=source,
-        reference_time=None
-    )
+    graph_service.client.add_episode.assert_called_once()
+    kwargs = graph_service.client.add_episode.call_args.kwargs
+    assert kwargs["name"] == f"Episode from {source}"
+    assert kwargs["episode_body"] == content
+    assert kwargs["source_description"] == source
+    assert "reference_time" in kwargs
+    assert kwargs["group_id"] is None
 
 @pytest.mark.asyncio
 async def test_add_observations(graph_service):
@@ -40,12 +41,13 @@ async def test_add_observations(graph_service):
 
     # Verify
     expected_content = "Medical System Observations:\n- BP is 140/90\n- HR is 80"
-    graph_service.client.add_episode.assert_called_once_with(
-        name=f"Episode from {source}",
-        episode_body=expected_content,
-        source_description=source,
-        reference_time=None
-    )
+    graph_service.client.add_episode.assert_called_once()
+    kwargs = graph_service.client.add_episode.call_args.kwargs
+    assert kwargs["name"] == f"Episode from {source}"
+    assert kwargs["episode_body"] == expected_content
+    assert kwargs["source_description"] == source
+    assert "reference_time" in kwargs
+    assert kwargs["group_id"] is None
 
 @pytest.mark.asyncio
 async def test_search_graph(graph_service):
@@ -66,7 +68,10 @@ async def test_search_graph(graph_service):
     results = await graph_service.search(query)
 
     # Verify
-    graph_service.client.search.assert_called_once_with(query, limit=10)
+    graph_service.client.search.assert_called_once()
+    args, kwargs = graph_service.client.search.call_args
+    assert args[0] == query
+    assert kwargs.get("num_results", kwargs.get("limit")) == 10
     assert results == ["Patient -> HAS_CONDITION -> Hypertension"]
 
 @pytest.mark.asyncio
@@ -76,19 +81,18 @@ async def test_initialization_flow():
 
     # We need to mock the imports in graph_service
     with patch('app.services.graph_service.GRAPHITI_AVAILABLE', True), \
-         patch('app.services.graph_service.Neo4jDriver') as MockDriver, \
          patch('app.services.graph_service.LLMConfig') as MockConfig, \
          patch('app.services.graph_service.OpenAIClient') as MockClient, \
          patch('app.services.graph_service.Graphiti') as MockGraphiti:
 
+        MockGraphiti.return_value.build_indices_and_constraints = AsyncMock(return_value=None)
         service = GraphService()
 
         await service.initialize()
 
         # Verify initializations
-        MockDriver.assert_called_once()
         MockConfig.assert_called_once()
-        MockClient.assert_called_once()
+        MockClient.assert_called_once_with(config=MockConfig.return_value, max_tokens=2048)
         MockGraphiti.assert_called_once()
 
         # Verify build_indices was called

backend/tests/test_routes_graph.py

@@ -15,7 +15,7 @@ class TestGraphRoutes:
         """Create a mock graph service."""
         mock_service = MagicMock()
         mock_service.client = MagicMock()  # Service is available
-        mock_service.search = AsyncMock(return_value=[
+        mock_service.search_user = AsyncMock(return_value=[
             "High LDL -> leads_to -> Cardiovascular Risk",
             "Diabetes -> requires -> Blood Sugar Monitoring",
             "Exercise -> improves -> Cardiovascular Health",
@@ -51,7 +51,11 @@ class TestGraphRoutes:
             assert result.available is True
             assert result.count == 3
             assert len(result.facts) == 3
-            mock_graph_service.search.assert_called_once()
+            mock_graph_service.search_user.assert_called_once_with(
+                user_id="test-user-123",
+                query="health conditions",
+                limit=20,
+            )
 
     @pytest.mark.asyncio
     async def test_get_user_graph_facts_unavailable(self, mock_graph_service_unavailable, mock_user):
@@ -82,7 +86,8 @@ class TestGraphRoutes:
             
             assert result.available is True
             assert result.count == 3
-            mock_graph_service.search.assert_called_once_with(
+            mock_graph_service.search_user.assert_called_once_with(
+                user_id="test-user-123",
                 query="cardiovascular",
                 limit=10
             )
@@ -128,7 +133,7 @@ class TestGraphRoutes:
         """Test error handling in graph routes."""
         mock_service = MagicMock()
         mock_service.client = MagicMock()  # Service available
-        mock_service.search = AsyncMock(side_effect=Exception("Neo4j connection error"))
+        mock_service.search_user = AsyncMock(side_effect=Exception("Neo4j connection error"))
         
         with patch('app.routes.graph.get_graph_service', return_value=mock_service):
             from app.routes.graph import get_user_graph_facts

backend/tests/test_routes_memory.py

@@ -106,6 +106,19 @@ class TestMemoryRoutes:
             assert result.deleted_count == 1
             mock_memory_service.delete.assert_called_once_with("mem-1")
 
+    @pytest.mark.asyncio
+    async def test_delete_memory_rejects_other_user_id(self, mock_memory_service, mock_user):
+        """Delete should be rejected if memory ID is not found in current user's list."""
+        with patch('app.routes.memory.get_memory_service', return_value=mock_memory_service):
+            from app.routes.memory import delete_memory
+
+            result = await delete_memory(memory_id="not-owned-id", current_user=mock_user)
+
+            assert result.success is False
+            assert result.deleted_count == 0
+            assert "not found" in (result.message or "").lower()
+            mock_memory_service.delete.assert_not_called()
+
     @pytest.mark.asyncio
     async def test_delete_all_memories_success(self, mock_memory_service, mock_user):
         """Test successful deletion of all memories."""

docker-compose.yml

@@ -49,6 +49,8 @@ services:
       - paddle_models:/root/.paddleocr
       # Persist ChromaDB vector store
       - chroma_data:/app/chroma_db
+      # Persist Mem0's separate ChromaDB store
+      - mem0_chroma:/app/mem0_chroma
       # Persist Hugging Face model/cache locally
       - hf_cache:/root/.cache/huggingface
     environment:
@@ -68,6 +70,12 @@ services:
       - OPENAI_API_KEY=${OPENAI_API_KEY:-}
       - GEMINI_API_KEY=${GEMINI_API_KEY:-}
       - GOOGLE_PLACES_API_KEY=${GOOGLE_PLACES_API_KEY:-}
+      # OpenRouter (PRIMARY LLM provider)
+      - OPENROUTER_API_KEY=${OPENROUTER_API_KEY:-}
+      - OPENROUTER_BASE_URL=${OPENROUTER_BASE_URL:-https://openrouter.ai/api/v1}
+      - OPENROUTER_MODEL=${OPENROUTER_MODEL:-openrouter/pony-alpha}
+      - OPENROUTER_FALLBACK_MODEL=${OPENROUTER_FALLBACK_MODEL:-upstage/solar-pro-3:free}
+      - OPENROUTER_TIMEOUT=${OPENROUTER_TIMEOUT:-120}
       # ElevenLabs TTS Configuration
       - ELEVENLABS_API_KEY=${ELEVENLABS_API_KEY:-}
       - ELEVENLABS_VOICE_ID=${ELEVENLABS_VOICE_ID:-21m00Tcm4TlvDq8ikWAM}
@@ -86,7 +94,17 @@ services:
       - NEO4J_USER=${NEO4J_USER:-neo4j}
       - NEO4J_PASSWORD=${NEO4J_PASSWORD:-changeme}
       - MEM0_COLLECTION=${MEM0_COLLECTION:-user_memories}
+      - MEM0_EMBED_MODEL=${MEM0_EMBED_MODEL:-nomic-embed-text}
+      - MEM0_GROQ_MODEL=${MEM0_GROQ_MODEL:-llama-3.1-8b-instant}
+      - MEM0_PREFER_GROQ=true
+      - GRAPHITI_GROQ_MODEL=${GRAPHITI_GROQ_MODEL:-moonshotai/kimi-k2-instruct-0905}
       - GRAPHITI_DATABASE=${GRAPHITI_DATABASE:-neo4j}
+      # Groq rate-limit mitigation (tune for your Groq plan)
+      - MEM0_CALL_INTERVAL_SECONDS=${MEM0_CALL_INTERVAL_SECONDS:-3.0}
+      - MEM0_MAX_RETRIES=${MEM0_MAX_RETRIES:-5}
+      - MEM0_RETRY_BASE_SECONDS=${MEM0_RETRY_BASE_SECONDS:-2.0}
+      - MEM0_BATCH_DELAY_SECONDS=${MEM0_BATCH_DELAY_SECONDS:-5.0}
+      - MEM0_SYNC_BATCH_SIZE=${MEM0_SYNC_BATCH_SIZE:-15}
       # SMS Configuration (Twilio or mock mode)
       - SMS_MODE=${SMS_MODE:-mock}
       - SMS_TEST_TO_NUMBER=${SMS_TEST_TO_NUMBER:-}
@@ -117,6 +135,12 @@ services:
       NEO4J_AUTH: ${NEO4J_USER:-neo4j}/${NEO4J_PASSWORD:-changeme}
       NEO4J_PLUGINS: '["apoc"]'
       NEO4J_dbms_security_procedures_unrestricted: apoc.*
+      # ---- Performance tuning (prevents default tiny-heap lag) ----
+      NEO4J_server_memory_heap_initial__size: 512m
+      NEO4J_server_memory_heap_max__size: 1G
+      NEO4J_server_memory_pagecache_size: 512m
+      # Disable unnecessary features for faster startup
+      NEO4J_dbms_usage__report_enabled: "false"
     ports:
       - "7474:7474"  # Browser UI
       - "7687:7687"  # Bolt protocol
@@ -153,6 +177,7 @@ volumes:
   postgres_data:
   paddle_models:
   chroma_data:
+  mem0_chroma:
   hf_cache:
   neo4j_data:
   neo4j_logs:

frontend/src/components/HealthGraph.css

@@ -75,6 +75,12 @@
     background: var(--dash-surface-hover, #ffffff);
 }
 
+.health-graph-actions {
+    display: flex;
+    align-items: center;
+    gap: var(--dash-spacing-sm, 0.75rem);
+}
+
 .health-graph-controls {
     display: flex;
     align-items: center;
@@ -132,6 +138,31 @@
     color: white;
 }
 
+.health-graph-sync {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.4rem;
+    padding: 0.5rem 0.75rem;
+    border-radius: var(--dash-radius-md, 0.75rem);
+    border: 1px solid var(--dash-accent-light, #8fb199);
+    background: var(--dash-accent-pale, #e8f3eb);
+    color: var(--dash-accent-dark, #4a7c59);
+    font-size: 0.8125rem;
+    font-weight: 600;
+    cursor: pointer;
+    transition: all var(--dash-transition-base, 250ms);
+}
+
+.health-graph-sync:hover:not(:disabled) {
+    background: var(--dash-accent-light, #8fb199);
+    color: white;
+}
+
+.health-graph-sync:disabled {
+    opacity: 0.6;
+    cursor: not-allowed;
+}
+
 /* States */
 .health-graph-loading,
 .health-graph-empty,
@@ -178,6 +209,47 @@
     font-size: 0.875rem;
 }
 
+.health-graph-note {
+    display: flex;
+    align-items: center;
+    gap: var(--dash-spacing-sm, 0.75rem);
+    padding: 0.75rem var(--dash-spacing-xl, 2rem);
+    background: rgba(107, 145, 117, 0.12);
+    color: var(--dash-accent-dark, #4a7c59);
+    font-size: 0.875rem;
+}
+
+.health-graph-empty-note {
+    margin-top: var(--dash-spacing-sm, 0.75rem);
+    color: var(--dash-accent-dark, #4a7c59);
+    font-size: 0.8125rem;
+}
+
+.health-graph-empty-sync {
+    margin-top: var(--dash-spacing-md, 1rem);
+    display: inline-flex;
+    align-items: center;
+    gap: 0.4rem;
+    padding: 0.625rem 1rem;
+    border-radius: var(--dash-radius-md, 0.75rem);
+    border: 1px solid var(--dash-accent-light, #8fb199);
+    background: var(--dash-accent, #6b9175);
+    color: white;
+    font-size: 0.875rem;
+    font-weight: 600;
+    cursor: pointer;
+    transition: all var(--dash-transition-base, 250ms);
+}
+
+.health-graph-empty-sync:hover:not(:disabled) {
+    background: var(--dash-accent-dark, #4a7c59);
+}
+
+.health-graph-empty-sync:disabled {
+    opacity: 0.6;
+    cursor: not-allowed;
+}
+
 /* Canvas */
 .health-graph-canvas-wrapper {
     position: relative;
@@ -307,6 +379,177 @@
     color: var(--dash-accent-dark, #4a7c59);
 }
 
+/* ============================================================================
+   AI Insights Panel Styles
+   ============================================================================ */
+
+.health-graph-insights {
+    margin: 0 var(--dash-spacing-xl, 2rem) var(--dash-spacing-lg, 1.5rem);
+    padding: var(--dash-spacing-lg, 1.5rem);
+    background: linear-gradient(135deg, #faf8f4 0%, #f5f1e8 100%);
+    border-radius: var(--dash-radius-lg, 1rem);
+    border: 1px solid var(--dash-border, #e5dfd5);
+}
+
+.insights-header {
+    display: flex;
+    align-items: center;
+    gap: var(--dash-spacing-sm, 0.75rem);
+    margin-bottom: var(--dash-spacing-md, 1rem);
+}
+
+.insights-icon {
+    color: var(--dash-accent, #6b9175);
+}
+
+.insights-title {
+    font-size: 0.9375rem;
+    font-weight: 600;
+    color: var(--dash-text, #2d2d2d);
+    font-family: var(--dash-font-serif, 'Playfair Display', Georgia, serif);
+}
+
+.insights-buttons {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--dash-spacing-sm, 0.75rem);
+}
+
+.insight-button {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.4rem;
+    padding: 0.5rem 0.875rem;
+    border-radius: var(--dash-radius-md, 0.75rem);
+    border: 1px solid transparent;
+    font-size: 0.8125rem;
+    font-weight: 600;
+    cursor: pointer;
+    transition: all var(--dash-transition-base, 250ms);
+}
+
+.insight-button:disabled {
+    opacity: 0.6;
+    cursor: not-allowed;
+}
+
+/* Temporal - Blue theme */
+.insight-button-temporal {
+    background: linear-gradient(135deg, #d4e5f7 0%, #c4d8f0 100%);
+    color: #3d6a9f;
+    border-color: #a8c8e8;
+}
+
+.insight-button-temporal:hover:not(:disabled),
+.insight-button-temporal.active {
+    background: linear-gradient(135deg, #7a9cc6 0%, #5a8abf 100%);
+    color: white;
+    border-color: #5a8abf;
+}
+
+/* Relationships - Green theme */
+.insight-button-relationships {
+    background: linear-gradient(135deg, #e8f3eb 0%, #d4e8d9 100%);
+    color: #4a7c59;
+    border-color: #8fb199;
+}
+
+.insight-button-relationships:hover:not(:disabled),
+.insight-button-relationships.active {
+    background: linear-gradient(135deg, #6b9175 0%, #4a7c59 100%);
+    color: white;
+    border-color: #4a7c59;
+}
+
+/* Contradictions - Amber theme */
+.insight-button-contradictions {
+    background: linear-gradient(135deg, #fef3d7 0%, #fce8b2 100%);
+    color: #a07d28;
+    border-color: #d9a962;
+}
+
+.insight-button-contradictions:hover:not(:disabled),
+.insight-button-contradictions.active {
+    background: linear-gradient(135deg, #d9a962 0%, #c49430 100%);
+    color: white;
+    border-color: #c49430;
+}
+
+.insights-content {
+    margin-top: var(--dash-spacing-md, 1rem);
+    padding: var(--dash-spacing-md, 1rem);
+    background: white;
+    border-radius: var(--dash-radius-md, 0.75rem);
+    border: 1px solid var(--dash-border-light, #f0ebe3);
+}
+
+.insights-loading {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: var(--dash-spacing-sm, 0.75rem);
+    padding: var(--dash-spacing-lg, 1.5rem);
+    color: var(--dash-accent-dark, #4a7c59);
+    font-size: 0.9rem;
+}
+
+.insights-error {
+    display: flex;
+    align-items: center;
+    gap: var(--dash-spacing-sm, 0.75rem);
+    padding: var(--dash-spacing-md, 1rem);
+    background: rgba(200, 90, 84, 0.1);
+    border-radius: var(--dash-radius-sm, 0.5rem);
+    color: var(--dash-danger, #c85a54);
+    font-size: 0.875rem;
+}
+
+.insights-text {
+    line-height: 1.7;
+    color: var(--dash-text, #2d2d2d);
+    font-size: 0.9375rem;
+}
+
+.insights-text p {
+    margin: 0 0 0.75rem 0;
+}
+
+.insights-text p:last-child {
+    margin-bottom: 0;
+}
+
+.insights-sources {
+    margin-top: var(--dash-spacing-md, 1rem);
+    padding-top: var(--dash-spacing-sm, 0.75rem);
+    border-top: 1px solid var(--dash-border-light, #f0ebe3);
+}
+
+.insights-sources summary {
+    display: flex;
+    align-items: center;
+    gap: 0.35rem;
+    font-size: 0.8125rem;
+    color: var(--dash-text-muted, #999999);
+    cursor: pointer;
+    user-select: none;
+}
+
+.insights-sources summary:hover {
+    color: var(--dash-accent-dark, #4a7c59);
+}
+
+.insights-sources ul {
+    margin: var(--dash-spacing-sm, 0.75rem) 0 0;
+    padding: 0 0 0 1.25rem;
+    font-size: 0.8125rem;
+    color: var(--dash-text-secondary, #6b6b6b);
+    line-height: 1.6;
+}
+
+.insights-sources li {
+    margin-bottom: 0.35rem;
+}
+
 /* Spinner animation */
 .spinning {
     animation: spin 1s linear infinite;
@@ -330,6 +573,11 @@
         gap: var(--dash-spacing-sm, 0.75rem);
     }
 
+    .health-graph-actions {
+        width: 100%;
+        justify-content: flex-end;
+    }
+
     .health-graph-canvas-wrapper {
         margin: 0 var(--dash-spacing-md, 1rem) var(--dash-spacing-md, 1rem);
     }

frontend/src/components/HealthGraph.tsx

@@ -1,4 +1,4 @@
-import React, { useState, useEffect, useCallback, useRef } from 'react';
+import React, { useState, useEffect, useCallback, useRef, useMemo } from 'react';
 import { motion, AnimatePresence } from 'framer-motion';
 import {
     Network,
@@ -11,6 +11,10 @@ import {
     ZoomOut,
     Maximize2,
     Info,
+    TrendingUp,
+    GitBranch,
+    AlertTriangle,
+    Loader2,
 } from 'lucide-react';
 import { API_BASE_URL } from '../config/api';
 import './HealthGraph.css';
@@ -39,6 +43,22 @@ interface GraphDataResponse {
     message: string | null;
 }
 
+interface InsightResponse {
+    insight_type: string;
+    content: string;
+    sources: string[];
+    available: boolean;
+    message: string | null;
+}
+
+type InsightType = 'temporal' | 'relationships' | 'contradictions';
+
+const INSIGHT_BUTTONS: { type: InsightType; icon: typeof TrendingUp; label: string; description: string }[] = [
+    { type: 'temporal', icon: TrendingUp, label: 'Timeline Analysis', description: 'How have my metrics changed?' },
+    { type: 'relationships', icon: GitBranch, label: 'Health Connections', description: 'What\'s connected in my health data?' },
+    { type: 'contradictions', icon: AlertTriangle, label: 'Data Conflicts', description: 'Any inconsistencies in my records?' },
+];
+
 interface HealthGraphProps {
     authToken?: string;
     apiBaseUrl?: string;
@@ -55,6 +75,8 @@ const nodeColors: Record<string, string> = {
     entity: '#999999',        // dash-text-muted (gray)
 };
 
+const normalizeNodeId = (value: string): string => value.trim().toLowerCase().replace(/\s+/g, '_');
+
 const HealthGraph: React.FC<HealthGraphProps> = ({
     authToken,
     apiBaseUrl = API_BASE_URL,
@@ -62,13 +84,22 @@ const HealthGraph: React.FC<HealthGraphProps> = ({
 }) => {
     const [graphData, setGraphData] = useState<GraphDataResponse | null>(null);
     const [loading, setLoading] = useState(false);
+    const [syncing, setSyncing] = useState(false);
     const [error, setError] = useState<string | null>(null);
+    const [syncNotice, setSyncNotice] = useState<string | null>(null);
     const [collapsed, setCollapsed] = useState(defaultCollapsed);
     const [available, setAvailable] = useState(true);
     const [zoom, setZoom] = useState(1);
     const [hoveredNode, setHoveredNode] = useState<GraphNode | null>(null);
     const svgRef = useRef<SVGSVGElement>(null);
 
+    // Insights state
+    const [insightLoading, setInsightLoading] = useState(false);
+    const [insightContent, setInsightContent] = useState<string | null>(null);
+    const [insightSources, setInsightSources] = useState<string[]>([]);
+    const [activeInsightType, setActiveInsightType] = useState<InsightType | null>(null);
+    const [insightError, setInsightError] = useState<string | null>(null);
+
     const fetchGraphData = useCallback(async () => {
         if (!authToken) {
             setError('Authentication required');
@@ -103,6 +134,98 @@ const HealthGraph: React.FC<HealthGraphProps> = ({
         }
     }, [authToken, apiBaseUrl]);
 
+    // Generate AI insight from graph data
+    const generateInsight = useCallback(async (insightType: InsightType) => {
+        if (!authToken) {
+            setInsightError('Authentication required');
+            return;
+        }
+
+        setInsightLoading(true);
+        setInsightError(null);
+        setInsightContent(null);
+        setActiveInsightType(insightType);
+
+        try {
+            const response = await fetch(`${apiBaseUrl}/api/graph/insights`, {
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${authToken}`,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({ insight_type: insightType, context_limit: 10 }),
+            });
+
+            if (!response.ok) {
+                throw new Error(`Failed to generate insight: ${response.status}`);
+            }
+
+            const data: InsightResponse = await response.json();
+
+            if (!data.available) {
+                throw new Error(data.message || 'Service not available');
+            }
+
+            if (data.message && !data.content) {
+                throw new Error(data.message);
+            }
+
+            if (!data.content || data.content.trim() === '') {
+                setInsightError('No insight generated. Try adding more health data.');
+                return;
+            }
+
+            setInsightContent(data.content);
+            setInsightSources(data.sources || []);
+        } catch (err) {
+            setInsightError(err instanceof Error ? err.message : 'Failed to generate insight');
+        } finally {
+            setInsightLoading(false);
+        }
+    }, [authToken, apiBaseUrl]);
+
+    const syncProfileToGraph = useCallback(async () => {
+        if (!authToken) {
+            setError('Authentication required');
+            return;
+        }
+
+        setSyncing(true);
+        setError(null);
+        setSyncNotice(null);
+
+        try {
+            const response = await fetch(`${apiBaseUrl}/api/profile/sync-to-memory`, {
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${authToken}`,
+                    'Content-Type': 'application/json',
+                },
+            });
+
+            if (!response.ok) {
+                throw new Error(`Profile sync failed: ${response.status}`);
+            }
+
+            const payload = await response.json().catch(() => null);
+            if (payload?.success === false) {
+                throw new Error(payload?.message || 'Profile sync failed');
+            }
+            const syncedFacts = payload?.synced?.facts_synced;
+            if (typeof syncedFacts === 'number') {
+                setSyncNotice(`Synced ${syncedFacts} facts from your profile. Refreshing graph...`);
+            } else {
+                setSyncNotice('Profile sync completed. Refreshing graph...');
+            }
+
+            await fetchGraphData();
+        } catch (err) {
+            setError(err instanceof Error ? err.message : 'Failed to sync profile data');
+        } finally {
+            setSyncing(false);
+        }
+    }, [authToken, apiBaseUrl, fetchGraphData]);
+
     useEffect(() => {
         if (!collapsed && authToken) {
             fetchGraphData();
@@ -110,7 +233,7 @@ const HealthGraph: React.FC<HealthGraphProps> = ({
     }, [collapsed, authToken, fetchGraphData]);
 
     // Simple force-directed layout calculation (simplified)
-    const calculateLayout = useCallback((nodes: GraphNode[], relationships: GraphRelationship[]) => {
+    const calculateLayout = useCallback((nodes: GraphNode[]) => {
         const width = 600;
         const height = 400;
         const centerX = width / 2;
@@ -154,9 +277,10 @@ const HealthGraph: React.FC<HealthGraphProps> = ({
         return nodePositions;
     }, []);
 
-    const nodePositions = graphData
-        ? calculateLayout(graphData.nodes, graphData.relationships)
-        : {};
+    const nodePositions = useMemo(
+        () => (graphData ? calculateLayout(graphData.nodes) : {}),
+        [graphData, calculateLayout]
+    );
 
     const handleZoomIn = () => setZoom(prev => Math.min(prev + 0.2, 2));
     const handleZoomOut = () => setZoom(prev => Math.max(prev - 0.2, 0.5));
@@ -210,8 +334,22 @@ const HealthGraph: React.FC<HealthGraphProps> = ({
                         ) : !graphData || graphData.nodes.length === 0 ? (
                             <div className="health-graph-empty">
                                 <Sparkles size={32} />
-                                <p>No health relationships yet</p>
-                                <span>Relationships will be discovered as you chat with the assistant.</span>
+                                <p>No graph data for your account yet</p>
+                                <span>
+                                    This graph is user-scoped. Sync your profile data or upload reports to generate
+                                    relationships.
+                                </span>
+                                {syncNotice && (
+                                    <span className="health-graph-empty-note">{syncNotice}</span>
+                                )}
+                                <button
+                                    className="health-graph-empty-sync"
+                                    onClick={syncProfileToGraph}
+                                    disabled={syncing || loading}
+                                >
+                                    {syncing ? <RefreshCw size={14} className="spinning" /> : <Sparkles size={14} />}
+                                    <span>{syncing ? 'Syncing...' : 'Sync Profile Data'}</span>
+                                </button>
                             </div>
                         ) : (
                             <>
@@ -228,13 +366,102 @@ const HealthGraph: React.FC<HealthGraphProps> = ({
                                             <Maximize2 size={16} />
                                         </button>
                                     </div>
-                                    <button
-                                        className="health-graph-refresh"
-                                        onClick={fetchGraphData}
-                                        title="Refresh"
-                                    >
-                                        <RefreshCw size={16} />
-                                    </button>
+                                    <div className="health-graph-actions">
+                                        <button
+                                            className="health-graph-sync"
+                                            onClick={syncProfileToGraph}
+                                            disabled={syncing || loading}
+                                            title="Sync profile into per-user graph"
+                                        >
+                                            {syncing ? <RefreshCw size={14} className="spinning" /> : <Sparkles size={14} />}
+                                            <span>{syncing ? 'Syncing...' : 'Sync Profile'}</span>
+                                        </button>
+                                        <button
+                                            className="health-graph-refresh"
+                                            onClick={fetchGraphData}
+                                            title="Refresh"
+                                        >
+                                            <RefreshCw size={16} />
+                                        </button>
+                                    </div>
+                                </div>
+
+                                {syncNotice && (
+                                    <div className="health-graph-note">
+                                        <Info size={14} />
+                                        <span>{syncNotice}</span>
+                                    </div>
+                                )}
+
+                                {/* AI Insights Panel */}
+                                <div className="health-graph-insights">
+                                    <div className="insights-header">
+                                        <Sparkles size={16} className="insights-icon" />
+                                        <span className="insights-title">AI-Powered Insights</span>
+                                    </div>
+                                    <div className="insights-buttons">
+                                        {INSIGHT_BUTTONS.map(({ type, icon: Icon, label, description }) => (
+                                            <button
+                                                key={type}
+                                                className={`insight-button insight-button-${type} ${activeInsightType === type ? 'active' : ''}`}
+                                                onClick={() => generateInsight(type)}
+                                                disabled={insightLoading}
+                                                title={description}
+                                            >
+                                                {insightLoading && activeInsightType === type ? (
+                                                    <Loader2 size={16} className="spinning" />
+                                                ) : (
+                                                    <Icon size={16} />
+                                                )}
+                                                <span>{label}</span>
+                                            </button>
+                                        ))}
+                                    </div>
+
+                                    <AnimatePresence>
+                                        {(insightContent || insightLoading || insightError) && (
+                                            <motion.div
+                                                initial={{ height: 0, opacity: 0 }}
+                                                animate={{ height: 'auto', opacity: 1 }}
+                                                exit={{ height: 0, opacity: 0 }}
+                                                transition={{ duration: 0.2 }}
+                                                className="insights-content"
+                                            >
+                                                {insightLoading ? (
+                                                    <div className="insights-loading">
+                                                        <Loader2 size={20} className="spinning" />
+                                                        <span>Analyzing your health data...</span>
+                                                    </div>
+                                                ) : insightError ? (
+                                                    <div className="insights-error">
+                                                        <AlertCircle size={16} />
+                                                        <span>{insightError}</span>
+                                                    </div>
+                                                ) : insightContent && (
+                                                    <>
+                                                        <div className="insights-text">
+                                                            {insightContent.split('\n').filter(line => line.trim()).map((line, i) => (
+                                                                <p key={i}>{line}</p>
+                                                            ))}
+                                                        </div>
+                                                        {insightSources.length > 0 && (
+                                                            <details className="insights-sources">
+                                                                <summary>
+                                                                    <Info size={12} />
+                                                                    <span>{insightSources.length} facts used</span>
+                                                                </summary>
+                                                                <ul>
+                                                                    {insightSources.map((source, i) => (
+                                                                        <li key={i}>{source}</li>
+                                                                    ))}
+                                                                </ul>
+                                                            </details>
+                                                        )}
+                                                    </>
+                                                )}
+                                            </motion.div>
+                                        )}
+                                    </AnimatePresence>
                                 </div>
 
                                 {error && (
@@ -254,8 +481,8 @@ const HealthGraph: React.FC<HealthGraphProps> = ({
                                         {/* Relationship lines */}
                                         <g className="relationships">
                                             {graphData.relationships.map((rel, index) => {
-                                                const sourcePos = nodePositions[rel.source.toLowerCase().replace(/ /g, '_')];
-                                                const targetPos = nodePositions[rel.target.toLowerCase().replace(/ /g, '_')];
+                                                const sourcePos = nodePositions[normalizeNodeId(rel.source)];
+                                                const targetPos = nodePositions[normalizeNodeId(rel.target)];
 
                                                 if (!sourcePos || !targetPos) return null;
 

frontend/src/components/ProfileSuccessScreen.tsx

@@ -8,7 +8,6 @@ import { useEffect } from 'react';
 import { useNavigate } from 'react-router-dom';
 import { motion } from 'framer-motion';
 import { Check, ArrowRight } from 'lucide-react';
-import { API_BASE_URL } from '../config/api';
 import './ProfileSuccessScreen.css';
 
 interface ProfileSuccessScreenProps {
@@ -23,41 +22,19 @@ export default function ProfileSuccessScreen({
   const navigate = useNavigate();
 
   useEffect(() => {
-    // Sync profile data to memory/graph layers for provenance
-    const syncToMemory = async () => {
-      const authToken = localStorage.getItem('authToken');
-      if (!authToken) return;
-
-      try {
-        await fetch(`${API_BASE_URL}/api/profile/sync-to-memory`, {
-          method: 'POST',
-          headers: {
-            'Authorization': `Bearer ${authToken}`,
-            'Content-Type': 'application/json',
-          },
-        });
-        console.log('Profile synced to memory/graph layers');
-      } catch (error) {
-        console.warn('Failed to sync profile to memory:', error);
-        // Non-blocking - don't prevent navigation on failure
-      }
-    };
-
-    syncToMemory();
-  }, []);
-
-  useEffect(() => {
+    // Profile sync is now handled by the Features page which shows a
+    // live sync overlay.  We just redirect there after the success animation.
     if (autoRedirect) {
       const timer = setTimeout(() => {
-        navigate('/dashboard');
+        navigate('/features', { state: { fromProfileSync: true } });
       }, redirectDelay);
 
       return () => clearTimeout(timer);
     }
   }, [autoRedirect, redirectDelay, navigate]);
 
-  const handleDashboard = () => {
-    navigate('/dashboard');
+  const handleFeatures = () => {
+    navigate('/features', { state: { fromProfileSync: true } });
   };
 
   const handleSettings = () => {
@@ -140,9 +117,9 @@ export default function ProfileSuccessScreen({
         >
           <button
             className="success-btn success-btn-primary"
-            onClick={handleDashboard}
+            onClick={handleFeatures}
           >
-            Go to Dashboard
+            View Health Intelligence
             <ArrowRight size={18} />
           </button>
           <button
@@ -161,7 +138,7 @@ export default function ProfileSuccessScreen({
             animate={{ opacity: 1 }}
             transition={{ delay: 1, duration: 0.3 }}
           >
-            Redirecting to dashboard...
+            Redirecting to Health Intelligence...
           </motion.p>
         )}
       </motion.div>

frontend/src/components/dashboard/DashboardNavbar.tsx

@@ -1,7 +1,7 @@
 import { useState } from 'react';
 import { Link, useLocation, useNavigate } from 'react-router-dom';
 import { motion, AnimatePresence } from 'framer-motion';
-import { Settings, LogOut, Home, LayoutDashboard, Bell, FileText, Activity, Sparkles, Pill, PhoneCall } from 'lucide-react';
+import { Settings, LogOut, Home, LayoutDashboard, Bell, FileText, Activity, Sparkles, Pill, PhoneCall, Network } from 'lucide-react';
 import { logout } from '../../utils/auth';
 import Logo from '../ui/Logo';
 import './DashboardNavbar.css';
@@ -23,6 +23,7 @@ function DashboardNavbar({ userName = 'User', userStatus = '87% Healthy' }: Dash
     { label: 'Voice Agent', path: '/voice-agent', icon: PhoneCall },
     { label: 'AI Summary', path: '/report-summary', icon: Sparkles },
     { label: 'Recommendations', path: '/recommendations', icon: Activity },
+    { label: 'Features', path: '/features', icon: Network },
     { label: 'Medicines', path: '/medicines', icon: Pill },
   ];
 
@@ -120,6 +121,14 @@ function DashboardNavbar({ userName = 'User', userStatus = '87% Healthy' }: Dash
                     <Settings size={16} />
                     Settings
                   </Link>
+                  <Link
+                    to="/features"
+                    className="dashboard-user-dropdown-item"
+                    onClick={() => setIsUserMenuOpen(false)}
+                  >
+                    <Network size={16} />
+                    Features
+                  </Link>
                   <div className="dashboard-user-dropdown-divider" />
                   <button
                     className="dashboard-user-dropdown-item"

frontend/src/pages/Features.css

@@ -423,4 +423,138 @@
         flex-direction: column;
         align-items: flex-start;
     }
+}
+
+/* ===================================================================
+   Sync Overlay  –  shown when arriving from profile questionnaire
+   =================================================================== */
+
+.sync-overlay {
+    position: fixed;
+    inset: 0;
+    z-index: 1000;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    background: rgba(18, 20, 22, 0.82);
+    backdrop-filter: blur(12px);
+    -webkit-backdrop-filter: blur(12px);
+}
+
+.sync-overlay-card {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    text-align: center;
+    gap: 20px;
+    padding: 48px 40px 40px;
+    background: var(--dash-card-bg);
+    border: 1px solid var(--dash-border);
+    border-radius: 24px;
+    max-width: 420px;
+    width: 90%;
+    box-shadow: 0 20px 60px rgba(0, 0, 0, 0.35);
+}
+
+.sync-overlay-icon {
+    width: 64px;
+    height: 64px;
+    border-radius: 50%;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    background: rgba(106, 145, 117, 0.15);
+    color: var(--dash-accent);
+}
+
+.sync-overlay-title {
+    margin: 0;
+    font-size: 1.35rem;
+    font-weight: 700;
+    color: var(--dash-text);
+}
+
+/* Sync steps */
+.sync-steps {
+    display: flex;
+    flex-direction: column;
+    gap: 12px;
+    width: 100%;
+}
+
+.sync-step {
+    display: flex;
+    align-items: center;
+    gap: 12px;
+    padding: 10px 16px;
+    border-radius: 12px;
+    background: rgba(255, 255, 255, 0.03);
+    border: 1px solid transparent;
+    transition: all 0.25s ease;
+}
+
+.sync-step.active {
+    background: rgba(106, 145, 117, 0.08);
+    border-color: rgba(106, 145, 117, 0.25);
+}
+
+.sync-step.done {
+    opacity: 0.7;
+}
+
+.sync-step-icon {
+    width: 28px;
+    height: 28px;
+    border-radius: 8px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    flex-shrink: 0;
+    background: rgba(106, 145, 117, 0.12);
+    color: var(--dash-text-muted);
+    transition: all 0.25s ease;
+}
+
+.sync-step.active .sync-step-icon {
+    background: rgba(106, 145, 117, 0.2);
+    color: var(--dash-accent);
+}
+
+.sync-step.done .sync-step-icon {
+    background: rgba(106, 145, 117, 0.2);
+    color: var(--dash-accent);
+}
+
+.sync-step-label {
+    flex: 1;
+    font-size: 14px;
+    font-weight: 500;
+    color: var(--dash-text-muted);
+    text-align: left;
+    transition: color 0.25s ease;
+}
+
+.sync-step.active .sync-step-label {
+    color: var(--dash-text);
+}
+
+.sync-step-spinner {
+    color: var(--dash-accent);
+    display: flex;
+    align-items: center;
+}
+
+/* Result summaries */
+.sync-overlay-summary {
+    margin: 0;
+    font-size: 14px;
+    color: var(--dash-accent);
+    font-weight: 500;
+}
+
+.sync-overlay-error {
+    margin: 0;
+    font-size: 13px;
+    color: var(--dash-danger);
+    line-height: 1.5;
 }

frontend/src/pages/Features.tsx

@@ -1,5 +1,5 @@
-import { useState, useEffect } from 'react';
-import { motion } from 'framer-motion';
+import { useState, useEffect, useCallback } from 'react';
+import { motion, AnimatePresence } from 'framer-motion';
 import {
     Brain,
     Network,
@@ -9,9 +9,12 @@ import {
     Database,
     Cpu,
     Zap,
-    Link2
+    Link2,
+    Check,
+    RefreshCw,
+    AlertCircle,
 } from 'lucide-react';
-import { useNavigate } from 'react-router-dom';
+import { useNavigate, useLocation } from 'react-router-dom';
 import DashboardNavbar from '../components/dashboard/DashboardNavbar';
 import MemoryDashboard from '../components/MemoryDashboard';
 import HealthGraph from '../components/HealthGraph';
@@ -22,10 +25,86 @@ import './Features.css';
 
 function Features() {
     const navigate = useNavigate();
+    const location = useLocation();
     const [authToken, setAuthToken] = useState<string | null>(null);
     const [userName, setUserName] = useState('User');
     const [loading, setLoading] = useState(true);
 
+    // Sync overlay state – activated when arriving from profile completion
+    const fromProfileSync = !!(location.state as { fromProfileSync?: boolean })?.fromProfileSync;
+    const [syncOverlayVisible, setSyncOverlayVisible] = useState(fromProfileSync);
+    const [syncPhase, setSyncPhase] = useState<'preparing' | 'memory' | 'graph' | 'done' | 'error'>('preparing');
+    const [syncResult, setSyncResult] = useState<{
+        factsSynced: number;
+        memoryOk: boolean;
+        graphOk: boolean;
+        errors: string[];
+    } | null>(null);
+    // Key used to force-remount child components after sync completes
+    const [syncKey, setSyncKey] = useState(0);
+
+    // Clears router state so a page refresh doesn't re-trigger the overlay
+    useEffect(() => {
+        if (fromProfileSync) {
+            window.history.replaceState({}, document.title);
+        }
+    }, [fromProfileSync]);
+
+    // ---- Profile→Memory/Graph sync logic ----
+    const runProfileSync = useCallback(async (token: string) => {
+        setSyncPhase('preparing');
+        // Small visual delay so the user sees the "preparing" step
+        await new Promise(r => setTimeout(r, 800));
+
+        setSyncPhase('memory');
+
+        try {
+            const response = await fetch(`${API_BASE_URL}/api/profile/sync-to-memory`, {
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    'Content-Type': 'application/json',
+                },
+            });
+
+            const payload = await response.json().catch(() => null);
+
+            if (!response.ok || payload?.success === false) {
+                throw new Error(payload?.message || `Sync failed (${response.status})`);
+            }
+
+            const synced = payload?.synced ?? {};
+            // Transition through the "graph" visual phase
+            setSyncPhase('graph');
+            await new Promise(r => setTimeout(r, 600));
+
+            setSyncResult({
+                factsSynced: synced.facts_synced ?? 0,
+                memoryOk: !!synced.memory,
+                graphOk: !!synced.graph,
+                errors: payload?.errors ?? [],
+            });
+            setSyncPhase('done');
+
+            // Force child re-mount so they fetch fresh data
+            setSyncKey(prev => prev + 1);
+
+            // Auto-dismiss overlay after a brief pause
+            setTimeout(() => setSyncOverlayVisible(false), 2200);
+        } catch (err) {
+            console.error('Profile sync error:', err);
+            setSyncResult({
+                factsSynced: 0,
+                memoryOk: false,
+                graphOk: false,
+                errors: [err instanceof Error ? err.message : 'Unknown error'],
+            });
+            setSyncPhase('error');
+            // Auto-dismiss error overlay after longer pause
+            setTimeout(() => setSyncOverlayVisible(false), 3500);
+        }
+    }, []);
+
     useEffect(() => {
         const token = localStorage.getItem('access_token');
         if (!token) {
@@ -44,7 +123,12 @@ function Features() {
             })
             .catch(console.error)
             .finally(() => setLoading(false));
-    }, [navigate]);
+
+        // If arriving from profile completion, trigger the sync
+        if (fromProfileSync) {
+            runProfileSync(token);
+        }
+    }, [navigate, fromProfileSync, runProfileSync]);
 
     if (loading) {
         return (
@@ -69,6 +153,100 @@ function Features() {
 
             <DashboardNavbar userName={userName} userStatus="" />
 
+            {/* Profile Sync Overlay */}
+            <AnimatePresence>
+                {syncOverlayVisible && (
+                    <motion.div
+                        className="sync-overlay"
+                        initial={{ opacity: 0 }}
+                        animate={{ opacity: 1 }}
+                        exit={{ opacity: 0 }}
+                        transition={{ duration: 0.35 }}
+                    >
+                        <motion.div
+                            className="sync-overlay-card"
+                            initial={{ scale: 0.9, opacity: 0 }}
+                            animate={{ scale: 1, opacity: 1 }}
+                            exit={{ scale: 0.95, opacity: 0 }}
+                            transition={{ type: 'spring', stiffness: 200, damping: 22 }}
+                        >
+                            {/* Animated header icon */}
+                            <motion.div
+                                className="sync-overlay-icon"
+                                animate={syncPhase === 'done' ? { scale: [1, 1.15, 1] } : { rotate: 360 }}
+                                transition={
+                                    syncPhase === 'done'
+                                        ? { duration: 0.4 }
+                                        : { repeat: Infinity, duration: 1.8, ease: 'linear' }
+                                }
+                            >
+                                {syncPhase === 'done' ? (
+                                    <Check size={32} />
+                                ) : syncPhase === 'error' ? (
+                                    <AlertCircle size={32} />
+                                ) : (
+                                    <RefreshCw size={32} />
+                                )}
+                            </motion.div>
+
+                            <h2 className="sync-overlay-title">
+                                {syncPhase === 'done'
+                                    ? 'All Set!'
+                                    : syncPhase === 'error'
+                                        ? 'Sync Issue'
+                                        : 'Syncing Your Health Data'}
+                            </h2>
+
+                            {/* Step indicators */}
+                            <div className="sync-steps">
+                                <SyncStep
+                                    label="Analysing profile"
+                                    active={syncPhase === 'preparing'}
+                                    done={syncPhase !== 'preparing'}
+                                    icon={<Database size={16} />}
+                                />
+                                <SyncStep
+                                    label="Syncing to Health Memory"
+                                    active={syncPhase === 'memory'}
+                                    done={['graph', 'done'].includes(syncPhase)}
+                                    icon={<Brain size={16} />}
+                                />
+                                <SyncStep
+                                    label="Building Knowledge Graph"
+                                    active={syncPhase === 'graph'}
+                                    done={syncPhase === 'done'}
+                                    icon={<Network size={16} />}
+                                />
+                            </div>
+
+                            {/* Result summary */}
+                            {syncPhase === 'done' && syncResult && (
+                                <motion.p
+                                    className="sync-overlay-summary"
+                                    initial={{ opacity: 0, y: 8 }}
+                                    animate={{ opacity: 1, y: 0 }}
+                                >
+                                    {syncResult.factsSynced} facts synced
+                                    {syncResult.memoryOk && ' to Memory'}
+                                    {syncResult.memoryOk && syncResult.graphOk && ' &'}
+                                    {syncResult.graphOk && ' Knowledge Graph'}
+                                </motion.p>
+                            )}
+
+                            {syncPhase === 'error' && syncResult && (
+                                <motion.p
+                                    className="sync-overlay-error"
+                                    initial={{ opacity: 0, y: 8 }}
+                                    animate={{ opacity: 1, y: 0 }}
+                                >
+                                    {syncResult.errors[0] || 'Something went wrong. Your data is safe — sync will retry later.'}
+                                </motion.p>
+                            )}
+                        </motion.div>
+                    </motion.div>
+                )}
+            </AnimatePresence>
+
             <div className="features-content">
                 <div className="features-container">
 
@@ -197,6 +375,7 @@ function Features() {
 
                         <div className="section-content">
                             <MemoryDashboard
+                                key={`mem-${syncKey}`}
                                 authToken={authToken || undefined}
                                 apiBaseUrl={API_BASE_URL}
                                 defaultCollapsed={false}
@@ -228,6 +407,7 @@ function Features() {
 
                         <div className="section-content section-content-large">
                             <HealthGraph
+                                key={`graph-${syncKey}`}
                                 authToken={authToken || undefined}
                                 apiBaseUrl={API_BASE_URL}
                                 defaultCollapsed={false}
@@ -259,4 +439,35 @@ function Features() {
     );
 }
 
+/* ------------------------------------------------------------------ */
+/*  Sync step indicator sub-component                                 */
+/* ------------------------------------------------------------------ */
+
+interface SyncStepProps {
+    label: string;
+    active: boolean;
+    done: boolean;
+    icon: React.ReactNode;
+}
+
+function SyncStep({ label, active, done, icon }: SyncStepProps) {
+    return (
+        <div className={`sync-step ${active ? 'active' : ''} ${done ? 'done' : ''}`}>
+            <span className="sync-step-icon">
+                {done ? <Check size={16} /> : icon}
+            </span>
+            <span className="sync-step-label">{label}</span>
+            {active && (
+                <motion.span
+                    className="sync-step-spinner"
+                    animate={{ rotate: 360 }}
+                    transition={{ repeat: Infinity, duration: 1, ease: 'linear' }}
+                >
+                    <RefreshCw size={12} />
+                </motion.span>
+            )}
+        </div>
+    );
+}
+
 export default Features;