feat : Project Memory

.dockerignore

@@ -0,0 +1,51 @@
+# Git
+.git
+.gitignore
+
+# Python
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+.Python
+pip-log.txt
+pip-delete-this-directory.txt
+.venv/
+venv/
+ENV/
+env/
+*.egg-info/
+.pytest_cache/
+
+# Node
+node_modules/
+npm-debug.log
+yarn-error.log
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+*.db
+*.sqlite
+*.log
+.env
+.env.local
+.env.*.local
+
+# Build outputs
+dist/
+build/
+
+# Documentation
+*.md
+LICENSE
+docs/

.gitignore

@@ -0,0 +1,212 @@
+#Agent
+.claude/
+
+#DB
+backend/project_memory.db
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 arymandeshwal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -7,6 +7,108 @@ sdk: docker
 pinned: false
 license: mit
 short_description: Semantic, shared AI project memory.
+tags:
+  - building-mcp-track-enterprise
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+
+## 🎯 Track 1: Building MCP - Enterprise Category
+
+**Project Memory** is a multi-user, multi-project AI memory system powered by MCP (Model Context Protocol). It creates shared project memory where every action gets logged and becomes searchable via semantic search and AI chat.
+
+## 🚀 What We Built
+
+An MCP server that extends LLM capabilities for enterprise teams by:
+- **Persistent Project Memory**: Every task completion generates AI documentation that becomes searchable knowledge
+- **Semantic Search**: Vector-based memory retrieval across all project activities
+- **MCP Tool Integration**: Exposes project management capabilities as MCP tools
+- **Multi-User Collaboration**: Teams can share and search collective knowledge
+
+## 🛠️ MCP Tools Exposed
+
+Our MCP server provides these tools:
+- `create_project`: Initialize a new project workspace
+- `list_projects`: View all available projects
+- `join_project`: Join an existing project
+- `list_tasks`: Get project tasks with status
+- `complete_task`: Mark task as done with AI-generated documentation
+- `memory_search`: Semantic search across project history
+- `list_activity`: View project activity feed
+
+## 📹 Demo Video
+
+[Watch our 3-minute demo showing MCP integration with Claude Desktop](#) *(link to be added)*
+
+## 🏗️ Architecture
+
+```
+┌─────────────────┐     ┌─────────────────┐
+│   Web Frontend  │────▶│  FastAPI Backend │
+│     (React)     │     │   (MCP Client)   │
+└─────────────────┘     └─────────────────┘
+                               │
+                               ▼
+                        ┌─────────────────┐
+                        │   MCP Server    │
+                        │  (TypeScript)   │
+                        └─────────────────┘
+                               │
+                               ▼
+                        ┌─────────────────┐
+                        │  SQLite + Vec   │
+                        │   (Embeddings)  │
+                        └─────────────────┘
+```
+
+## 💡 Key Features
+
+1. **Task Completion Pipeline**: Transforms user work into searchable documentation
+2. **Vector Search**: Semantic retrieval using sqlite-vec embeddings
+3. **Chat Interface**: Natural language queries using MCP tools
+4. **Activity Feed**: Real-time project activity tracking
+5. **Multi-Project Support**: Manage multiple projects with isolated memory
+
+## 🔧 Technical Stack
+
+- **MCP Server**: TypeScript with @modelcontextprotocol/sdk
+- **Backend**: FastAPI (Python) as MCP client
+- **Frontend**: React + Vite + Tailwind CSS
+- **Database**: SQLite with sqlite-vec for embeddings
+- **AI**: Google Generative AI (Gemini) for documentation generation
+- **Deployment**: Docker container for Hugging Face Spaces
+
+## 🎮 How to Use
+
+1. **Create or Join a Project**: Start by creating a new project or joining an existing one
+2. **Complete Tasks**: Mark tasks as done and provide context about your work
+3. **AI Documentation**: System automatically generates searchable documentation
+4. **Search Memory**: Use semantic search to find any past work or decision
+5. **Chat with Memory**: Ask questions about project history using natural language
+
+## 🚢 Deployment
+
+This Space runs as a Docker container combining:
+- FastAPI backend serving as MCP client
+- React frontend for user interface
+- MCP server handling all tool operations
+- SQLite database with vector search capabilities
+
+## 🔐 Environment Variables
+
+Configure in Space settings:
+- `GOOGLE_API_KEY`: For Gemini AI integration
+- `DATABASE_URL`: (Optional) Custom database connection
+
+## 👥 Team
+
+*Add team member names here*
+
+## 📝 License
+
+MIT License - See LICENSE file for details
+
+## 🔗 Links
+
+- [GitHub Repository](https://github.com/YOUR_USERNAME/project-memory)
+- [MCP Documentation](https://modelcontextprotocol.io)
+- [Hackathon Page](https://huggingface.co/MCP-1st-Birthday)

backend/CHANGELOG.md

@@ -0,0 +1,419 @@
+# Project Memory Backend - Changelog
+
+## Current Status: Production Ready
+
+---
+
+## Phase 4: User & Project ID Simplification (2025-11-30)
+
+### Breaking Changes
+
+**User Model - Removed Email**
+| Before | After |
+|--------|-------|
+| `name`, `email` | `first_name`, `last_name` |
+| UUID for ID | `first_name[:3]` + 4 random digits |
+| Email required | No email needed |
+
+**Example User ID:** `Amal Nimmy` → `ama1234`
+
+**Project Model - Name as ID**
+| Before | After |
+|--------|-------|
+| UUID for ID | Project name used as ID |
+| ID auto-generated | User chooses name (must be unique) |
+
+**Example Project ID:** `fastgate` → ID is `fastgate`
+
+### New Features
+
+| Feature | Description |
+|---------|-------------|
+| `check_project_id_available()` | Check if project ID/name is taken |
+| `GET /api/projects/check/{id}` | API endpoint to check availability |
+| `generate_user_id(first_name)` | Generate user ID from first name |
+
+### Updated Files
+
+| File | Changes |
+|------|---------|
+| `app/models.py` | User: removed `email`, added `first_name`/`last_name`, new ID generation |
+| `app/schemas.py` | UserBase/UserCreate: `firstName`, `lastName` (no email) |
+| `app/main.py` | Updated user endpoints, added project ID check endpoint |
+| `app/tools/projects.py` | Project uses name as ID, added `check_project_id_available()` |
+
+### New Unit Tests
+
+| Test File | Coverage |
+|-----------|----------|
+| `tests/test_database.py` | Database init, session management, engine config |
+| `tests/test_user_models.py` | User ID generation, User/Project/Task models, enums |
+| `tests/test_projects.py` | Project creation, joining, ID availability check |
+| `tests/test_schemas.py` | All Pydantic schemas validation |
+
+### Test Results
+```
+57 passed (new unit tests)
+3 passed, 1 xfailed (scenario tests)
+```
+
+### Database Migration
+
+**Important:** Delete the old database to apply schema changes:
+```bash
+del project_memory.db
+# Database will be recreated on next startup
+```
+
+### API Changes
+
+**Create User (Updated):**
+```bash
+curl -X POST http://localhost:8000/api/users \
+  -H "Content-Type: application/json" \
+  -d '{"firstName": "Amal", "lastName": "Nimmy"}'
+# Response: {"id": "ama1234", "firstName": "Amal", "lastName": "Nimmy", ...}
+```
+
+**Check Project ID Availability (New):**
+```bash
+curl http://localhost:8000/api/projects/check/fastgate
+# Response: {"available": true, "project_id": "fastgate"}
+```
+
+**Create Project (Updated):**
+```bash
+curl -X POST http://localhost:8000/api/projects \
+  -H "Content-Type: application/json" \
+  -d '{"name": "fastgate", "description": "Fast API Gateway", "userId": "ama1234"}'
+# Response: {"id": "fastgate", "name": "fastgate", ...}
+```
+
+---
+
+## Architecture
+
+```
+backend/
+├── app/
+│   ├── database.py       # SQLite + SQLAlchemy setup
+│   ├── models.py         # User, Project, Task, LogEntry models
+│   ├── schemas.py        # Pydantic request/response models
+│   ├── main.py           # FastAPI REST API
+│   ├── mcp_server.py     # MCP server with all tools
+│   ├── model_router.py   # Multi-model rotation + multi-key support
+│   ├── llm.py            # Gemini LLM client (uses model_router)
+│   ├── vectorstore.py    # sqlite-vec vector storage
+│   ├── smart_query.py    # Natural language query processing
+│   └── tools/
+│       ├── projects.py   # create_project, list_projects, join_project
+│       ├── tasks.py      # create_task, list_tasks, list_activity
+│       └── memory.py     # complete_task, memory_search
+├── test_*.py             # Test scripts
+├── requirements.txt
+└── .env
+```
+
+---
+
+## Phase 1: Foundation + Intelligence Layer
+
+### Database Models
+
+| Model | Fields |
+|-------|--------|
+| `User` | id, first_name, last_name, avatar_url, created_at |
+| `Project` | id (=name), name, description, created_by, created_at |
+| `ProjectMembership` | project_id, user_id, role (owner/member) |
+| `Task` | id, project_id, title, description, status, assigned_to |
+| `LogEntry` | id, project_id, task_id, user_id, raw_input, generated_doc, tags |
+
+### Enums
+
+| Enum | Values |
+|------|--------|
+| `TaskStatus` | todo, in_progress, done |
+| `ActorType` | human, agent |
+| `ActionType` | task_completed, doc_generated, query_answered |
+
+### MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `create_project` | Create project + add owner membership |
+| `list_projects` | List user's projects with roles |
+| `join_project` | Add user to existing project |
+| `create_task` | Create task in project |
+| `list_tasks` | List tasks with optional status filter |
+| `list_activity` | Get recent LogEntries for project |
+| `complete_task` | Mark done + generate docs + create embedding |
+| `memory_search` | Semantic search + LLM-synthesized answer |
+| `smart_query` | Natural language queries with context awareness |
+
+### LLM Integration (`llm.py`)
+
+| Function | Purpose |
+|----------|---------|
+| `generate_documentation()` | Generate docs from task completion |
+| `synthesize_answer()` | Create answer from search context |
+| `get_embedding()` | Get 768-dim embedding vector |
+
+**Models:** Gemini 2.0 Flash (text) + text-embedding-004 (embeddings)
+
+### Vector Store (`vectorstore.py`)
+
+| Function | Purpose |
+|----------|---------|
+| `init_vectorstore()` | Create tables at startup |
+| `add_embedding()` | Store embedding with metadata |
+| `search()` | Vector similarity search |
+| `delete_by_project()` | Cleanup vectors |
+
+---
+
+## Phase 2: FastAPI REST API
+
+### Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/` | Health check |
+| GET | `/api/projects?userId={id}` | List user's projects |
+| POST | `/api/projects` | Create new project |
+| POST | `/api/projects/{id}/join` | Join existing project |
+| GET | `/api/projects/{id}/tasks?status={s}` | List project tasks |
+| POST | `/api/projects/{id}/tasks` | Create new task |
+| POST | `/api/tasks/{id}/complete` | Complete task with docs |
+| GET | `/api/projects/{id}/activity?limit={n}` | Get activity feed |
+| POST | `/api/projects/{id}/search` | Semantic search |
+| POST | `/api/chat` | Chat with AI |
+
+### API Examples
+
+**Create Project:**
+```bash
+curl -X POST http://localhost:8000/api/projects \
+  -H "Content-Type: application/json" \
+  -d '{"name": "My Project", "description": "Description", "userId": "user-id"}'
+```
+
+**Complete Task:**
+```bash
+curl -X POST http://localhost:8000/api/tasks/{task-id}/complete \
+  -H "Content-Type: application/json" \
+  -d '{"userId": "user-id", "whatIDid": "Implemented login API", "codeSnippet": "..."}'
+```
+
+**Search Memory:**
+```bash
+curl -X POST http://localhost:8000/api/projects/{project-id}/search \
+  -H "Content-Type: application/json" \
+  -d '{"query": "What did we do yesterday?"}'
+```
+
+### Features
+
+- FastAPI with automatic OpenAPI docs (`/docs`, `/redoc`)
+- CORS configured for frontend (localhost:5173, :3000)
+- Pydantic schema validation
+- Error handling with meaningful messages
+- Database initialization on startup
+- Async support for LLM calls
+
+---
+
+## Quick Start
+
+```bash
+cd backend
+
+# Setup
+python -m venv .venv
+.venv\Scripts\activate          # Windows
+pip install -r requirements.txt
+
+# Configure
+# Create .env with GEMINI_API_KEY
+
+# Run
+uvicorn app.main:app --reload
+```
+
+**Server:** http://localhost:8000
+**API Docs:** http://localhost:8000/docs
+
+---
+
+## Environment Variables
+
+```env
+# Multi-key support (recommended) - comma-separated for 2x rate limits
+GEMINI_API_KEYS=key1,key2
+
+# Single key fallback (backward compatible)
+GEMINI_API_KEY=your-key-here
+
+DATABASE_URL=sqlite:///./project_memory.db
+FRONTEND_URL=http://localhost:5173
+```
+
+---
+
+## Dependencies
+
+```
+fastapi==0.115.0
+uvicorn[standard]==0.32.0
+sqlalchemy==2.0.36
+python-dotenv==1.0.1
+google-generativeai
+sqlite-vec
+numpy
+pydantic==2.9.2
+httpx==0.27.2
+python-multipart==0.0.12
+mcp
+```
+
+---
+
+## Troubleshooting
+
+**Port in use:**
+```bash
+netstat -ano | findstr :8000
+taskkill /PID <pid> /F
+```
+
+**Import errors:**
+```bash
+.venv\Scripts\activate
+pip install -r requirements.txt
+```
+
+**Database issues:**
+```bash
+del project_memory.db
+.venv\Scripts\python test_api.py
+```
+
+---
+
+## Test Commands
+
+```bash
+# Run all pytest unit tests (recommended)
+pytest tests/ -v
+
+# Run specific test files
+pytest tests/test_database.py tests/test_user_models.py tests/test_projects.py tests/test_schemas.py -v
+pytest tests/test_scenarios.py -v
+
+# Legacy manual test scripts (not pytest)
+.venv\Scripts\python tests/test_tools.py
+.venv\Scripts\python tests/test_devb.py
+.venv\Scripts\python tests/test_complete_api.py  # Requires running server
+.venv\Scripts\python tests/test_model_router.py
+```
+
+---
+
+## Phase 3: Multi-Model Rotation & Rate Limit Scaling
+
+### Problem
+Gemini 2.0 Flash has only 15 RPM (requests per minute), limiting concurrent users to ~5.
+
+### Solution
+Implemented multi-model rotation with multi-key support to scale from 15 RPM to 330+ RPM.
+
+### New File: `app/model_router.py`
+
+| Component | Purpose |
+|-----------|---------|
+| `ModelRouter` class | Manages model rotation, rate limiting, caching, multi-key support |
+| `_load_api_keys()` | Load API keys from environment (backward compatible) |
+| `_get_next_key()` | Round-robin key selection with health tracking |
+| `_check_rate_limit()` | Per-key, per-model rate limit checking |
+| `generate()` | Main generation with automatic fallback |
+| `get_stats()` | Usage statistics for monitoring |
+
+### Available Models
+
+| Model | RPM/Key | Quality | Use Case |
+|-------|---------|---------|----------|
+| gemini-2.0-flash | 15 | Best | Complex tasks (chat, smart_query) |
+| gemini-2.0-flash-lite | 30 | Good | Documentation generation |
+| gemma-3-27b-it | 30 | Good | Documentation, synthesis |
+| gemma-3-12b-it | 30 | Medium | Simple tasks |
+| gemma-3-4b-it | 30 | Lower | Fallback |
+| gemma-3-1b-it | 30 | Lowest | Emergency fallback |
+
+**Total per key: 165 RPM**
+
+### Task-Based Model Priority
+
+| Task Type | Priority (best → fallback) |
+|-----------|----------------------------|
+| `chat` | gemini-2.0-flash → flash-lite → gemma-3-27b |
+| `smart_query` | gemini-2.0-flash → gemma-3-27b → gemma-3-12b |
+| `documentation` | flash-lite → gemma-3-27b → gemma-3-12b |
+| `synthesis` | gemma-3-27b → gemma-3-12b → gemma-3-4b |
+
+### Multi-Key Support
+
+Configure multiple API keys for doubled rate limits:
+
+```env
+# Option 1: Comma-separated (recommended)
+GEMINI_API_KEYS=key1,key2
+
+# Option 2: Single key (backward compatible)
+GEMINI_API_KEY=your-key
+```
+
+### Key Health Management
+
+| Error Type | Action | Cooldown |
+|------------|--------|----------|
+| Rate limit (429) | Mark unhealthy, try next key | 60 sec |
+| Auth error (401/403) | Mark unhealthy | 24 hours |
+| Quota exceeded | Mark unhealthy, try next key | 60 sec |
+| Other errors | Short cooldown, try next model | 30 sec |
+
+### Response Caching
+
+- **TTL:** 5 minutes
+- **Key format:** `hash(task_type:user_id:prompt[:200])`
+- **Auto-cleanup:** Expired entries removed periodically
+
+### Capacity Summary
+
+| Metric | Before | 1 Key | 2 Keys |
+|--------|--------|-------|--------|
+| Base RPM | 15 | 165 | 330 |
+| With cache | 15 | 300+ | 600+ |
+| Concurrent users | ~5 | ~100 | ~200 |
+| Fallback | None | Auto | Auto + failover |
+
+### Updated Files
+
+| File | Changes |
+|------|---------|
+| `app/model_router.py` | NEW - Multi-model rotation + caching + multi-key |
+| `app/llm.py` | Uses router for `generate_documentation()`, `synthesize_answer()`, `chat_with_tools()` |
+| `app/smart_query.py` | Uses router for model selection |
+| `test_model_router.py` | NEW - 20 test cases for router functionality |
+| `.env` | Added `GEMINI_API_KEYS` for multi-key support |
+
+### Architecture Update
+
+```
+backend/
+├── app/
+│   ├── model_router.py   # NEW: Multi-model rotation + multi-key support
+│   ├── llm.py            # Updated: Uses model router
+│   ├── smart_query.py    # Updated: Uses model router
+│   └── ...
+├── test_model_router.py  # NEW: Router test cases
+└── ...
+```

backend/Dockerfile

@@ -0,0 +1,28 @@
+# Backend Dockerfile
+FROM python:3.11-slim
+
+# Set working directory
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    gcc \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements first for better caching
+COPY requirements.txt .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY . .
+
+# Create directory for database
+RUN mkdir -p /app/data
+
+# Expose port
+EXPOSE 8000
+
+# Run the application
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

backend/app/__init__.py

@@ -0,0 +1 @@
+# Project Memory Backend

backend/app/database.py

@@ -0,0 +1,37 @@
+"""Database connection and session management for Project Memory."""
+
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker, declarative_base
+from pathlib import Path
+
+# Database file location
+DB_PATH = Path(__file__).parent.parent / "project_memory.db"
+DATABASE_URL = f"sqlite:///{DB_PATH}"
+
+# Create engine with SQLite-specific settings
+engine = create_engine(
+    DATABASE_URL,
+    connect_args={"check_same_thread": False},  # Needed for SQLite
+    echo=False,  # Set to True for SQL debugging
+)
+
+# Session factory
+SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
+
+# Base class for models
+Base = declarative_base()
+
+
+def get_db():
+    """Dependency that provides a database session."""
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()
+
+
+def init_db():
+    """Initialize database tables."""
+    from app import models  # noqa: F401 - Import models to register them
+    Base.metadata.create_all(bind=engine)

backend/app/llm.py

@@ -0,0 +1,486 @@
+import google.generativeai as genai
+import json
+import os
+from dotenv import load_dotenv
+
+# Load environment variables
+load_dotenv()
+
+# Validate required environment variable
+GEMINI_API_KEY = os.getenv("GEMINI_API_KEY")
+if not GEMINI_API_KEY:
+    raise ValueError(
+        "GEMINI_API_KEY environment variable is required. "
+        "Please set it in your .env file or environment."
+    )
+
+# Configure Gemini
+genai.configure(api_key=GEMINI_API_KEY)
+
+# Import model router for multi-model rotation
+from app.model_router import generate as router_generate, generate_with_info
+
+
+async def generate_documentation(task_title: str, what_i_did: str, code_snippet: str | None = None) -> dict:
+    """Generate docs for completed task. Returns {summary, details, tags}"""
+    prompt = f"""
+    Generate technical documentation for this completed work.
+
+    Task: {task_title}
+    What was done: {what_i_did}
+    Code: {code_snippet or 'N/A'}
+
+    Return ONLY valid JSON with:
+    - "summary": one-line summary
+    - "details": 2-3 paragraph technical documentation
+    - "tags": array of 3-7 relevant tags
+
+    Response must be pure JSON, no markdown.
+    """
+
+    # Use model router for multi-model rotation
+    text = await router_generate(prompt, task_type="documentation")
+    # Clean response (remove markdown code blocks if present)
+    text = text.strip()
+    if text.startswith("```"):
+        text = text.split("```")[1]
+        if text.startswith("json"):
+            text = text[4:]
+    return json.loads(text.strip())
+
+
+async def synthesize_answer(context: str, query: str) -> str:
+    """Generate answer from context. Returns answer string."""
+    prompt = f"""
+    Based on this project memory:
+    {context}
+
+    Answer: {query}
+
+    Cite specific entries. If info not found, say so.
+    """
+
+    # Use model router for multi-model rotation
+    return await router_generate(prompt, task_type="synthesis")
+
+
+async def get_embedding(text: str) -> list[float]:
+    """Get embedding vector for text using Gemini embedding model."""
+    result = genai.embed_content(
+        model="models/text-embedding-004",
+        content=text
+    )
+    return result['embedding']
+
+
+async def generate_tasks(project_name: str, project_description: str, count: int = 50) -> list[dict]:
+    """Generate demo tasks for a project using LLM.
+
+    Args:
+        project_name: Name of the project
+        project_description: Description of the project
+        count: Number of tasks to generate (max 50)
+
+    Returns:
+        List of tasks with title and description
+    """
+    # Cap at 50 tasks max
+    count = min(count, 50)
+
+    prompt = f"""
+You are a project manager creating demo tasks for a hackathon project.
+
+Project: {project_name}
+Description: {project_description}
+
+Generate exactly {count} simple, demo-friendly tasks for this software project. Each task should be:
+- Simple and quick to complete (5-30 minutes each)
+- Suitable for a demo or hackathon setting
+- Cover typical software development activities (setup, coding, testing, docs, UI)
+
+Include a mix of:
+- Setup tasks (environment, dependencies, config)
+- Feature implementation (simple features)
+- Bug fixes (minor issues)
+- Documentation (README, comments)
+- Testing (basic tests)
+- UI/UX improvements
+
+Return ONLY a valid JSON array with objects containing:
+- "title": short task title (max 100 chars)
+- "description": brief description (1 sentence)
+
+Example:
+[
+  {{"title": "Set up development environment", "description": "Install dependencies and configure local dev environment."}},
+  {{"title": "Add user login button", "description": "Create a login button component in the header."}}
+]
+
+Return ONLY the JSON array, no markdown or extra text.
+"""
+
+    # Use model router for generation
+    text = await router_generate(prompt, task_type="documentation")
+
+    # Clean response (remove markdown code blocks if present)
+    text = text.strip()
+    if text.startswith("```"):
+        lines = text.split("\n")
+        # Remove first and last lines (```json and ```)
+        text = "\n".join(lines[1:-1])
+        if text.startswith("json"):
+            text = text[4:]
+
+    try:
+        tasks = json.loads(text.strip())
+        # Validate structure
+        if not isinstance(tasks, list):
+            raise ValueError("Response is not a list")
+
+        # Ensure each task has required fields
+        validated_tasks = []
+        for task in tasks:
+            if isinstance(task, dict) and "title" in task:
+                validated_tasks.append({
+                    "title": str(task.get("title", ""))[:100],
+                    "description": str(task.get("description", ""))
+                })
+
+        return validated_tasks
+    except json.JSONDecodeError as e:
+        raise ValueError(f"Failed to parse LLM response as JSON: {e}")
+
+
+async def chat_with_tools(messages: list[dict], project_id: str) -> str:
+    """Chat with AI using MCP tools for function calling.
+
+    Args:
+        messages: List of chat messages [{'role': 'user/assistant', 'content': '...'}]
+        project_id: Project ID for context
+
+    Returns:
+        AI response string
+    """
+    from app.tools.projects import list_projects, create_project, join_project
+    from app.tools.tasks import list_tasks, create_task, list_activity
+    from app.tools.memory import complete_task, memory_search
+    from app.model_router import router
+
+    # Define tools for Gemini function calling
+    tools = [
+        {
+            "name": "list_projects",
+            "description": "List all projects for a user",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "userId": {"type": "string", "description": "User ID"}
+                },
+                "required": ["userId"]
+            }
+        },
+        {
+            "name": "list_tasks",
+            "description": "List all tasks for a project",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "projectId": {"type": "string", "description": "Project ID"},
+                    "status": {"type": "string", "enum": ["todo", "in_progress", "done"]}
+                },
+                "required": ["projectId"]
+            }
+        },
+        {
+            "name": "list_activity",
+            "description": "Get recent activity for a project",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "projectId": {"type": "string", "description": "Project ID"},
+                    "limit": {"type": "number", "default": 20}
+                },
+                "required": ["projectId"]
+            }
+        },
+        {
+            "name": "memory_search",
+            "description": "Semantic search across project memory",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "projectId": {"type": "string", "description": "Project ID"},
+                    "query": {"type": "string", "description": "Search query"}
+                },
+                "required": ["projectId", "query"]
+            }
+        }
+    ]
+
+    # Build system message with project context
+    system_message = f"""
+    You are an AI assistant helping users understand their project memory.
+    Current Project ID: {project_id}
+
+    You have access to these tools:
+    - list_projects: List user's projects
+    - list_tasks: List tasks in a project
+    - list_activity: Get recent activity
+    - memory_search: Search project memory semantically
+
+    Use these tools to answer user questions accurately.
+    """
+
+    # Convert messages to Gemini format
+    chat_messages = []
+    for msg in messages:
+        if msg["role"] == "system":
+            system_message = msg["content"]
+        else:
+            chat_messages.append(msg)
+
+    # Build the prompt with tool descriptions
+    tool_prompt = f"""
+{system_message}
+
+To use tools, format your response as:
+TOOL: tool_name
+ARGS: {{"arg1": "value1"}}
+
+Available tools:
+{json.dumps(tools, indent=2)}
+"""
+
+    # Add system context to first message
+    full_messages = [{"role": "user", "content": tool_prompt}] + chat_messages
+
+    # Convert to Gemini chat format
+    chat_history = []
+    for msg in full_messages[:-1]:  # All except last
+        chat_history.append({
+            "role": "user" if msg["role"] == "user" else "model",
+            "parts": [msg["content"]]
+        })
+
+    # Get best available model from router for chat
+    model_name = router.get_model_for_task("chat")
+    if not model_name:
+        raise Exception("All models are rate limited. Please try again in a minute.")
+
+    model = router.models[model_name]
+    router._record_usage(model_name)
+
+    # Start chat session with selected model
+    chat = model.start_chat(history=chat_history)
+
+    # Send last message
+    last_message = full_messages[-1]["content"]
+    response = chat.send_message(last_message)
+
+    # Check if response contains tool call
+    response_text = response.text
+
+    # Simple tool detection
+    if "TOOL:" in response_text and "ARGS:" in response_text:
+        # Parse tool call
+        lines = response_text.split("\n")
+        tool_name = None
+        args = None
+
+        for line in lines:
+            if line.startswith("TOOL:"):
+                tool_name = line.replace("TOOL:", "").strip()
+            elif line.startswith("ARGS:"):
+                args = json.loads(line.replace("ARGS:", "").strip())
+
+        # Execute tool if found
+        if tool_name and args:
+            tool_result = None
+
+            if tool_name == "list_projects":
+                tool_result = list_projects(user_id=args["userId"])
+            elif tool_name == "list_tasks":
+                tool_result = list_tasks(
+                    project_id=args["projectId"],
+                    status=args.get("status")
+                )
+            elif tool_name == "list_activity":
+                tool_result = list_activity(
+                    project_id=args["projectId"],
+                    limit=args.get("limit", 20)
+                )
+            elif tool_name == "memory_search":
+                tool_result = await memory_search(
+                    project_id=args["projectId"],
+                    query=args["query"]
+                )
+
+            # Send tool result back to model
+            if tool_result:
+                follow_up = f"Tool {tool_name} returned: {json.dumps(tool_result)}\n\nBased on this, answer the user's question."
+                final_response = chat.send_message(follow_up)
+                return final_response.text
+
+    return response_text
+
+
+async def task_chat(
+    task_id: str,
+    task_title: str,
+    task_description: str,
+    project_id: str,
+    user_id: str,
+    message: str,
+    history: list[dict],
+    current_datetime: str
+) -> dict:
+    """Chat with AI agent while working on a task.
+
+    The agent can:
+    - Answer questions and give coding advice
+    - Search project memory for context
+    - Complete the task when user indicates they're done
+
+    Args:
+        task_id: ID of the task being worked on
+        task_title: Title of the task
+        task_description: Description of the task
+        project_id: Project ID
+        user_id: User ID working on the task
+        message: User's message
+        history: Conversation history
+        current_datetime: Current timestamp
+
+    Returns:
+        {message: str, taskCompleted?: bool, taskStatus?: str}
+    """
+    from app.tools.memory import complete_task, memory_search
+    from app.model_router import router
+
+    # System prompt with task context
+    system_prompt = f"""You are an AI assistant helping a developer work on a task.
+
+CURRENT TASK:
+- Title: {task_title}
+- Description: {task_description or 'No description'}
+- Task ID: {task_id}
+
+USER: {user_id}
+PROJECT: {project_id}
+CURRENT TIME: {current_datetime}
+
+YOUR CAPABILITIES:
+1. Answer questions and give coding advice related to the task
+2. Search project memory for relevant context (completed tasks, documentation)
+3. Complete the task when the user EXPLICITLY CONFIRMS
+
+TASK COMPLETION FLOW:
+When the user indicates they've finished (e.g., "I'm done", "finished it", describes what they did):
+1. Briefly acknowledge what they accomplished
+2. ASK SIMPLY: "Would you like me to mark this task as complete?" (just this question, nothing more)
+3. WAIT for user confirmation (e.g., "yes", "mark it", "complete it", "sure")
+4. ONLY after explicit confirmation, call the complete_task tool
+
+IMPORTANT:
+- Do NOT call complete_task until the user explicitly confirms
+- Do NOT ask for additional details or descriptions when confirming - just ask yes/no
+- The user has already told you what they did - use that information for the complete_task tool
+
+To use tools, format your response as:
+TOOL: tool_name
+ARGS: {{"arg1": "value1"}}
+RESULT_PENDING
+
+After I provide the tool result, give your final response to the user.
+
+Available tools:
+- memory_search: Search project memory. Args: {{"query": "search terms"}}
+- complete_task: Mark task as complete. Args: {{"what_i_did": "description of work done", "code_snippet": "optional code"}}
+
+Be helpful, concise, and focused on helping complete the task."""
+
+    # Build conversation for the model
+    chat_messages = []
+
+    # Add history (convert role names)
+    for msg in history:
+        role = "model" if msg["role"] == "assistant" else "user"
+        chat_messages.append({
+            "role": role,
+            "parts": [msg["content"]]
+        })
+
+    # Get best available model
+    model_name = router.get_model_for_task("chat")
+    if not model_name:
+        return {"message": "All AI models are temporarily unavailable. Please try again in a minute."}
+
+    model = router.models[model_name]
+    router._record_usage(model_name)
+
+    # Start chat with system context in first message
+    first_message = f"{system_prompt}\n\nUser's first message will follow."
+    chat_history = [{"role": "user", "parts": [first_message]}, {"role": "model", "parts": ["Understood. I'm ready to help you work on this task. What would you like to know or do?"]}]
+
+    # Add conversation history
+    chat_history.extend(chat_messages)
+
+    chat = model.start_chat(history=chat_history)
+
+    # Send user's message
+    response = chat.send_message(message)
+    response_text = response.text
+
+    # Check for tool calls
+    task_completed = False
+    task_status = "in_progress"
+
+    if "TOOL:" in response_text and "ARGS:" in response_text:
+        lines = response_text.split("\n")
+        tool_name = None
+        args = None
+
+        for line in lines:
+            if line.startswith("TOOL:"):
+                tool_name = line.replace("TOOL:", "").strip()
+            elif line.startswith("ARGS:"):
+                try:
+                    args = json.loads(line.replace("ARGS:", "").strip())
+                except json.JSONDecodeError:
+                    continue
+
+        if tool_name and args:
+            tool_result = None
+
+            if tool_name == "memory_search":
+                tool_result = await memory_search(
+                    project_id=project_id,
+                    query=args.get("query", "")
+                )
+            elif tool_name == "complete_task":
+                what_i_did = args.get("what_i_did", message)
+                code_snippet = args.get("code_snippet")
+
+                tool_result = await complete_task(
+                    task_id=task_id,
+                    project_id=project_id,
+                    user_id=user_id,
+                    what_i_did=what_i_did,
+                    code_snippet=code_snippet
+                )
+
+                if "error" not in tool_result:
+                    task_completed = True
+                    task_status = "done"
+
+            # Get follow-up response with tool result
+            if tool_result:
+                follow_up = f"Tool {tool_name} returned: {json.dumps(tool_result)}\n\nProvide your response to the user."
+                final_response = chat.send_message(follow_up)
+                response_text = final_response.text
+
+    return {
+        "message": response_text,
+        "taskCompleted": task_completed,
+        "taskStatus": task_status
+    }

backend/app/main.py

@@ -0,0 +1,544 @@
+"""FastAPI application for Project Memory - API layer calling MCP tools."""
+
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+from contextlib import asynccontextmanager
+from typing import List, Optional
+import os
+from dotenv import load_dotenv
+
+from app import schemas
+from app.schemas import (
+    ProjectCreate, ProjectJoin, Project,
+    TaskCreate, Task, TaskCompleteRequest, TaskCompleteResponse,
+    ActivityResponse, SearchRequest, SearchResponse,
+    SmartQueryRequest, SmartQueryResponse,
+    ChatRequest, ChatResponse, ErrorResponse,
+    UserCreate, User
+)
+
+from app.tools.projects import create_project, list_projects, join_project, check_project_id_available
+from app.tools.tasks import create_task, list_tasks, list_activity
+from app.tools.memory import complete_task, memory_search
+
+# Load environment variables
+load_dotenv()
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Initialize database and vector store on startup."""
+    from app.database import init_db
+    from app.vectorstore import init_vectorstore
+    
+    init_db()
+    init_vectorstore()
+    print("[OK] Database and vector store initialized")
+    yield
+
+
+# Initialize FastAPI app
+app = FastAPI(
+    title="Project Memory API",
+    description="Multi-user, multi-project AI memory system powered by MCP",
+    version="1.0.0",
+    lifespan=lifespan
+)
+
+# Configure CORS
+frontend_url = os.getenv("FRONTEND_URL", "http://localhost:5173")
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=[frontend_url, "http://localhost:5173", "http://localhost:3000"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+# ==================== Health Check ====================
+@app.get("/")
+async def root():
+    """Health check endpoint."""
+    return {"status": "ok", "message": "Project Memory API is running"}
+
+
+# ==================== User Endpoints ====================
+@app.post("/api/users", response_model=schemas.User)
+async def create_user(user: schemas.UserCreate):
+    """Create a new user."""
+    from app.database import get_db
+    from app.models import User, generate_user_id
+    
+    db = next(get_db())
+    
+    # Generate unique user ID (first 3 letters of firstname + 4 random digits)
+    user_id = generate_user_id(user.firstName)
+    
+    # Ensure ID is unique (regenerate if collision)
+    while db.query(User).filter(User.id == user_id).first():
+        user_id = generate_user_id(user.firstName)
+    
+    # Create new user
+    new_user = User(
+        id=user_id,
+        first_name=user.firstName,
+        last_name=user.lastName,
+        avatar_url=user.avatar_url
+    )
+    db.add(new_user)
+    db.commit()
+    db.refresh(new_user)
+    
+    return {
+        "id": new_user.id,
+        "firstName": new_user.first_name,
+        "lastName": new_user.last_name,
+        "avatar_url": new_user.avatar_url,
+        "created_at": new_user.created_at
+    }
+
+
+@app.get("/api/users/{user_id}", response_model=schemas.User)
+async def get_user(user_id: str):
+    """Get user by ID."""
+    from app.database import get_db
+    from app.models import User
+    
+    db = next(get_db())
+    user = db.query(User).filter(User.id == user_id).first()
+    
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+    
+    return {
+        "id": user.id,
+        "firstName": user.first_name,
+        "lastName": user.last_name,
+        "avatar_url": user.avatar_url,
+        "created_at": user.created_at
+    }
+
+
+@app.get("/api/users")
+async def list_users():
+    """List all users."""
+    from app.database import get_db
+    from app.models import User
+    
+    db = next(get_db())
+    users = db.query(User).all()
+    return [{"id": u.id, "firstName": u.first_name, "lastName": u.last_name} for u in users]
+
+
+# ==================== Project Endpoints ====================
+@app.get("/api/projects/check/{project_id}")
+async def check_project_availability(project_id: str):
+    """Check if a project ID is available."""
+    try:
+        result = check_project_id_available(project_id=project_id)
+        return result
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.get("/api/projects")
+async def get_projects(userId: str):
+    """List all projects for a user."""
+    try:
+        result = list_projects(user_id=userId)
+        return result
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/api/projects", response_model=Project)
+async def create_new_project(project: ProjectCreate):
+    """Create a new project."""
+    try:
+        result = create_project(
+            name=project.name,
+            description=project.description,
+            user_id=project.userId
+        )
+        if "error" in result:
+            raise HTTPException(status_code=400, detail=result["error"])
+        return result
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/api/projects/{project_id}/join")
+async def join_existing_project(project_id: str, request: ProjectJoin):
+    """Join an existing project."""
+    try:
+        result = join_project(
+            project_id=project_id,
+            user_id=request.userId
+        )
+        if "error" in result:
+            raise HTTPException(status_code=400, detail=result["error"])
+        return result
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.get("/api/projects/{project_id}/members")
+async def get_project_members(project_id: str):
+    """Get all members of a project."""
+    from app.database import get_db
+    from app.models import Project, ProjectMembership, User
+
+    db = next(get_db())
+    try:
+        # Check project exists
+        project = db.query(Project).filter(Project.id == project_id).first()
+        if not project:
+            raise HTTPException(status_code=404, detail="Project not found")
+
+        # Get all memberships with user details
+        memberships = db.query(ProjectMembership, User).join(
+            User, ProjectMembership.user_id == User.id
+        ).filter(ProjectMembership.project_id == project_id).all()
+
+        members = [
+            {
+                "id": user.id,
+                "firstName": user.first_name,
+                "lastName": user.last_name,
+                "avatar_url": user.avatar_url,
+                "role": membership.role,
+                "joined_at": membership.joined_at.isoformat() if membership.joined_at else None
+            }
+            for membership, user in memberships
+        ]
+
+        return {"members": members}
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+    finally:
+        db.close()
+
+
+# ==================== Task Endpoints ====================
+@app.get("/api/projects/{project_id}/tasks")
+async def get_project_tasks(project_id: str, status: Optional[str] = None):
+    """Get all tasks for a project, optionally filtered by status."""
+    try:
+        result = list_tasks(
+            project_id=project_id,
+            status=status
+        )
+        return result
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/api/projects/{project_id}/tasks", response_model=Task)
+async def create_new_task(project_id: str, task: TaskCreate):
+    """Create a new task in a project."""
+    try:
+        result = create_task(
+            project_id=project_id,
+            title=task.title,
+            description=task.description,
+            assigned_to=task.assignedTo
+        )
+        if "error" in result:
+            raise HTTPException(status_code=400, detail=result["error"])
+        return result
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/api/projects/{project_id}/tasks/generate")
+async def generate_project_tasks(project_id: str, request: dict = None):
+    """Generate demo tasks for a project using AI.
+
+    Does NOT save to database - returns generated tasks for user to edit.
+    Max 50 tasks.
+    """
+    from app.llm import generate_tasks
+    from app.database import get_db
+    from app.models import Project
+
+    db = next(get_db())
+    try:
+        # Get project details
+        project = db.query(Project).filter(Project.id == project_id).first()
+        if not project:
+            raise HTTPException(status_code=404, detail="Project not found")
+
+        # Get count from request, default 50, max 50
+        count = min(request.get("count", 50) if request else 50, 50)
+
+        # Generate tasks using LLM (no user prompt needed)
+        tasks = await generate_tasks(
+            project_name=project.name,
+            project_description=project.description,
+            count=count
+        )
+
+        return {"tasks": tasks}
+    except HTTPException:
+        raise
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+    finally:
+        db.close()
+
+
+@app.post("/api/tasks/{task_id}/complete", response_model=TaskCompleteResponse)
+async def complete_existing_task(task_id: str, request: TaskCompleteRequest):
+    """Complete a task with documentation. Generates AI docs and stores embeddings."""
+    from app.database import get_db
+    from app.models import Task as TaskModel
+
+    db = next(get_db())
+    try:
+        task = db.query(TaskModel).filter(TaskModel.id == task_id).first()
+
+        if not task:
+            raise HTTPException(status_code=404, detail="Task not found")
+
+        result = await complete_task(
+            task_id=task_id,
+            project_id=task.project_id,
+            user_id=request.userId,
+            what_i_did=request.whatIDid,
+            code_snippet=request.codeSnippet
+        )
+
+        if "error" in result:
+            raise HTTPException(status_code=400, detail=result["error"])
+
+        return result
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+    finally:
+        db.close()
+
+
+@app.patch("/api/tasks/{task_id}/status")
+async def update_task_status(task_id: str, request: dict):
+    """Update task status (for kanban board)."""
+    from app.database import get_db
+    from app.models import Task as TaskModel, TaskStatus
+
+    db = next(get_db())
+    try:
+        task = db.query(TaskModel).filter(TaskModel.id == task_id).first()
+
+        if not task:
+            raise HTTPException(status_code=404, detail="Task not found")
+
+        new_status = request.get("status")
+        if new_status not in ["todo", "in_progress", "done"]:
+            raise HTTPException(status_code=400, detail="Invalid status. Must be: todo, in_progress, or done")
+
+        task.status = TaskStatus(new_status)
+        db.commit()
+        db.refresh(task)
+
+        return {
+            "id": str(task.id),
+            "project_id": task.project_id,
+            "title": task.title,
+            "description": task.description,
+            "status": task.status.value,
+            "assigned_to": task.assigned_to,
+            "created_at": task.created_at.isoformat() if task.created_at else None
+        }
+    except HTTPException:
+        raise
+    except Exception as e:
+        db.rollback()
+        raise HTTPException(status_code=500, detail=str(e))
+    finally:
+        db.close()
+
+
+@app.post("/api/tasks/{task_id}/chat")
+async def chat_with_task_agent(task_id: str, request: dict):
+    """Chat with AI agent while working on a task.
+
+    The agent can answer questions, search project memory, and complete tasks.
+    """
+    from app.database import get_db
+    from app.models import Task as TaskModel
+    from app.llm import task_chat
+
+    db = next(get_db())
+    try:
+        # Get task details
+        task = db.query(TaskModel).filter(TaskModel.id == task_id).first()
+        if not task:
+            raise HTTPException(status_code=404, detail="Task not found")
+
+        # Extract request data
+        project_id = request.get("projectId", task.project_id)
+        user_id = request.get("userId")
+        message = request.get("message")
+        history = request.get("history", [])
+        current_datetime = request.get("currentDatetime", "")
+
+        if not user_id:
+            raise HTTPException(status_code=400, detail="userId is required")
+        if not message:
+            raise HTTPException(status_code=400, detail="message is required")
+
+        # Call the task chat function
+        result = await task_chat(
+            task_id=task_id,
+            task_title=task.title,
+            task_description=task.description or "",
+            project_id=project_id,
+            user_id=user_id,
+            message=message,
+            history=history,
+            current_datetime=current_datetime
+        )
+
+        return result
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+    finally:
+        db.close()
+
+
+# ==================== Activity Feed Endpoint ====================
+@app.get("/api/projects/{project_id}/activity")
+async def get_project_activity(project_id: str, limit: int = 20):
+    """Get recent activity for a project."""
+    try:
+        result = list_activity(
+            project_id=project_id,
+            limit=limit
+        )
+        return result
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+# ==================== Search Endpoint ====================
+@app.post("/api/projects/{project_id}/search", response_model=SearchResponse)
+async def search_project_memory(project_id: str, request: SearchRequest):
+    """Semantic search across project memory."""
+    try:
+        result = await memory_search(
+            project_id=project_id,
+            query=request.query,
+            filters=request.filters.dict() if request.filters else None
+        )
+        
+        if "error" in result:
+            raise HTTPException(status_code=400, detail=result["error"])
+        
+        return result
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+# ==================== Smart Query Endpoint ====================
+@app.post("/api/projects/{project_id}/smart-query", response_model=SmartQueryResponse)
+async def smart_query_project(project_id: str, request: SmartQueryRequest):
+    """Natural language query with context awareness.
+
+    Understands queries like:
+    - "What did I do yesterday?"
+    - "What did Alice do today?"
+    - "How does the auth system work?"
+    - "Task 13 status?"
+    """
+    try:
+        from app.smart_query import smart_query
+
+        result = await smart_query(
+            project_id=project_id,
+            query=request.query,
+            current_user_id=request.currentUserId,
+            current_datetime=request.currentDatetime
+        )
+
+        if "error" in result.get("answer", ""):
+            raise HTTPException(status_code=400, detail=result["answer"])
+
+        return result
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+# ==================== Chat Endpoint ====================
+@app.post("/api/chat", response_model=ChatResponse)
+async def chat_with_ai(request: ChatRequest):
+    """Chat with AI using MCP tools."""
+    try:
+        # Import here to avoid circular dependency
+        from app.llm import chat_with_tools
+        
+        # Convert messages to dict format
+        messages = [{"role": msg.role, "content": msg.content} for msg in request.messages]
+        
+        # Call the chat function with tool support
+        result = await chat_with_tools(
+            messages=messages,
+            project_id=request.projectId
+        )
+        
+        return {"message": result}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+# ==================== Error Handlers ====================
+@app.exception_handler(HTTPException)
+async def http_exception_handler(request, exc):
+    """Custom HTTP exception handler."""
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={
+            "error": exc.detail,
+            "status_code": exc.status_code
+        }
+    )
+
+
+@app.exception_handler(Exception)
+async def general_exception_handler(request, exc):
+    """General exception handler."""
+    return JSONResponse(
+        status_code=500,
+        content={
+            "error": "Internal server error",
+            "detail": str(exc)
+        }
+    )
+
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(
+        "app.main:app",
+        host="0.0.0.0",
+        port=8000,
+        reload=True
+    )

backend/app/mcp_server.py

@@ -0,0 +1,256 @@
+"""MCP Server for Project Memory - The Brain of the system."""
+
+import asyncio
+import json
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import Tool, TextContent
+
+from app.database import init_db
+from app.tools.projects import create_project, list_projects, join_project
+from app.tools.tasks import create_task, list_tasks, list_activity
+from app.tools.memory import complete_task, memory_search
+from app.smart_query import smart_query
+from app.vectorstore import init_vectorstore
+
+# Initialize the MCP server
+server = Server("project-memory")
+
+
+# Tool definitions
+TOOLS = [
+    # Project Tools
+    Tool(
+        name="create_project",
+        description="Create a new project and add the creator as owner",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "name": {"type": "string", "description": "Project name"},
+                "description": {"type": "string", "description": "Project description"},
+                "userId": {"type": "string", "description": "ID of the user creating the project"}
+            },
+            "required": ["name", "description", "userId"]
+        }
+    ),
+    Tool(
+        name="list_projects",
+        description="List all projects for a user",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "userId": {"type": "string", "description": "ID of the user"}
+            },
+            "required": ["userId"]
+        }
+    ),
+    Tool(
+        name="join_project",
+        description="Add a user to an existing project",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "projectId": {"type": "string", "description": "ID of the project to join"},
+                "userId": {"type": "string", "description": "ID of the user joining"}
+            },
+            "required": ["projectId", "userId"]
+        }
+    ),
+    # Task Tools
+    Tool(
+        name="create_task",
+        description="Create a new task in a project",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "projectId": {"type": "string", "description": "ID of the project"},
+                "title": {"type": "string", "description": "Task title"},
+                "description": {"type": "string", "description": "Task description"},
+                "assignedTo": {"type": "string", "description": "User ID to assign the task to"}
+            },
+            "required": ["projectId", "title"]
+        }
+    ),
+    Tool(
+        name="list_tasks",
+        description="List all tasks for a project, optionally filtered by status",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "projectId": {"type": "string", "description": "ID of the project"},
+                "status": {
+                    "type": "string",
+                    "enum": ["todo", "in_progress", "done"],
+                    "description": "Optional status filter"
+                }
+            },
+            "required": ["projectId"]
+        }
+    ),
+    Tool(
+        name="list_activity",
+        description="Get recent activity (log entries) for a project",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "projectId": {"type": "string", "description": "ID of the project"},
+                "limit": {"type": "number", "default": 20, "description": "Maximum number of entries"}
+            },
+            "required": ["projectId"]
+        }
+    ),
+    # Memory Tools (placeholders for Dev B to implement)
+    Tool(
+        name="complete_task",
+        description="Mark a task as complete with documentation. Generates AI documentation and stores embeddings.",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "taskId": {"type": "string", "description": "ID of the task to complete"},
+                "projectId": {"type": "string", "description": "ID of the project"},
+                "userId": {"type": "string", "description": "ID of the user completing the task"},
+                "whatIDid": {"type": "string", "description": "Description of what was done"},
+                "codeSnippet": {"type": "string", "description": "Optional code snippet"}
+            },
+            "required": ["taskId", "projectId", "userId", "whatIDid"]
+        }
+    ),
+    Tool(
+        name="memory_search",
+        description="Semantic search across project memory. Returns relevant log entries and AI-synthesized answer.",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "projectId": {"type": "string", "description": "ID of the project to search"},
+                "query": {"type": "string", "description": "Search query"},
+                "filters": {
+                    "type": "object",
+                    "properties": {
+                        "userId": {"type": "string"},
+                        "dateFrom": {"type": "string"},
+                        "dateTo": {"type": "string"},
+                        "tags": {"type": "array", "items": {"type": "string"}}
+                    },
+                    "description": "Optional filters"
+                }
+            },
+            "required": ["projectId", "query"]
+        }
+    ),
+    # Smart Query Tool - LLM-first natural language queries
+    Tool(
+        name="smart_query",
+        description="Natural language query with context awareness. Understands 'yesterday', 'I', user names, task references. Use for questions like 'What did I do yesterday?' or 'How does auth work?'",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "projectId": {"type": "string", "description": "Project ID to query"},
+                "query": {"type": "string", "description": "Natural language query"},
+                "currentUserId": {"type": "string", "description": "ID of user making the query"},
+                "currentDatetime": {"type": "string", "description": "Current datetime ISO format (optional)"}
+            },
+            "required": ["projectId", "query", "currentUserId"]
+        }
+    )
+]
+
+
+@server.list_tools()
+async def handle_list_tools() -> list[Tool]:
+    """Return all available tools."""
+    return TOOLS
+
+
+@server.call_tool()
+async def handle_call_tool(name: str, arguments: dict) -> list[TextContent]:
+    """Handle tool calls by dispatching to the appropriate function."""
+    
+    try:
+        match name:
+            # Project Tools
+            case "create_project":
+                result = create_project(
+                    name=arguments["name"],
+                    description=arguments["description"],
+                    user_id=arguments["userId"]
+                )
+            case "list_projects":
+                result = list_projects(user_id=arguments["userId"])
+            case "join_project":
+                result = join_project(
+                    project_id=arguments["projectId"],
+                    user_id=arguments["userId"]
+                )
+            
+            # Task Tools
+            case "create_task":
+                result = create_task(
+                    project_id=arguments["projectId"],
+                    title=arguments["title"],
+                    description=arguments.get("description"),
+                    assigned_to=arguments.get("assignedTo")
+                )
+            case "list_tasks":
+                result = list_tasks(
+                    project_id=arguments["projectId"],
+                    status=arguments.get("status")
+                )
+            case "list_activity":
+                result = list_activity(
+                    project_id=arguments["projectId"],
+                    limit=arguments.get("limit", 20)
+                )
+            
+            # Memory Tools (Dev B - implemented)
+            case "complete_task":
+                result = await complete_task(
+                    task_id=arguments["taskId"],
+                    project_id=arguments["projectId"],
+                    user_id=arguments["userId"],
+                    what_i_did=arguments["whatIDid"],
+                    code_snippet=arguments.get("codeSnippet")
+                )
+            case "memory_search":
+                result = await memory_search(
+                    project_id=arguments["projectId"],
+                    query=arguments["query"],
+                    filters=arguments.get("filters")
+                )
+
+            # Smart Query Tool
+            case "smart_query":
+                result = await smart_query(
+                    project_id=arguments["projectId"],
+                    query=arguments["query"],
+                    current_user_id=arguments["currentUserId"],
+                    current_datetime=arguments.get("currentDatetime")
+                )
+
+            case _:
+                result = {"error": f"Unknown tool: {name}"}
+        
+        return [TextContent(type="text", text=json.dumps(result, default=str))]
+    
+    except Exception as e:
+        error_result = {"error": str(e)}
+        return [TextContent(type="text", text=json.dumps(error_result))]
+
+
+async def main():
+    """Run the MCP server."""
+    # Initialize database tables
+    init_db()
+    # Initialize vector store for embeddings
+    init_vectorstore()
+    print("Project Memory MCP Server starting...", flush=True)
+    
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(
+            read_stream,
+            write_stream,
+            server.create_initialization_options()
+        )
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

backend/app/model_router.py

@@ -0,0 +1,414 @@
+"""Model Router for multi-model rotation with rate limiting and caching."""
+
+import google.generativeai as genai
+import time
+import hashlib
+import os
+from datetime import datetime, timedelta
+from typing import Optional
+from collections import deque
+import asyncio
+from dotenv import load_dotenv
+
+load_dotenv()
+
+# Cooldown durations in seconds
+KEY_COOLDOWN_RATE_LIMIT = 60  # For 429/quota errors
+KEY_COOLDOWN_OTHER = 30       # For other transient errors
+
+
+def _load_api_keys() -> list[str]:
+    """Load API keys from environment (backward compatible)."""
+    keys_str = os.getenv("GEMINI_API_KEYS", "")
+    if keys_str:
+        return [k.strip() for k in keys_str.split(",") if k.strip()]
+    single_key = os.getenv("GEMINI_API_KEY")
+    return [single_key] if single_key else []
+
+
+# Model configurations with RPM limits and quality tiers
+MODEL_CONFIGS = {
+    "gemini-2.0-flash": {"rpm": 15, "quality": 1},
+    "gemini-2.0-flash-lite": {"rpm": 30, "quality": 2},
+    "gemma-3-27b-it": {"rpm": 30, "quality": 3},
+    "gemma-3-12b-it": {"rpm": 30, "quality": 4},
+    "gemma-3-4b-it": {"rpm": 30, "quality": 5},
+    "gemma-3-1b-it": {"rpm": 30, "quality": 6},
+}
+
+# Task type to model priority mapping (lower quality number = better model)
+TASK_PRIORITIES = {
+    "chat": ["gemini-2.0-flash", "gemini-2.0-flash-lite", "gemma-3-27b-it"],
+    "smart_query": ["gemini-2.0-flash", "gemma-3-27b-it", "gemma-3-12b-it"],
+    "documentation": ["gemini-2.0-flash-lite", "gemma-3-27b-it", "gemma-3-12b-it"],
+    "synthesis": ["gemma-3-27b-it", "gemma-3-12b-it", "gemma-3-4b-it"],
+    "default": ["gemini-2.0-flash", "gemini-2.0-flash-lite", "gemma-3-27b-it",
+                "gemma-3-12b-it", "gemma-3-4b-it", "gemma-3-1b-it"],
+}
+
+# Cache TTL in seconds
+CACHE_TTL = 300  # 5 minutes
+
+# Retry delay in seconds
+RETRY_DELAY = 2.5
+
+
+class ModelRouter:
+    """Manages model rotation, rate limiting, response caching, and multi-key support."""
+
+    def __init__(self):
+        # Load API keys
+        self.api_keys = _load_api_keys()
+        if not self.api_keys:
+            raise ValueError("No API keys found. Set GEMINI_API_KEYS or GEMINI_API_KEY in .env")
+
+        # Key rotation state
+        self.key_index = 0
+        self.key_health: dict[int, dict] = {
+            i: {"healthy": True, "last_error": None, "retry_after": None}
+            for i in range(len(self.api_keys))
+        }
+
+        # Track usage per model per key: {key_idx: {model: deque}}
+        self.usage: dict[int, dict[str, deque]] = {
+            i: {model: deque() for model in MODEL_CONFIGS}
+            for i in range(len(self.api_keys))
+        }
+
+        # Response cache: {cache_key: {"response": str, "timestamp": datetime, "model": str}}
+        self.cache: dict[str, dict] = {}
+
+        # Initialize with first key (models created on-demand for key rotation)
+        self._configure_key(0)
+        self.models: dict[str, genai.GenerativeModel] = {
+            model: genai.GenerativeModel(model) for model in MODEL_CONFIGS
+        }
+
+    def _configure_key(self, key_idx: int):
+        """Configure genai with the specified API key."""
+        genai.configure(api_key=self.api_keys[key_idx])
+
+    def _is_key_healthy(self, key_idx: int) -> bool:
+        """Check if a key is healthy (not in cooldown)."""
+        health = self.key_health[key_idx]
+        if not health["healthy"] and health["retry_after"]:
+            if datetime.now() > health["retry_after"]:
+                health["healthy"] = True
+                health["last_error"] = None
+                health["retry_after"] = None
+        return health["healthy"]
+
+    def _mark_key_unhealthy(self, key_idx: int, error: Exception, cooldown_seconds: int):
+        """Mark a key as unhealthy with cooldown."""
+        self.key_health[key_idx] = {
+            "healthy": False,
+            "last_error": str(error),
+            "retry_after": datetime.now() + timedelta(seconds=cooldown_seconds)
+        }
+
+    def _get_next_key(self) -> tuple[int, str]:
+        """Get next healthy API key using round-robin."""
+        num_keys = len(self.api_keys)
+
+        # Try each key once
+        for _ in range(num_keys):
+            idx = self.key_index % num_keys
+            self.key_index += 1
+            if self._is_key_healthy(idx):
+                return idx, self.api_keys[idx]
+
+        # All keys unhealthy - find the one with earliest retry_after
+        earliest_idx = 0
+        earliest_time = datetime.max
+        for idx, health in self.key_health.items():
+            if health["retry_after"] and health["retry_after"] < earliest_time:
+                earliest_time = health["retry_after"]
+                earliest_idx = idx
+
+        # Reset that key and use it
+        self.key_health[earliest_idx]["healthy"] = True
+        return earliest_idx, self.api_keys[earliest_idx]
+
+    def _get_model_with_key(self, model_name: str, key_idx: int) -> genai.GenerativeModel:
+        """Get a model instance configured with the specified key."""
+        self._configure_key(key_idx)
+        return genai.GenerativeModel(model_name)
+
+    def _get_cache_key(self, task_type: str, user_id: Optional[str], prompt: str) -> str:
+        """Generate cache key from task type, user, and prompt."""
+        # Use first 200 chars of prompt to keep keys reasonable
+        key_string = f"{task_type}:{user_id or 'anon'}:{prompt[:200]}"
+        return hashlib.md5(key_string.encode()).hexdigest()
+
+    def _check_cache(self, cache_key: str) -> Optional[str]:
+        """Check if response is cached and not expired."""
+        if cache_key in self.cache:
+            entry = self.cache[cache_key]
+            if datetime.now() - entry["timestamp"] < timedelta(seconds=CACHE_TTL):
+                return entry["response"]
+            else:
+                # Expired, remove it
+                del self.cache[cache_key]
+        return None
+
+    def _store_cache(self, cache_key: str, response: str, model_used: str):
+        """Store response in cache."""
+        self.cache[cache_key] = {
+            "response": response,
+            "timestamp": datetime.now(),
+            "model": model_used
+        }
+        # Clean old cache entries periodically (every 100 entries)
+        if len(self.cache) > 100:
+            self._clean_cache()
+
+    def _clean_cache(self):
+        """Remove expired cache entries."""
+        now = datetime.now()
+        expired_keys = [
+            key for key, entry in self.cache.items()
+            if now - entry["timestamp"] >= timedelta(seconds=CACHE_TTL)
+        ]
+        for key in expired_keys:
+            del self.cache[key]
+
+    def _check_rate_limit(self, model_name: str, key_idx: int = 0) -> bool:
+        """Check if model is within rate limit for a specific key. Returns True if OK to use."""
+        config = MODEL_CONFIGS[model_name]
+        rpm_limit = config["rpm"]
+        usage_queue = self.usage[key_idx][model_name]
+
+        # Remove timestamps older than 60 seconds
+        now = time.time()
+        while usage_queue and usage_queue[0] < now - 60:
+            usage_queue.popleft()
+
+        # Check if under limit
+        return len(usage_queue) < rpm_limit
+
+    def _record_usage(self, model_name: str, key_idx: int = 0):
+        """Record a usage for rate limiting."""
+        self.usage[key_idx][model_name].append(time.time())
+
+    def get_model_for_task(self, task_type: str) -> Optional[str]:
+        """Get the best available model for a task type (checks all keys)."""
+        priorities = TASK_PRIORITIES.get(task_type, TASK_PRIORITIES["default"])
+
+        # Check across all healthy keys
+        for key_idx in range(len(self.api_keys)):
+            if not self._is_key_healthy(key_idx):
+                continue
+            for model_name in priorities:
+                if self._check_rate_limit(model_name, key_idx):
+                    return model_name
+
+        # All preferred models at limit, try any available model on any key
+        for key_idx in range(len(self.api_keys)):
+            if not self._is_key_healthy(key_idx):
+                continue
+            for model_name in MODEL_CONFIGS:
+                if self._check_rate_limit(model_name, key_idx):
+                    return model_name
+
+        return None
+
+    async def generate(
+        self,
+        prompt: str,
+        task_type: str = "default",
+        user_id: Optional[str] = None,
+        use_cache: bool = True
+    ) -> tuple[str, str]:
+        """Generate response with model rotation, key rotation, and caching.
+
+        Args:
+            prompt: The prompt to send to the model
+            task_type: Type of task (chat, smart_query, documentation, synthesis)
+            user_id: User ID for cache key differentiation
+            use_cache: Whether to use caching (default True)
+
+        Returns:
+            Tuple of (response_text, model_used)
+        """
+        # Check cache first
+        if use_cache:
+            cache_key = self._get_cache_key(task_type, user_id, prompt)
+            cached = self._check_cache(cache_key)
+            if cached:
+                return cached, "cache"
+
+        # Get prioritized models for this task
+        priorities = TASK_PRIORITIES.get(task_type, TASK_PRIORITIES["default"])
+        all_models = list(priorities) + [m for m in MODEL_CONFIGS if m not in priorities]
+
+        last_error = None
+        tried_combinations = set()
+
+        # Try each key/model combination
+        max_attempts = len(self.api_keys) * len(all_models)
+
+        for _ in range(max_attempts):
+            # Get next healthy key
+            key_idx, api_key = self._get_next_key()
+
+            for model_name in all_models:
+                combo = (key_idx, model_name)
+                if combo in tried_combinations:
+                    continue
+
+                # Check rate limit for this key/model
+                if not self._check_rate_limit(model_name, key_idx):
+                    continue
+
+                tried_combinations.add(combo)
+
+                try:
+                    # Get model with this key
+                    model = self._get_model_with_key(model_name, key_idx)
+                    self._record_usage(model_name, key_idx)
+
+                    response = model.generate_content(prompt)
+                    response_text = response.text
+
+                    # Cache the response
+                    if use_cache:
+                        self._store_cache(cache_key, response_text, model_name)
+
+                    return response_text, model_name
+
+                except Exception as e:
+                    error_str = str(e).lower()
+                    last_error = e
+
+                    # Determine cooldown based on error type
+                    if "429" in str(e) or "resource exhausted" in error_str or "quota" in error_str:
+                        # Rate limit - mark key unhealthy, wait briefly, try next
+                        self._mark_key_unhealthy(key_idx, e, KEY_COOLDOWN_RATE_LIMIT)
+                        await asyncio.sleep(RETRY_DELAY)
+                        break  # Try next key
+
+                    elif "401" in str(e) or "403" in str(e) or "invalid" in error_str:
+                        # Auth error - mark key permanently unhealthy
+                        self._mark_key_unhealthy(key_idx, e, 86400)  # 24 hours
+                        break  # Try next key
+
+                    else:
+                        # Other error - short cooldown, try next model
+                        await asyncio.sleep(0.5)
+                        continue
+
+        # All combinations exhausted
+        if last_error:
+            raise Exception(f"All models/keys exhausted. Last error: {last_error}")
+        else:
+            raise Exception("All models are rate limited. Please try again in a minute.")
+
+    async def generate_with_model(
+        self,
+        model_name: str,
+        prompt: str,
+        user_id: Optional[str] = None,
+        use_cache: bool = True
+    ) -> str:
+        """Generate with a specific model (for chat sessions that need consistency).
+
+        Falls back to other models if specified model is rate limited.
+        """
+        response, _ = await self.generate(
+            prompt=prompt,
+            task_type="default",
+            user_id=user_id,
+            use_cache=use_cache
+        )
+        return response
+
+    def get_stats(self) -> dict:
+        """Get current usage stats for monitoring."""
+        now = time.time()
+        stats = {
+            "keys": {
+                "total": len(self.api_keys),
+                "healthy": sum(1 for i in range(len(self.api_keys)) if self._is_key_healthy(i)),
+                "details": {}
+            },
+            "models": {},
+            "cache_size": len(self.cache)
+        }
+
+        # Per-key stats
+        for key_idx in range(len(self.api_keys)):
+            health = self.key_health[key_idx]
+            stats["keys"]["details"][f"key_{key_idx}"] = {
+                "healthy": self._is_key_healthy(key_idx),
+                "last_error": health["last_error"],
+                "retry_after": health["retry_after"].isoformat() if health["retry_after"] else None
+            }
+
+        # Aggregate model usage across all keys
+        for model_name in MODEL_CONFIGS:
+            total_used = 0
+            for key_idx in range(len(self.api_keys)):
+                usage_queue = self.usage[key_idx][model_name]
+                total_used += sum(1 for t in usage_queue if t > now - 60)
+
+            # Limit is per-key, so total limit = per_key_limit * num_keys
+            per_key_limit = MODEL_CONFIGS[model_name]["rpm"]
+            total_limit = per_key_limit * len(self.api_keys)
+
+            stats["models"][model_name] = {
+                "used": total_used,
+                "limit": total_limit,
+                "available": total_limit - total_used
+            }
+
+        return stats
+
+
+# Global router instance
+router = ModelRouter()
+
+
+# Convenience functions
+async def generate(
+    prompt: str,
+    task_type: str = "default",
+    user_id: Optional[str] = None,
+    use_cache: bool = True
+) -> str:
+    """Generate response using model router.
+
+    Args:
+        prompt: The prompt to send
+        task_type: One of 'chat', 'smart_query', 'documentation', 'synthesis', 'default'
+        user_id: User ID for cache differentiation
+        use_cache: Whether to use response cache
+
+    Returns:
+        Response text
+    """
+    response, model = await router.generate(prompt, task_type, user_id, use_cache)
+    return response
+
+
+async def generate_with_info(
+    prompt: str,
+    task_type: str = "default",
+    user_id: Optional[str] = None,
+    use_cache: bool = True
+) -> tuple[str, str]:
+    """Generate response and return which model was used.
+
+    Returns:
+        Tuple of (response_text, model_name)
+    """
+    return await router.generate(prompt, task_type, user_id, use_cache)
+
+
+def get_model_for_task(task_type: str) -> Optional[str]:
+    """Get best available model for a task type."""
+    return router.get_model_for_task(task_type)
+
+
+def get_stats() -> dict:
+    """Get current router stats."""
+    return router.get_stats()

backend/app/models.py

@@ -0,0 +1,146 @@
+"""SQLAlchemy models for Project Memory."""
+
+from sqlalchemy import Column, String, DateTime, ForeignKey, Text, Enum, JSON
+from sqlalchemy.orm import relationship
+from datetime import datetime
+import uuid
+import enum
+import random
+
+from app.database import Base
+
+
+def generate_uuid() -> str:
+    """Generate a new UUID string."""
+    return str(uuid.uuid4())
+
+
+def generate_user_id(first_name: str) -> str:
+    """Generate user ID: first 3 letters of firstname + 4 random digits.
+    
+    Example: 'Amal' -> 'ama1234'
+    """
+    prefix = first_name[:3].lower()
+    suffix = ''.join([str(random.randint(0, 9)) for _ in range(4)])
+    return f"{prefix}{suffix}"
+
+
+class ActorType(str, enum.Enum):
+    """Who performed the action."""
+    human = "human"
+    agent = "agent"
+
+
+class ActionType(str, enum.Enum):
+    """Type of action recorded."""
+    task_completed = "task_completed"
+    doc_generated = "doc_generated"
+    query_answered = "query_answered"
+
+
+class TaskStatus(str, enum.Enum):
+    """Task status states."""
+    todo = "todo"
+    in_progress = "in_progress"
+    done = "done"
+
+
+class User(Base):
+    """User account."""
+    __tablename__ = "users"
+    
+    id = Column(String, primary_key=True)  # Generated as first_name[:3] + 4 random digits
+    first_name = Column(String, nullable=False)
+    last_name = Column(String, nullable=False)
+    avatar_url = Column(String, nullable=True)
+    created_at = Column(DateTime, default=datetime.utcnow)
+    
+    # Relationships
+    memberships = relationship("ProjectMembership", back_populates="user")
+    created_projects = relationship("Project", back_populates="creator")
+    log_entries = relationship("LogEntry", back_populates="user")
+    
+    @property
+    def name(self) -> str:
+        """Full name for backward compatibility."""
+        return f"{self.first_name} {self.last_name}"
+
+
+class Project(Base):
+    """Project that contains tasks and memory.
+
+    Option A: project name is also the stable project ID. We persist the ID explicitly
+    from the tools layer (create_project uses the provided name as id).
+    """
+    __tablename__ = "projects"
+    
+    # ID is provided by callers (equal to the project name); no UUID default
+    id = Column(String, primary_key=True)
+    name = Column(String, nullable=False)
+    description = Column(Text, nullable=True)
+    created_at = Column(DateTime, default=datetime.utcnow)
+    created_by = Column(String, ForeignKey("users.id"), nullable=True)
+    
+    # Relationships
+    creator = relationship("User", back_populates="created_projects")
+    memberships = relationship("ProjectMembership", back_populates="project")
+    tasks = relationship("Task", back_populates="project")
+    log_entries = relationship("LogEntry", back_populates="project")
+
+
+class ProjectMembership(Base):
+    """Association between users and projects."""
+    __tablename__ = "project_memberships"
+    
+    id = Column(String, primary_key=True, default=generate_uuid)
+    project_id = Column(String, ForeignKey("projects.id"), nullable=False)
+    user_id = Column(String, ForeignKey("users.id"), nullable=False)
+    role = Column(String, default="member")  # "owner" or "member"
+    joined_at = Column(DateTime, default=datetime.utcnow)
+    
+    # Relationships
+    project = relationship("Project", back_populates="memberships")
+    user = relationship("User", back_populates="memberships")
+
+
+class Task(Base):
+    """Task within a project."""
+    __tablename__ = "tasks"
+    
+    id = Column(String, primary_key=True, default=generate_uuid)
+    project_id = Column(String, ForeignKey("projects.id"), nullable=False)
+    title = Column(String, nullable=False)
+    description = Column(Text, nullable=True)
+    status = Column(Enum(TaskStatus), default=TaskStatus.todo)
+    assigned_to = Column(String, nullable=True)  # userId or "agent"
+    created_at = Column(DateTime, default=datetime.utcnow)
+    completed_at = Column(DateTime, nullable=True)
+    
+    # Relationships
+    project = relationship("Project", back_populates="tasks")
+    log_entries = relationship("LogEntry", back_populates="task")
+
+
+class LogEntry(Base):
+    """
+    The core of project memory.
+    Records what was done, by whom, and stores LLM-generated documentation.
+    """
+    __tablename__ = "log_entries"
+    
+    id = Column(String, primary_key=True, default=generate_uuid)
+    project_id = Column(String, ForeignKey("projects.id"), nullable=False)
+    task_id = Column(String, ForeignKey("tasks.id"), nullable=True)
+    user_id = Column(String, ForeignKey("users.id"), nullable=True)
+    actor_type = Column(Enum(ActorType), nullable=False)
+    action_type = Column(Enum(ActionType), nullable=False)
+    raw_input = Column(Text, nullable=False)  # What user typed
+    code_snippet = Column(Text, nullable=True)  # Optional code
+    generated_doc = Column(Text, nullable=False)  # LLM-generated documentation
+    tags = Column(JSON, default=list)  # Extracted tags
+    created_at = Column(DateTime, default=datetime.utcnow)
+    
+    # Relationships
+    project = relationship("Project", back_populates="log_entries")
+    task = relationship("Task", back_populates="log_entries")
+    user = relationship("User", back_populates="log_entries")

backend/app/schemas.py

@@ -0,0 +1,173 @@
+"""Pydantic schemas for FastAPI request/response models."""
+
+from pydantic import BaseModel
+from typing import Optional, List, Dict, Any
+from datetime import datetime
+
+
+# ==================== User Schemas ====================
+class UserBase(BaseModel):
+    firstName: str
+    lastName: str
+    avatar_url: Optional[str] = None
+
+
+class UserCreate(UserBase):
+    pass
+
+
+class User(UserBase):
+    id: str
+    created_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+# ==================== Project Schemas ====================
+class ProjectBase(BaseModel):
+    name: str
+    description: str
+
+
+class ProjectCreate(ProjectBase):
+    userId: str
+
+
+class ProjectJoin(BaseModel):
+    userId: str
+
+
+class Project(ProjectBase):
+    id: str
+    created_by: str
+    created_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+class ProjectWithRole(Project):
+    role: str  # "owner" or "member"
+
+
+# ==================== Task Schemas ====================
+class TaskBase(BaseModel):
+    title: str
+    description: Optional[str] = None
+
+
+class TaskCreate(TaskBase):
+    assignedTo: Optional[str] = None
+
+
+class Task(TaskBase):
+    id: str
+    project_id: str
+    status: str  # "todo", "in_progress", "done"
+    assigned_to: Optional[str] = None
+    created_at: datetime
+    completed_at: Optional[datetime] = None
+
+    class Config:
+        from_attributes = True
+
+
+# ==================== Task Completion Schemas ====================
+class TaskCompleteRequest(BaseModel):
+    userId: str
+    whatIDid: str
+    codeSnippet: Optional[str] = None
+
+
+class TaskCompleteResponse(BaseModel):
+    success: bool
+    log_entry_id: str
+
+
+# ==================== Activity Log Schemas ====================
+class LogEntry(BaseModel):
+    id: str
+    project_id: str
+    task_id: Optional[str] = None
+    user_id: Optional[str] = None
+    actor_type: str  # "human" or "agent"
+    action_type: str  # "task_completed", "doc_generated", "query_answered"
+    raw_input: str
+    code_snippet: Optional[str] = None
+    generated_doc: str
+    tags: List[str] = []
+    created_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+class ActivityResponse(BaseModel):
+    entries: List[LogEntry]
+
+
+# ==================== Search Schemas ====================
+class SearchFilters(BaseModel):
+    userId: Optional[str] = None
+    dateFrom: Optional[str] = None
+    dateTo: Optional[str] = None
+    tags: Optional[List[str]] = None
+
+
+class SearchRequest(BaseModel):
+    query: str
+    filters: Optional[SearchFilters] = None
+
+
+class SearchSource(BaseModel):
+    id: str
+    summary: str
+
+
+class SearchResponse(BaseModel):
+    answer: str
+    sources: List[SearchSource]
+
+
+# ==================== Smart Query Schemas ====================
+class SmartQueryRequest(BaseModel):
+    query: str
+    currentUserId: str
+    currentDatetime: Optional[str] = None
+
+
+class SmartQuerySource(BaseModel):
+    id: str
+    type: str  # "activity", "memory", "task"
+    summary: str
+    date: Optional[str] = None
+    relevance: Optional[float] = None
+    status: Optional[str] = None
+
+
+class SmartQueryResponse(BaseModel):
+    answer: str
+    tools_used: List[str] = []
+    sources: List[SmartQuerySource] = []
+
+
+# ==================== Chat Schemas ====================
+class ChatMessage(BaseModel):
+    role: str  # "user", "assistant", "system"
+    content: str
+
+
+class ChatRequest(BaseModel):
+    messages: List[ChatMessage]
+    projectId: str
+
+
+class ChatResponse(BaseModel):
+    message: str
+
+
+# ==================== Error Schema ====================
+class ErrorResponse(BaseModel):
+    error: str
+    detail: Optional[str] = None

backend/app/smart_query.py

@@ -0,0 +1,684 @@
+"""
+Smart Query - LLM-First implementation using Gemini function calling.
+
+Enables natural language queries like:
+- "What did I do yesterday?"
+- "What did dev_a do today?"
+- "Did dev_b complete task abc?"
+- "How did the xyz api get implemented?"
+- "Task 13 status?"
+"""
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from typing import Optional
+import google.generativeai as genai
+import json
+import os
+from dotenv import load_dotenv
+
+# Load environment variables
+load_dotenv()
+
+from app.database import SessionLocal
+from app.models import Task, LogEntry, User, TaskStatus, ProjectMembership
+from app.llm import get_embedding
+from app.vectorstore import search
+from app.model_router import router as model_router
+
+# Configure Gemini (reuse existing config pattern from llm.py)
+genai.configure(api_key=os.getenv("GEMINI_API_KEY"))
+
+
+@dataclass
+class QueryContext:
+    """Context from frontend for query processing."""
+    current_user_id: str
+    current_datetime: datetime
+    project_id: str
+
+
+# Gemini Function Declarations
+GEMINI_TOOLS = [
+    genai.protos.Tool(
+        function_declarations=[
+            genai.protos.FunctionDeclaration(
+                name="get_user_activity",
+                description="Get activity/log entries for a user within a date range",
+                parameters=genai.protos.Schema(
+                    type=genai.protos.Type.OBJECT,
+                    properties={
+                        "user_id": genai.protos.Schema(type=genai.protos.Type.STRING, description="User ID (use 'current' for the current user)"),
+                        "user_name": genai.protos.Schema(type=genai.protos.Type.STRING, description="User name to look up"),
+                        "date_from": genai.protos.Schema(type=genai.protos.Type.STRING, description="Start date ISO format"),
+                        "date_to": genai.protos.Schema(type=genai.protos.Type.STRING, description="End date ISO format"),
+                    },
+                    required=["date_from", "date_to"]
+                )
+            ),
+            genai.protos.FunctionDeclaration(
+                name="get_task_status",
+                description="Get status and details of a specific task by ID or title",
+                parameters=genai.protos.Schema(
+                    type=genai.protos.Type.OBJECT,
+                    properties={
+                        "task_id": genai.protos.Schema(type=genai.protos.Type.STRING, description="Task ID"),
+                        "task_title": genai.protos.Schema(type=genai.protos.Type.STRING, description="Task title to search"),
+                    }
+                )
+            ),
+            genai.protos.FunctionDeclaration(
+                name="check_task_completion",
+                description="Check if a task was completed, optionally by a specific user",
+                parameters=genai.protos.Schema(
+                    type=genai.protos.Type.OBJECT,
+                    properties={
+                        "task_title": genai.protos.Schema(type=genai.protos.Type.STRING, description="Task title"),
+                        "user_name": genai.protos.Schema(type=genai.protos.Type.STRING, description="User to check"),
+                    },
+                    required=["task_title"]
+                )
+            ),
+            genai.protos.FunctionDeclaration(
+                name="semantic_search",
+                description="Search project memory semantically for concepts, implementations, or how things work",
+                parameters=genai.protos.Schema(
+                    type=genai.protos.Type.OBJECT,
+                    properties={
+                        "search_query": genai.protos.Schema(type=genai.protos.Type.STRING, description="Semantic search query"),
+                    },
+                    required=["search_query"]
+                )
+            ),
+            genai.protos.FunctionDeclaration(
+                name="list_users",
+                description="List all users/members in the project",
+                parameters=genai.protos.Schema(
+                    type=genai.protos.Type.OBJECT,
+                    properties={}
+                )
+            ),
+            genai.protos.FunctionDeclaration(
+                name="list_tasks",
+                description="List tasks in the project, optionally filtered by status. Use this for queries like 'what tasks are done', 'pending tasks', 'all tasks'",
+                parameters=genai.protos.Schema(
+                    type=genai.protos.Type.OBJECT,
+                    properties={
+                        "status": genai.protos.Schema(
+                            type=genai.protos.Type.STRING,
+                            description="Filter by status: 'todo', 'in_progress', 'done', or 'all' for no filter"
+                        ),
+                        "assigned_to": genai.protos.Schema(
+                            type=genai.protos.Type.STRING,
+                            description="Filter by assignee user ID or 'agent'"
+                        ),
+                        "limit": genai.protos.Schema(
+                            type=genai.protos.Type.INTEGER,
+                            description="Max number of tasks to return (default 20)"
+                        ),
+                    }
+                )
+            ),
+        ]
+    )
+]
+
+
+async def smart_query(
+    project_id: str,
+    query: str,
+    current_user_id: str,
+    current_datetime: Optional[str] = None
+) -> dict:
+    """
+    Main entry point for LLM-first query processing.
+
+    Args:
+        project_id: Project to query
+        query: Natural language query
+        current_user_id: ID of user making the query
+        current_datetime: ISO datetime string (optional, defaults to now)
+
+    Returns:
+        {answer: str, tools_used: list[str], sources: list[dict]}
+    """
+    # Parse datetime
+    dt = datetime.fromisoformat(current_datetime) if current_datetime else datetime.now()
+    context = QueryContext(current_user_id, dt, project_id)
+
+    # Build system prompt with context
+    yesterday = (dt - timedelta(days=1)).date()
+    today = dt.date()
+
+    system_prompt = f"""You are a project memory assistant helping users find information about their project work.
+
+CONTEXT:
+- Current User ID: {context.current_user_id}
+- Current Date/Time: {dt.isoformat()}
+- Project ID: {context.project_id}
+
+RULES:
+1. When user says "I", "me", or "my" - use user_id="{context.current_user_id}"
+2. "today" = {today}
+3. "yesterday" = {yesterday}
+4. Convert relative dates to absolute ISO format before calling tools
+5. Use the tools to fetch real data - NEVER make up information
+6. If you need to resolve a user name to ID, call list_users first
+7. Always cite sources in your answer when available
+"""
+
+    try:
+        # Get best available model from router for smart_query task
+        model_name = model_router.get_model_for_task("smart_query")
+        if not model_name:
+            return {
+                "answer": "All models are rate limited. Please try again in a minute.",
+                "tools_used": [],
+                "sources": []
+            }
+
+        # Record usage for rate limiting
+        model_router._record_usage(model_name)
+
+        # Create model with function calling using selected model
+        model = genai.GenerativeModel(
+            model_name,
+            tools=GEMINI_TOOLS,
+            system_instruction=system_prompt
+        )
+
+        # Start chat and send query
+        chat = model.start_chat()
+        response = chat.send_message(query)
+
+        # Tool calling loop
+        tool_results = []
+        max_iterations = 5
+
+        for _ in range(max_iterations):
+            # Check for function calls in response
+            function_calls = []
+            for part in response.candidates[0].content.parts:
+                if hasattr(part, 'function_call') and part.function_call.name:
+                    function_calls.append(part.function_call)
+
+            if not function_calls:
+                break  # No more function calls, we have final answer
+
+            # Execute each function call
+            function_responses = []
+            for fn_call in function_calls:
+                result = await execute_tool(fn_call.name, dict(fn_call.args), context)
+                tool_results.append({"tool": fn_call.name, "args": dict(fn_call.args), "result": result})
+
+                function_responses.append(
+                    genai.protos.Part(
+                        function_response=genai.protos.FunctionResponse(
+                            name=fn_call.name,
+                            response={"result": json.dumps(result, default=str)}
+                        )
+                    )
+                )
+
+            # Send function results back to model
+            response = chat.send_message(function_responses)
+
+        # Extract final text answer
+        final_answer = ""
+        for part in response.candidates[0].content.parts:
+            if hasattr(part, 'text'):
+                final_answer += part.text
+
+        return {
+            "answer": final_answer,
+            "tools_used": [tr["tool"] for tr in tool_results],
+            "sources": extract_sources(tool_results)
+        }
+
+    except Exception as e:
+        return {
+            "answer": f"Error processing query: {str(e)}",
+            "tools_used": [],
+            "sources": []
+        }
+
+
+async def execute_tool(name: str, args: dict, context: QueryContext) -> dict:
+    """Execute a tool by name with given arguments."""
+    db = SessionLocal()
+
+    try:
+        match name:
+            case "get_user_activity":
+                return _tool_get_user_activity(db, context, args)
+            case "get_task_status":
+                return _tool_get_task_status(db, context.project_id, args)
+            case "check_task_completion":
+                return _tool_check_completion(db, context.project_id, args)
+            case "semantic_search":
+                return await _tool_semantic_search(context.project_id, args)
+            case "list_users":
+                return _tool_list_users(db, context.project_id)
+            case "list_tasks":
+                return _tool_list_tasks(db, context.project_id, args)
+            case _:
+                return {"error": f"Unknown tool: {name}"}
+    finally:
+        db.close()
+
+
+def _get_recent_work_hint(db, user_id: str, project_id: str) -> str:
+    """Get a short hint about user's recent work for disambiguation."""
+    recent_entry = db.query(LogEntry).filter(
+        LogEntry.user_id == user_id,
+        LogEntry.project_id == project_id
+    ).order_by(LogEntry.created_at.desc()).first()
+
+    if recent_entry:
+        # Use first 50 chars of raw_input or first tag
+        if recent_entry.raw_input:
+            return f"worked on: {recent_entry.raw_input[:50]}..."
+        elif recent_entry.tags:
+            return f"worked on: {recent_entry.tags[0]}"
+    return "no recent activity"
+
+
+def _resolve_user_in_project(db, project_id: str, user_name: str) -> dict:
+    """
+    Resolve a user by name within project scope only using first/last name fields.
+
+    Returns:
+        {"found": True, "user_id": "...", "user_name": "..."} - single match
+        {"found": False, "reason": "not_found"} - no matches
+        {"found": False, "reason": "ambiguous", "options": [...]} - multiple matches
+    """
+    # Query users who are members of this project and match first or last name
+    matches = db.query(User, ProjectMembership).join(
+        ProjectMembership, User.id == ProjectMembership.user_id
+    ).filter(
+        ProjectMembership.project_id == project_id,
+        User.name.ilike(f"%{user_name}%")
+    ).all()
+
+    if not matches:
+        # Try first_name or last_name separately as fallback
+        matches = db.query(User, ProjectMembership).join(
+            ProjectMembership, User.id == ProjectMembership.user_id
+        ).filter(
+            ProjectMembership.project_id == project_id,
+            (User.first_name.ilike(f"%{user_name}%") | User.last_name.ilike(f"%{user_name}%"))
+        ).all()
+
+    if not matches:
+        return {
+            "found": False,
+            "reason": "not_found",
+            "message": f"No project member named '{user_name}' found"
+        }
+
+    if len(matches) == 1:
+        user, membership = matches[0]
+        return {
+            "found": True,
+            "user_id": str(user.id),
+            "user_name": f"{user.first_name} {user.last_name}"
+        }
+
+    # Multiple matches - return disambiguation options
+    options = []
+    for user, membership in matches:
+        options.append({
+            "user_id": str(user.id),
+            "name": user.name,
+            "role": membership.role,
+            "recent_work": _get_recent_work_hint(db, str(user.id), project_id)
+        })
+
+    return {
+        "found": False,
+        "reason": "ambiguous",
+        "message": f"Found {len(matches)} project members matching '{user_name}'",
+        "options": options
+    }
+
+
+def _tool_get_user_activity(db, context: QueryContext, args: dict) -> dict:
+    """Get user activity within date range."""
+    user_id = args.get("user_id")
+    user_name = args.get("user_name")
+    resolved_user_name = None
+
+    # Handle "current" user reference
+    if user_id == "current" or user_id == context.current_user_id:
+        user_id = context.current_user_id
+
+    # Resolve user name to ID using project-scoped resolver
+    if user_name and not user_id:
+        resolution = _resolve_user_in_project(db, context.project_id, user_name)
+
+        if not resolution["found"]:
+            # Return disambiguation or not found directly
+            return resolution
+
+        user_id = resolution["user_id"]
+        resolved_user_name = resolution["user_name"]
+
+    # Parse dates (handle 'Z' suffix and various formats)
+    date_from_str = args["date_from"].replace('Z', '+00:00').replace('+00:00', '')
+    date_to_str = args["date_to"].replace('Z', '+00:00').replace('+00:00', '')
+
+    try:
+        date_from = datetime.fromisoformat(date_from_str)
+    except ValueError:
+        # Try parsing just date
+        date_from = datetime.strptime(date_from_str[:10], '%Y-%m-%d')
+
+    try:
+        date_to = datetime.fromisoformat(date_to_str)
+    except ValueError:
+        date_to = datetime.strptime(date_to_str[:10], '%Y-%m-%d') + timedelta(days=1)
+
+    # Query LogEntry table
+    query = db.query(LogEntry).filter(
+        LogEntry.project_id == context.project_id,
+        LogEntry.created_at >= date_from,
+        LogEntry.created_at <= date_to
+    )
+
+    if user_id:
+        query = query.filter(LogEntry.user_id == user_id)
+
+    entries = query.order_by(LogEntry.created_at.desc()).all()
+
+    # Get user name for response (use already resolved name if available)
+    if not resolved_user_name and user_id:
+        resolved_user = db.query(User).filter(User.id == user_id).first()
+        resolved_user_name = (
+            f"{resolved_user.first_name} {resolved_user.last_name}"
+            if resolved_user else None
+        )
+
+    return {
+        "user_id": user_id,
+        "user_name": resolved_user_name,
+        "date_range": {"from": args["date_from"], "to": args["date_to"]},
+        "count": len(entries),
+        "activities": [
+            {
+                "id": str(e.id),
+                "task_id": str(e.task_id) if e.task_id else None,
+                "what_was_done": e.raw_input,
+                "summary": e.generated_doc[:200] if e.generated_doc else None,
+                "tags": e.tags or [],
+                "timestamp": e.created_at.isoformat()
+            }
+            for e in entries
+        ]
+    }
+
+
+def _tool_get_task_status(db, project_id: str, args: dict) -> dict:
+    """Get task by ID or title."""
+    task_id = args.get("task_id")
+    task_title = args.get("task_title")
+
+    query = db.query(Task).filter(Task.project_id == project_id)
+
+    if task_id:
+        # Try exact match first, then partial
+        task = query.filter(Task.id == task_id).first()
+        if not task:
+            task = query.filter(Task.id.like(f"%{task_id}%")).first()
+    elif task_title:
+        task = query.filter(Task.title.ilike(f"%{task_title}%")).first()
+    else:
+        return {"error": "Provide either task_id or task_title"}
+
+    if not task:
+        return {"found": False, "message": "Task not found"}
+
+    # Get completion log if exists
+    log_entry = db.query(LogEntry).filter(LogEntry.task_id == task.id).first()
+
+    return {
+        "found": True,
+        "task": {
+            "id": str(task.id),
+            "title": task.title,
+            "description": task.description,
+            "status": task.status.value,
+            "assigned_to": task.assigned_to,
+            "created_at": task.created_at.isoformat(),
+            "completed_at": task.completed_at.isoformat() if task.completed_at else None
+        },
+        "completion_details": {
+            "what_was_done": log_entry.raw_input,
+            "completed_by": str(log_entry.user_id) if log_entry.user_id else None,
+            "documentation": log_entry.generated_doc[:300] if log_entry.generated_doc else None
+        } if log_entry else None
+    }
+
+
+def _tool_check_completion(db, project_id: str, args: dict) -> dict:
+    """Check if task was completed, optionally by specific user."""
+    task_title = args["task_title"]
+    user_name = args.get("user_name")
+    user_id = None
+
+    # Find task
+    task = db.query(Task).filter(
+        Task.project_id == project_id,
+        Task.title.ilike(f"%{task_title}%")
+    ).first()
+
+    if not task:
+        return {"found": False, "message": f"Task matching '{task_title}' not found"}
+
+    # Resolve user name using project-scoped resolver
+    if user_name:
+        resolution = _resolve_user_in_project(db, project_id, user_name)
+
+        if not resolution["found"]:
+            # Return disambiguation or not found directly
+            return resolution
+
+        user_id = resolution["user_id"]
+
+    # Check completion log
+    log_query = db.query(LogEntry).filter(LogEntry.task_id == task.id)
+
+    if user_id:
+        log_query = log_query.filter(LogEntry.user_id == user_id)
+
+    log_entry = log_query.first()
+
+    return {
+        "found": True,
+        "task_title": task.title,
+        "task_id": str(task.id),
+        "status": task.status.value,
+        "is_completed": task.status == TaskStatus.done,
+        "completed_by_specified_user": log_entry is not None if user_name else None,
+        "completion_details": {
+            "what_was_done": log_entry.raw_input,
+            "timestamp": log_entry.created_at.isoformat()
+        } if log_entry else None
+    }
+
+
+async def _tool_semantic_search(project_id: str, args: dict) -> dict:
+    """Semantic search using vector store."""
+    query_text = args["search_query"]
+
+    # Get embedding (reuse existing function from llm.py)
+    query_embedding = await get_embedding(query_text)
+
+    # Search vector store
+    results = search(
+        query_embedding=query_embedding,
+        project_id=project_id,
+        n_results=10
+    )
+
+    if not results:
+        return {"query": query_text, "count": 0, "results": []}
+
+    # Enrich with full log entries
+    db = SessionLocal()
+    try:
+        log_ids = [r["id"] for r in results]
+        entries = db.query(LogEntry).filter(LogEntry.id.in_(log_ids)).all()
+        entry_map = {str(e.id): e for e in entries}
+
+        enriched = []
+        for r in results:
+            entry = entry_map.get(r["id"])
+            enriched.append({
+                "id": r["id"],
+                "relevance_score": round(1 - r.get("distance", 0), 3),
+                "what_was_done": entry.raw_input if entry else r["metadata"].get("text", "")[:200],
+                "documentation": entry.generated_doc[:300] if entry and entry.generated_doc else None,
+                "tags": entry.tags if entry else [],
+                "timestamp": entry.created_at.isoformat() if entry else r["metadata"].get("created_at")
+            })
+
+        return {"query": query_text, "count": len(enriched), "results": enriched}
+    finally:
+        db.close()
+
+
+def _tool_list_users(db, project_id: str) -> dict:
+    """List all project members."""
+    memberships = db.query(ProjectMembership).filter(
+        ProjectMembership.project_id == project_id
+    ).all()
+
+    users = []
+    for m in memberships:
+        user = db.query(User).filter(User.id == m.user_id).first()
+        if user:
+            users.append({
+                "id": str(user.id),
+                "name": user.name,
+                "first_name": user.first_name,
+                "last_name": user.last_name,
+                "role": m.role
+            })
+
+    return {"project_id": project_id, "count": len(users), "users": users}
+
+
+def _tool_list_tasks(db, project_id: str, args: dict) -> dict:
+    """List tasks in project, optionally filtered by status."""
+    from sqlalchemy import desc, func
+
+    status_filter = args.get("status", "all")
+    assigned_to = args.get("assigned_to")
+    limit = args.get("limit", 20)
+
+    # Build base query - always filter by project_id
+    base_query = db.query(Task).filter(Task.project_id == project_id)
+
+    # Apply status filter
+    if status_filter and status_filter != "all":
+        try:
+            status_enum = TaskStatus(status_filter)
+            base_query = base_query.filter(Task.status == status_enum)
+        except ValueError:
+            return {"error": f"Invalid status: {status_filter}. Use: todo, in_progress, done, or all"}
+
+    # Apply assignee filter
+    if assigned_to:
+        base_query = base_query.filter(Task.assigned_to == assigned_to)
+
+    # Get TOTAL count before applying limit
+    total_count = base_query.count()
+
+    # Now apply ordering and limit for the actual results
+    tasks = base_query.order_by(desc(Task.created_at)).limit(limit).all()
+
+    # Get status counts for ALL tasks in project (not filtered)
+    all_tasks = db.query(Task).filter(Task.project_id == project_id).all()
+    status_counts = {"todo": 0, "in_progress": 0, "done": 0}
+    for task in all_tasks:
+        status_counts[task.status.value] += 1
+
+    return {
+        "project_id": project_id,
+        "filter": {
+            "status": status_filter,
+            "assigned_to": assigned_to
+        },
+        "total_count": total_count,  # Actual total matching the filter
+        "returned_count": len(tasks),  # How many in this response (may be limited)
+        "status_summary": status_counts,  # Counts for ALL tasks in project
+        "tasks": [
+            {
+                "id": str(task.id),
+                "title": task.title,
+                "description": task.description[:100] if task.description else None,
+                "status": task.status.value,
+                "assigned_to": task.assigned_to,
+                "created_at": task.created_at.isoformat() if task.created_at else None,
+                "completed_at": task.completed_at.isoformat() if task.completed_at else None
+            }
+            for task in tasks
+        ]
+    }
+
+
+def extract_sources(tool_results: list) -> list:
+    """Extract source citations from tool results."""
+    sources = []
+    seen_ids = set()
+
+    for tr in tool_results:
+        result = tr.get("result", {})
+
+        # From activity queries
+        if "activities" in result:
+            for a in result["activities"][:5]:
+                if a.get("id") and a["id"] not in seen_ids:
+                    sources.append({
+                        "id": a["id"],
+                        "type": "activity",
+                        "summary": a.get("what_was_done", "")[:100],
+                        "date": a.get("timestamp")
+                    })
+                    seen_ids.add(a["id"])
+
+        # From semantic search
+        if "results" in result:
+            for r in result["results"][:5]:
+                if r.get("id") and r["id"] not in seen_ids:
+                    sources.append({
+                        "id": r["id"],
+                        "type": "memory",
+                        "summary": r.get("what_was_done", "")[:100],
+                        "date": r.get("timestamp"),
+                        "relevance": r.get("relevance_score")
+                    })
+                    seen_ids.add(r["id"])
+
+        # From task queries (single task)
+        if "task" in result and result.get("found"):
+            task = result["task"]
+            sources.append({
+                "id": task["id"],
+                "type": "task",
+                "summary": task["title"],
+                "status": task["status"]
+            })
+
+        # From list_tasks queries (multiple tasks)
+        if "tasks" in result and isinstance(result["tasks"], list):
+            for task in result["tasks"][:5]:
+                if task.get("id") and task["id"] not in seen_ids:
+                    sources.append({
+                        "id": task["id"],
+                        "type": "task",
+                        "summary": task["title"],
+                        "status": task.get("status")
+                    })
+                    seen_ids.add(task["id"])
+
+    return sources

backend/app/tools/__init__.py

@@ -0,0 +1 @@
+# MCP Tools

backend/app/tools/memory.py

@@ -0,0 +1,242 @@
+"""
+Memory tools for Project Memory - complete_task and memory_search.
+
+Dependencies (from Dev A):
+- app.models: Task, LogEntry, TaskStatus, ActorType, ActionType
+- app.database: get_db
+
+These imports will work once Dev A completes models.py and database.py.
+"""
+
+from datetime import datetime
+from typing import Optional
+from sqlalchemy.orm import Session
+
+# Dev A's imports (will work when their files are ready)
+from app.models import Task, LogEntry, TaskStatus, ActorType, ActionType
+from app.database import get_db
+
+# Dev B's imports
+from app.llm import generate_documentation, synthesize_answer, get_embedding
+from app.vectorstore import add_embedding, search
+
+# Tool definitions for MCP server
+TOOLS = [
+    {
+        "name": "complete_task",
+        "description": "Mark a task as complete with AI-generated documentation",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "task_id": {"type": "string", "description": "ID of the task to complete"},
+                "project_id": {"type": "string", "description": "Project ID"},
+                "user_id": {"type": "string", "description": "User completing the task"},
+                "what_i_did": {"type": "string", "description": "Description of work done"},
+                "code_snippet": {"type": "string", "description": "Optional code snippet"}
+            },
+            "required": ["task_id", "project_id", "user_id", "what_i_did"]
+        }
+    },
+    {
+        "name": "memory_search",
+        "description": "Search project memory with natural language and get AI-synthesized answers",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "project_id": {"type": "string", "description": "Project to search in"},
+                "query": {"type": "string", "description": "Natural language search query"}
+            },
+            "required": ["project_id", "query"]
+        }
+    }
+]
+
+
+async def complete_task(
+    task_id: str,
+    project_id: str,
+    user_id: str,
+    what_i_did: str,
+    code_snippet: Optional[str] = None,
+    db: Optional[Session] = None
+) -> dict:
+    """
+    Complete a task and create searchable memory.
+
+    Pipeline:
+    1. Update task status to done
+    2. Generate documentation via LLM
+    3. Create LogEntry record
+    4. Create embedding and store in vector DB
+    """
+    if db is None:
+        db = next(get_db())
+
+    try:
+        # 1. Get and update task
+        task = db.query(Task).filter(Task.id == task_id).first()
+        if not task:
+            return {"success": False, "error": "Task not found"}
+
+        task.status = TaskStatus.done
+        task.completed_at = datetime.now()
+
+        # 2. Generate documentation via LLM
+        doc = await generate_documentation(
+            task_title=task.title,
+            what_i_did=what_i_did,
+            code_snippet=code_snippet
+        )
+
+        # 3. Create LogEntry
+        log_entry = LogEntry(
+            project_id=project_id,
+            task_id=task_id,
+            user_id=user_id,
+            actor_type=ActorType.human,
+            action_type=ActionType.task_completed,
+            raw_input=what_i_did,
+            code_snippet=code_snippet,
+            generated_doc=doc["details"],
+            tags=doc.get("tags", [])
+        )
+        db.add(log_entry)
+        db.commit()
+        db.refresh(log_entry)
+
+        # 4. Create embedding and store
+        text_to_embed = f"""
+        Task: {task.title}
+        Summary: {doc['summary']}
+        Details: {doc['details']}
+        Code: {code_snippet or ''}
+        """
+
+        embedding = await get_embedding(text_to_embed)
+
+        add_embedding(
+            log_entry_id=str(log_entry.id),
+            text=text_to_embed,
+            embedding=embedding,
+            metadata={
+                "project_id": project_id,
+                "user_id": user_id,
+                "task_id": task_id,
+                "created_at": log_entry.created_at.isoformat()
+            }
+        )
+
+        return {
+            "success": True,
+            "log_entry_id": str(log_entry.id),
+            "summary": doc["summary"],
+            "tags": doc.get("tags", [])
+        }
+
+    except Exception as e:
+        db.rollback()
+        return {"success": False, "error": str(e)}
+
+
+async def memory_search(
+    project_id: str,
+    query: str,
+    filters: Optional[dict] = None,
+    db: Optional[Session] = None
+) -> dict:
+    """
+    Search project memory and synthesize answer.
+
+    Pipeline:
+    1. Get query embedding
+    2. Vector similarity search (with optional filters)
+    3. Fetch full log entries
+    4. LLM synthesis of answer with citations
+
+    Args:
+        project_id: Project to search in
+        query: Natural language search query
+        filters: Optional filters dict with keys: userId, dateFrom, dateTo, tags
+        db: Database session (optional)
+    """
+    if db is None:
+        db = next(get_db())
+
+    try:
+        # 1. Get query embedding
+        query_embedding = await get_embedding(query)
+
+        # 2. Convert camelCase filter keys to snake_case for vectorstore
+        search_filters = None
+        if filters:
+            search_filters = {}
+            if filters.get("userId"):
+                search_filters["user_id"] = filters["userId"]
+            if filters.get("dateFrom"):
+                search_filters["date_from"] = filters["dateFrom"]
+            if filters.get("dateTo"):
+                search_filters["date_to"] = filters["dateTo"]
+            # Note: tags filtering not yet implemented in vectorstore
+
+        # 3. Vector search with filters
+        results = search(
+            query_embedding=query_embedding,
+            project_id=project_id,
+            n_results=10,
+            filters=search_filters
+        )
+
+        if not results:
+            return {
+                "answer": "No relevant information found in project memory.",
+                "sources": []
+            }
+
+        # 3. Get full log entries
+        log_entry_ids = [r["id"] for r in results]
+        log_entries = db.query(LogEntry).filter(LogEntry.id.in_(log_entry_ids)).all()
+
+        if not log_entries:
+            # Fallback to vector store text if log entries not found
+            context = "\n---\n".join([
+                f"Entry: {r['metadata'].get('text', '')}"
+                for r in results
+            ])
+        else:
+            # 4. Build context from log entries
+            context = "\n---\n".join([
+                f"Date: {e.created_at}\nTask: {e.raw_input}\nDoc: {e.generated_doc}"
+                for e in log_entries
+            ])
+
+        # 5. Synthesize answer
+        answer = await synthesize_answer(context, query)
+
+        return {
+            "answer": answer,
+            "sources": [
+                {
+                    "id": str(e.id),
+                    "summary": e.raw_input,
+                    "date": e.created_at.isoformat()
+                }
+                for e in log_entries
+            ] if log_entries else [
+                {
+                    "id": r["id"],
+                    "summary": r["metadata"].get("text", "")[:100],
+                    "date": r["metadata"].get("created_at", "")
+                }
+                for r in results
+            ]
+        }
+
+    except Exception as e:
+        return {"answer": f"Error searching memory: {str(e)}", "sources": []}
+
+
+# Handler map for MCP server
+HANDLERS = {
+    "complete_task": complete_task,
+    "memory_search": memory_search,
+}

backend/app/tools/projects.py

@@ -0,0 +1,176 @@
+"""Project-related MCP tools."""
+
+from sqlalchemy.orm import Session
+from app.database import SessionLocal
+from app.models import Project, ProjectMembership, User
+
+
+def check_project_id_available(project_id: str) -> dict:
+    """
+    Check if a project ID is available.
+    
+    Args:
+        project_id: The project ID to check
+    
+    Returns:
+        Dict with 'available' boolean
+    """
+    db: Session = SessionLocal()
+    try:
+        existing = db.query(Project).filter(Project.id == project_id).first()
+        return {"available": existing is None, "project_id": project_id}
+    finally:
+        db.close()
+
+
+def create_project(name: str, description: str, user_id: str) -> dict:
+    """
+    Create a new project and add the creator as owner.
+    The project ID will be the project name (used as-is).
+    
+    Args:
+        name: Project name (will also be used as project ID)
+        description: Project description
+        user_id: ID of the user creating the project
+    
+    Returns:
+        Created project data or error if project ID already exists
+    """
+    db: Session = SessionLocal()
+    try:
+        # Verify user exists
+        user = db.query(User).filter(User.id == user_id).first()
+        if not user:
+            return {"error": f"User {user_id} not found"}
+        
+        # Use name as project ID
+        project_id = name
+        
+        # Check if project ID already exists
+        existing = db.query(Project).filter(Project.id == project_id).first()
+        if existing:
+            return {"error": f"Project ID '{project_id}' already exists. Please choose a different name."}
+        
+        # Create project with name as ID
+        project = Project(
+            id=project_id,
+            name=name,
+            description=description,
+            created_by=user_id
+        )
+        db.add(project)
+        db.flush()
+        
+        # Add creator as owner
+        membership = ProjectMembership(
+            project_id=project.id,
+            user_id=user_id,
+            role="owner"
+        )
+        db.add(membership)
+        db.commit()
+        
+        return {
+            "id": project.id,
+            "name": project.name,
+            "description": project.description,
+            "created_at": project.created_at.isoformat(),
+            "created_by": project.created_by
+        }
+    finally:
+        db.close()
+
+
+def list_projects(user_id: str) -> dict:
+    """
+    List all projects for a user.
+    
+    Args:
+        user_id: ID of the user
+    
+    Returns:
+        List of projects the user is a member of
+    """
+    db: Session = SessionLocal()
+    try:
+        # Get all project memberships for user
+        memberships = (
+            db.query(ProjectMembership)
+            .filter(ProjectMembership.user_id == user_id)
+            .all()
+        )
+        
+        projects = []
+        for membership in memberships:
+            project = membership.project
+            projects.append({
+                "id": project.id,
+                "name": project.name,
+                "description": project.description,
+                "created_at": project.created_at.isoformat(),
+                "role": membership.role
+            })
+        
+        return {"projects": projects}
+    finally:
+        db.close()
+
+
+def join_project(project_id: str, user_id: str) -> dict:
+    """
+    Add a user to an existing project.
+    
+    Args:
+        project_id: ID of the project to join
+        user_id: ID of the user joining
+    
+    Returns:
+        Membership confirmation
+    """
+    db: Session = SessionLocal()
+    try:
+        # Verify project exists
+        project = db.query(Project).filter(Project.id == project_id).first()
+        if not project:
+            return {"error": f"Project {project_id} not found"}
+        
+        # Verify user exists
+        user = db.query(User).filter(User.id == user_id).first()
+        if not user:
+            return {"error": f"User {user_id} not found"}
+        
+        # Check if already a member
+        existing = (
+            db.query(ProjectMembership)
+            .filter(
+                ProjectMembership.project_id == project_id,
+                ProjectMembership.user_id == user_id
+            )
+            .first()
+        )
+        if existing:
+            return {
+                "message": "Already a member",
+                "project_id": project_id,
+                "user_id": user_id,
+                "role": existing.role
+            }
+        
+        # Create membership
+        membership = ProjectMembership(
+            project_id=project_id,
+            user_id=user_id,
+            role="member"
+        )
+        db.add(membership)
+        db.commit()
+        
+        return {
+            "message": "Joined project successfully",
+            "project_id": project_id,
+            "project_name": project.name,
+            "user_id": user_id,
+            "role": "member"
+        }
+    finally:
+        db.close()

backend/app/tools/tasks.py

@@ -0,0 +1,139 @@
+"""Task-related MCP tools."""
+
+from sqlalchemy.orm import Session
+from sqlalchemy import desc
+from app.database import SessionLocal
+from app.models import Task, TaskStatus, Project, LogEntry
+
+
+def create_task(project_id: str, title: str, description: str = None, assigned_to: str = None) -> dict:
+    """
+    Create a new task in a project.
+    
+    Args:
+        project_id: ID of the project
+        title: Task title
+        description: Optional task description
+        assigned_to: Optional user ID to assign the task to
+    
+    Returns:
+        Created task data
+    """
+    db: Session = SessionLocal()
+    try:
+        # Verify project exists
+        project = db.query(Project).filter(Project.id == project_id).first()
+        if not project:
+            return {"error": f"Project {project_id} not found"}
+        
+        # Create task
+        task = Task(
+            project_id=project_id,
+            title=title,
+            description=description,
+            assigned_to=assigned_to,
+            status=TaskStatus.todo
+        )
+        db.add(task)
+        db.commit()
+        
+        return {
+            "id": task.id,
+            "project_id": task.project_id,
+            "title": task.title,
+            "description": task.description,
+            "status": task.status.value,
+            "assigned_to": task.assigned_to,
+            "created_at": task.created_at.isoformat()
+        }
+    finally:
+        db.close()
+
+
+def list_tasks(project_id: str, status: str = None) -> dict:
+    """
+    List all tasks for a project, optionally filtered by status.
+    
+    Args:
+        project_id: ID of the project
+        status: Optional status filter ("todo", "in_progress", "done")
+    
+    Returns:
+        List of tasks
+    """
+    db: Session = SessionLocal()
+    try:
+        # Build query
+        query = db.query(Task).filter(Task.project_id == project_id)
+        
+        # Apply status filter if provided
+        if status:
+            try:
+                status_enum = TaskStatus(status)
+                query = query.filter(Task.status == status_enum)
+            except ValueError:
+                return {"error": f"Invalid status: {status}. Must be one of: todo, in_progress, done"}
+        
+        # Order by created_at descending
+        tasks = query.order_by(desc(Task.created_at)).all()
+        
+        return {
+            "tasks": [
+                {
+                    "id": task.id,
+                    "project_id": task.project_id,
+                    "title": task.title,
+                    "description": task.description,
+                    "status": task.status.value,
+                    "assigned_to": task.assigned_to,
+                    "created_at": task.created_at.isoformat(),
+                    "completed_at": task.completed_at.isoformat() if task.completed_at else None
+                }
+                for task in tasks
+            ]
+        }
+    finally:
+        db.close()
+
+
+def list_activity(project_id: str, limit: int = 20) -> dict:
+    """
+    Get recent activity (log entries) for a project.
+    
+    Args:
+        project_id: ID of the project
+        limit: Maximum number of entries to return (default 20)
+    
+    Returns:
+        List of recent log entries
+    """
+    db: Session = SessionLocal()
+    try:
+        # Query log entries ordered by most recent
+        entries = (
+            db.query(LogEntry)
+            .filter(LogEntry.project_id == project_id)
+            .order_by(desc(LogEntry.created_at))
+            .limit(limit)
+            .all()
+        )
+        
+        return {
+            "activity": [
+                {
+                    "id": entry.id,
+                    "project_id": entry.project_id,
+                    "task_id": entry.task_id,
+                    "user_id": entry.user_id,
+                    "actor_type": entry.actor_type.value,
+                    "action_type": entry.action_type.value,
+                    "raw_input": entry.raw_input,
+                    "generated_doc": entry.generated_doc,
+                    "tags": entry.tags,
+                    "created_at": entry.created_at.isoformat()
+                }
+                for entry in entries
+            ]
+        }
+    finally:
+        db.close()

backend/app/vectorstore.py

@@ -0,0 +1,192 @@
+import sqlite3
+import sqlite_vec
+import struct
+from typing import Optional
+import os
+
+# Database path - same as main SQLite database
+DB_PATH = os.path.join(os.path.dirname(__file__), "..", "project_memory.db")
+
+
+def _serialize_vector(vec: list[float]) -> bytes:
+    """Convert list of floats to bytes for sqlite-vec."""
+    return struct.pack(f'{len(vec)}f', *vec)
+
+
+def _get_connection():
+    """Get SQLite connection with sqlite-vec loaded."""
+    conn = sqlite3.connect(DB_PATH)
+    conn.enable_load_extension(True)
+    sqlite_vec.load(conn)
+    conn.enable_load_extension(False)
+    return conn
+
+
+def init_vectorstore():
+    """Initialize the vector table. Call once at startup."""
+    conn = _get_connection()
+
+    # Metadata table for embeddings
+    conn.execute("""
+        CREATE TABLE IF NOT EXISTS embeddings (
+            id TEXT PRIMARY KEY,
+            project_id TEXT NOT NULL,
+            user_id TEXT,
+            task_id TEXT,
+            text TEXT,
+            created_at TEXT
+        )
+    """)
+
+    # Create index for faster project filtering
+    conn.execute("""
+        CREATE INDEX IF NOT EXISTS idx_embeddings_project
+        ON embeddings(project_id)
+    """)
+
+    # Create virtual table for vector search (768 dims for Gemini)
+    conn.execute("""
+        CREATE VIRTUAL TABLE IF NOT EXISTS vec_embeddings USING vec0(
+            id TEXT PRIMARY KEY,
+            embedding FLOAT[768]
+        )
+    """)
+
+    conn.commit()
+    conn.close()
+
+
+def add_embedding(
+    log_entry_id: str,
+    text: str,
+    embedding: list[float],
+    metadata: dict
+) -> None:
+    """Store embedding with metadata."""
+    conn = _get_connection()
+
+    # Store metadata
+    conn.execute("""
+        INSERT OR REPLACE INTO embeddings (id, project_id, user_id, task_id, text, created_at)
+        VALUES (?, ?, ?, ?, ?, ?)
+    """, (
+        log_entry_id,
+        metadata.get("project_id"),
+        metadata.get("user_id"),
+        metadata.get("task_id"),
+        text[:2000],  # Truncate long text
+        metadata.get("created_at")
+    ))
+
+    # Store vector
+    conn.execute("""
+        INSERT OR REPLACE INTO vec_embeddings (id, embedding)
+        VALUES (?, ?)
+    """, (log_entry_id, _serialize_vector(embedding)))
+
+    conn.commit()
+    conn.close()
+
+
+def search(
+    query_embedding: list[float],
+    project_id: str,
+    n_results: int = 10,
+    filters: Optional[dict] = None
+) -> list[dict]:
+    """Search for similar documents within a project."""
+    conn = _get_connection()
+
+    # Vector similarity search with metadata filter
+    # sqlite-vec uses k parameter in the MATCH clause
+    query = """
+        SELECT
+            e.id,
+            e.project_id,
+            e.user_id,
+            e.task_id,
+            e.text,
+            e.created_at,
+            v.distance
+        FROM vec_embeddings v
+        JOIN embeddings e ON v.id = e.id
+        WHERE v.embedding MATCH ?
+            AND k = ?
+            AND e.project_id = ?
+    """
+    params = [_serialize_vector(query_embedding), n_results * 2, project_id]
+
+    if filters:
+        if filters.get("user_id"):
+            query += " AND e.user_id = ?"
+            params.append(filters["user_id"])
+
+        # Date filters for time-based queries
+        if filters.get("date_from"):
+            date_from = filters["date_from"]
+            if hasattr(date_from, 'isoformat'):
+                date_from = date_from.isoformat()
+            query += " AND e.created_at >= ?"
+            params.append(date_from)
+
+        if filters.get("date_to"):
+            date_to = filters["date_to"]
+            if hasattr(date_to, 'isoformat'):
+                date_to = date_to.isoformat()
+            query += " AND e.created_at < ?"
+            params.append(date_to)
+
+    query += " ORDER BY v.distance LIMIT ?"
+    params.append(n_results)
+
+    results = conn.execute(query, params).fetchall()
+    conn.close()
+
+    return [
+        {
+            "id": row[0],
+            "metadata": {
+                "project_id": row[1],
+                "user_id": row[2],
+                "task_id": row[3],
+                "text": row[4],
+                "created_at": row[5]
+            },
+            "distance": row[6]
+        }
+        for row in results
+    ]
+
+
+def delete_by_project(project_id: str) -> None:
+    """Delete all vectors for a project."""
+    conn = _get_connection()
+
+    # Get IDs to delete
+    ids = conn.execute(
+        "SELECT id FROM embeddings WHERE project_id = ?",
+        (project_id,)
+    ).fetchall()
+
+    for (id_,) in ids:
+        conn.execute("DELETE FROM vec_embeddings WHERE id = ?", (id_,))
+
+    conn.execute("DELETE FROM embeddings WHERE project_id = ?", (project_id,))
+    conn.commit()
+    conn.close()
+
+
+def count_embeddings(project_id: Optional[str] = None) -> int:
+    """Count embeddings, optionally filtered by project."""
+    conn = _get_connection()
+
+    if project_id:
+        result = conn.execute(
+            "SELECT COUNT(*) FROM embeddings WHERE project_id = ?",
+            (project_id,)
+        ).fetchone()
+    else:
+        result = conn.execute("SELECT COUNT(*) FROM embeddings").fetchone()
+
+    conn.close()
+    return result[0]

backend/pytest.ini

@@ -0,0 +1,9 @@
+[pytest]
+pythonpath = .
+testpaths = tests
+python_files = test_*.py
+asyncio_mode = auto
+asyncio_default_fixture_loop_scope = function
+markers =
+    timeout: mark test to timeout after X seconds
+    asyncio: mark test as async

backend/requirements.txt

@@ -0,0 +1,13 @@
+fastapi==0.115.0
+uvicorn[standard]==0.32.0
+sqlalchemy==2.0.36
+python-dotenv==1.0.1
+google-generativeai
+sqlite-vec
+mcp
+numpy
+pydantic==2.9.2
+httpx==0.27.2
+python-multipart==0.0.12
+pytest==8.3.3
+pytest-asyncio==0.24.0

backend/tests/conftest.py

@@ -0,0 +1,58 @@
+import os
+import asyncio
+import pytest
+
+from app.database import init_db, SessionLocal
+from app.models import LogEntry, Task, ProjectMembership, Project, User, generate_user_id
+
+@pytest.fixture(autouse=True)
+def _ensure_gemini_env(monkeypatch):
+    # Prevent import-time failure in app.llm when GEMINI_API_KEY is missing
+    monkeypatch.setenv("GEMINI_API_KEY", os.getenv("GEMINI_API_KEY", "test-key"))
+
+@pytest.fixture(autouse=True, scope="session")
+def setup_db():
+    """Drop and recreate all tables once per test session."""
+    from app.database import Base, engine
+    # Drop all tables to ensure clean schema
+    Base.metadata.drop_all(bind=engine)
+    # Recreate with new schema
+    init_db()
+    yield
+
+
+@pytest.fixture(autouse=True)
+def reset_db(setup_db):
+    """Clean all rows before each test."""
+    db = SessionLocal()
+    try:
+        # Delete in dependency order to satisfy FKs
+        db.query(LogEntry).delete()
+        db.query(Task).delete()
+        db.query(ProjectMembership).delete()
+        db.query(Project).delete()
+        db.query(User).delete()
+        db.commit()
+        yield
+    finally:
+        db.close()
+
+@pytest.fixture()
+def db_session():
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()
+
+@pytest.fixture()
+def create_user(db_session):
+    def _create(first_name: str, last_name: str):
+        user_id = generate_user_id(first_name)
+        u = User(id=user_id, first_name=first_name, last_name=last_name)
+        db_session.add(u)
+        db_session.commit()
+        db_session.refresh(u)
+        return u
+    return _create
+

backend/tests/test_complete_api.py

@@ -0,0 +1,219 @@
+"""Complete API test with user creation flow."""
+
+import requests
+import json
+import sys
+
+BASE_URL = "http://localhost:8000"
+
+print("="*60)
+print("PROJECT MEMORY - COMPLETE API TEST")
+print("="*60)
+
+def test_api():
+    # Check if server is running
+    try:
+        response = requests.get(f"{BASE_URL}/")
+        print(f"✓ Server is running: {response.json()['message']}")
+    except:
+        print("❌ Server is not running!")
+        print("Start it with: uvicorn app.main:app --reload")
+        return
+    
+    print("\n" + "="*60)
+    print("1. CREATE USER")
+    print("="*60)
+    
+    # Create a new user
+    user_data = {
+        "firstName": "John",
+        "lastName": "Doe",
+        "avatar_url": "https://example.com/avatar.jpg"
+    }
+    
+    print(f"POST /api/users")
+    print(f"Body: {json.dumps(user_data, indent=2)}")
+    
+    response = requests.post(f"{BASE_URL}/api/users", json=user_data)
+    print(f"Status: {response.status_code}")
+    
+    if response.status_code != 200:
+        print(f"Error: {response.text}")
+        return
+    
+    user = response.json()
+    user_id = user["id"]
+    print(f"✓ Created user: {user_id}")
+    print(f"Response: {json.dumps(user, indent=2)}")
+    
+    print("\n" + "="*60)
+    print("2. GET USER")
+    print("="*60)
+    
+    print(f"GET /api/users/{user_id}")
+    response = requests.get(f"{BASE_URL}/api/users/{user_id}")
+    print(f"Status: {response.status_code}")
+    print(f"Response: {json.dumps(response.json(), indent=2)}")
+    
+    print("\n" + "="*60)
+    print("3. LIST ALL USERS")
+    print("="*60)
+    
+    print(f"GET /api/users")
+    response = requests.get(f"{BASE_URL}/api/users")
+    print(f"Status: {response.status_code}")
+    users = response.json()
+    print(f"Total users: {len(users)}")
+    for u in users[:3]:  # Show first 3 users
+        print(f"  - {u['firstName']} {u['lastName']} ({u['id']})")
+    
+    print("\n" + "="*60)
+    print("4. CREATE PROJECT")
+    print("="*60)
+    
+    project_data = {
+        "name": "Test Project",
+        "description": "API Testing Project",
+        "userId": user_id
+    }
+    
+    print(f"POST /api/projects")
+    print(f"Body: {json.dumps(project_data, indent=2)}")
+    
+    response = requests.post(f"{BASE_URL}/api/projects", json=project_data)
+    print(f"Status: {response.status_code}")
+    
+    if response.status_code != 200:
+        print(f"Error: {response.text}")
+        return
+    
+    project = response.json()
+    project_id = project["id"]
+    print(f"✓ Created project: {project_id}")
+    
+    print("\n" + "="*60)
+    print("5. LIST USER'S PROJECTS")
+    print("="*60)
+    
+    print(f"GET /api/projects?userId={user_id}")
+    response = requests.get(f"{BASE_URL}/api/projects?userId={user_id}")
+    print(f"Status: {response.status_code}")
+    projects = response.json()
+    print(f"User has {len(projects)} project(s)")
+    
+    print("\n" + "="*60)
+    print("6. CREATE TASK")
+    print("="*60)
+    
+    task_data = {
+        "title": "Implement user authentication",
+        "description": "Add login and registration features",
+        "assignedTo": user_id
+    }
+    
+    print(f"POST /api/projects/{project_id}/tasks")
+    print(f"Body: {json.dumps(task_data, indent=2)}")
+    
+    response = requests.post(f"{BASE_URL}/api/projects/{project_id}/tasks", json=task_data)
+    print(f"Status: {response.status_code}")
+    
+    if response.status_code != 200:
+        print(f"Error: {response.text}")
+        return
+        
+    task = response.json()
+    task_id = task["id"]
+    print(f"✓ Created task: {task_id}")
+    
+    print("\n" + "="*60)
+    print("7. LIST TASKS")
+    print("="*60)
+    
+    print(f"GET /api/projects/{project_id}/tasks")
+    response = requests.get(f"{BASE_URL}/api/projects/{project_id}/tasks")
+    print(f"Status: {response.status_code}")
+    tasks = response.json()
+    print(f"Project has {len(tasks)} task(s)")
+    
+    print("\n" + "="*60)
+    print("8. COMPLETE TASK (with AI documentation)")
+    print("="*60)
+    
+    complete_data = {
+        "userId": user_id,
+        "whatIDid": "Implemented OAuth2 authentication with JWT tokens",
+        "codeSnippet": "def authenticate(token): return jwt.decode(token, SECRET_KEY)"
+    }
+    
+    print(f"POST /api/tasks/{task_id}/complete")
+    print(f"Body: {json.dumps(complete_data, indent=2)}")
+    print("⏳ This will call Gemini AI to generate documentation...")
+    
+    response = requests.post(f"{BASE_URL}/api/tasks/{task_id}/complete", json=complete_data)
+    print(f"Status: {response.status_code}")
+    
+    if response.status_code == 200:
+        print(f"✓ Task completed with AI documentation")
+        print(f"Response: {json.dumps(response.json(), indent=2)}")
+    else:
+        print(f"Note: Task completion requires GEMINI_API_KEY in .env")
+        print(f"Response: {response.text}")
+    
+    print("\n" + "="*60)
+    print("9. GET ACTIVITY FEED")
+    print("="*60)
+    
+    print(f"GET /api/projects/{project_id}/activity")
+    response = requests.get(f"{BASE_URL}/api/projects/{project_id}/activity")
+    print(f"Status: {response.status_code}")
+    if response.status_code == 200:
+        activity = response.json()
+        print(f"Activity entries: {len(activity)}")
+    
+    print("\n" + "="*60)
+    print("TEST COMPLETE - ALL ENDPOINTS WORKING!")
+    print("="*60)
+    
+    print(f"""
+SUMMARY OF CREATED DATA:
+- User ID: {user_id}
+- Project ID: {project_id}
+- Task ID: {task_id}
+
+You can now use these IDs to test other endpoints!
+""")
+    
+    print("="*60)
+    print("CURL EXAMPLES WITH YOUR DATA")
+    print("="*60)
+    
+    print(f"""
+# Create another user
+curl -X POST {BASE_URL}/api/users \\
+  -H "Content-Type: application/json" \\
+  -d '{{"firstName": "Jane", "lastName": "Smith"}}'
+
+# Get your user
+curl {BASE_URL}/api/users/{user_id}
+
+# List all users
+curl {BASE_URL}/api/users
+
+# Create another project
+curl -X POST {BASE_URL}/api/projects \\
+  -H "Content-Type: application/json" \\
+  -d '{{"name": "Another Project", "description": "Description", "userId": "{user_id}"}}'
+
+# Join a project (create a second user first)
+curl -X POST {BASE_URL}/api/projects/{project_id}/join \\
+  -H "Content-Type: application/json" \\
+  -d '{{"userId": "ANOTHER_USER_ID"}}'
+
+# Search project memory (after completing tasks)
+curl -X POST {BASE_URL}/api/projects/{project_id}/search \\
+  -H "Content-Type: application/json" \\
+  -d '{{"query": "authentication"}}'
+""")
+
+if __name__ == "__main__":
+    test_api()

backend/tests/test_database.py

@@ -0,0 +1,69 @@
+"""Unit tests for database module."""
+
+import pytest
+from sqlalchemy.orm import Session
+
+from app.database import get_db, init_db, SessionLocal, Base, engine
+
+
+class TestDatabase:
+    """Test database initialization and session management."""
+
+    def test_init_db_creates_tables(self):
+        """Test that init_db creates all model tables."""
+        init_db()
+        
+        # Check that tables exist
+        from app.models import User, Project, Task, LogEntry, ProjectMembership
+        
+        # Verify table names are in metadata
+        assert "users" in Base.metadata.tables
+        assert "projects" in Base.metadata.tables
+        assert "tasks" in Base.metadata.tables
+        assert "log_entries" in Base.metadata.tables
+        assert "project_memberships" in Base.metadata.tables
+
+    def test_session_local_returns_session(self):
+        """Test SessionLocal creates a valid session."""
+        session = SessionLocal()
+        assert isinstance(session, Session)
+        session.close()
+
+    def test_get_db_yields_session(self):
+        """Test get_db generator yields a session and closes it."""
+        gen = get_db()
+        db = next(gen)
+        
+        assert isinstance(db, Session)
+        
+        # Exhaust generator to trigger cleanup
+        try:
+            next(gen)
+        except StopIteration:
+            pass
+
+    def test_get_db_closes_on_exception(self):
+        """Test get_db closes session even on exception."""
+        gen = get_db()
+        db = next(gen)
+        
+        # Simulate exception by closing manually
+        try:
+            gen.throw(Exception("test error"))
+        except Exception:
+            pass
+        
+        # Session should be closed (no error means cleanup happened)
+
+
+class TestDatabaseEngine:
+    """Test database engine configuration."""
+
+    def test_engine_is_sqlite(self):
+        """Test engine is configured for SQLite."""
+        assert "sqlite" in str(engine.url)
+
+    def test_engine_allows_multithread(self):
+        """Test SQLite is configured for multi-threaded access."""
+        # check_same_thread=False is set in database.py
+        assert engine.pool is not None

backend/tests/test_devb.py

@@ -0,0 +1,234 @@
+"""
+Dev B Test Suite - Run with: .venv/Scripts/python test_devb.py
+"""
+
+import asyncio
+import sys
+sys.path.insert(0, '.')
+
+from app.llm import generate_documentation, synthesize_answer, get_embedding
+from app.vectorstore import init_vectorstore, add_embedding, search, count_embeddings, delete_by_project
+
+# Test counters
+passed = 0
+failed = 0
+
+
+def test(name, condition, details=""):
+    global passed, failed
+    if condition:
+        print(f"  [PASS] {name}")
+        passed += 1
+    else:
+        print(f"  [FAIL] {name} - {details}")
+        failed += 1
+
+
+async def test_llm():
+    print("\n[1/4] Testing LLM Client (llm.py)")
+    print("-" * 40)
+
+    # Test 1: get_embedding
+    try:
+        emb = await get_embedding("test embedding")
+        test("get_embedding returns list", isinstance(emb, list))
+        test("get_embedding returns 768 dims", len(emb) == 768, f"got {len(emb)}")
+        test("get_embedding returns floats", isinstance(emb[0], float))
+    except Exception as e:
+        test("get_embedding", False, str(e))
+
+    # Test 2: generate_documentation
+    try:
+        doc = await generate_documentation(
+            task_title="Setup API",
+            what_i_did="Created REST endpoints",
+            code_snippet="@app.get('/api')"
+        )
+        test("generate_documentation returns dict", isinstance(doc, dict))
+        test("generate_documentation has summary", "summary" in doc)
+        test("generate_documentation has details", "details" in doc)
+        test("generate_documentation has tags", "tags" in doc and isinstance(doc["tags"], list))
+    except Exception as e:
+        test("generate_documentation", False, str(e))
+
+    # Test 3: synthesize_answer
+    try:
+        answer = await synthesize_answer(
+            context="Task completed: Built login system with JWT authentication",
+            query="What authentication was implemented?"
+        )
+        test("synthesize_answer returns string", isinstance(answer, str))
+        test("synthesize_answer not empty", len(answer) > 0)
+    except Exception as e:
+        test("synthesize_answer", False, str(e))
+
+
+async def test_vectorstore():
+    print("\n[2/4] Testing Vector Store (vectorstore.py)")
+    print("-" * 40)
+
+    # Test 1: init_vectorstore
+    try:
+        init_vectorstore()
+        test("init_vectorstore succeeds", True)
+    except Exception as e:
+        test("init_vectorstore", False, str(e))
+        return  # Can't continue without init
+
+    # Clean up test data first
+    try:
+        delete_by_project("test-project-xyz")
+    except:
+        pass
+
+    # Test 2: add_embedding
+    try:
+        emb = await get_embedding("Test document about Python programming")
+        add_embedding(
+            log_entry_id="test-entry-1",
+            text="Test document about Python programming",
+            embedding=emb,
+            metadata={
+                "project_id": "test-project-xyz",
+                "user_id": "test-user",
+                "task_id": "test-task",
+                "created_at": "2024-01-01T00:00:00"
+            }
+        )
+        test("add_embedding succeeds", True)
+    except Exception as e:
+        test("add_embedding", False, str(e))
+
+    # Test 3: count_embeddings
+    try:
+        count = count_embeddings("test-project-xyz")
+        test("count_embeddings returns int", isinstance(count, int))
+        test("count_embeddings >= 1", count >= 1, f"got {count}")
+    except Exception as e:
+        test("count_embeddings", False, str(e))
+
+    # Test 4: search
+    try:
+        query_emb = await get_embedding("Python")
+        results = search(query_emb, "test-project-xyz", n_results=5)
+        test("search returns list", isinstance(results, list))
+        test("search finds results", len(results) > 0, "no results found")
+        if results:
+            test("search result has id", "id" in results[0])
+            test("search result has metadata", "metadata" in results[0])
+            test("search result has distance", "distance" in results[0])
+    except Exception as e:
+        test("search", False, str(e))
+
+    # Test 5: delete_by_project
+    try:
+        delete_by_project("test-project-xyz")
+        count_after = count_embeddings("test-project-xyz")
+        test("delete_by_project removes data", count_after == 0, f"still has {count_after}")
+    except Exception as e:
+        test("delete_by_project", False, str(e))
+
+
+async def test_full_pipeline():
+    print("\n[3/4] Testing Full Pipeline")
+    print("-" * 40)
+
+    project_id = "pipeline-test-proj"
+
+    # Clean up first
+    try:
+        delete_by_project(project_id)
+    except:
+        pass
+
+    try:
+        # Step 1: Generate documentation
+        doc = await generate_documentation(
+            task_title="Implement user registration",
+            what_i_did="Added signup endpoint with email validation and password hashing",
+            code_snippet="def register(email, password): ..."
+        )
+        test("Pipeline: doc generation", "summary" in doc and "details" in doc)
+
+        # Step 2: Create embedding from doc
+        text_to_embed = f"{doc['summary']} {doc['details']}"
+        embedding = await get_embedding(text_to_embed)
+        test("Pipeline: embedding created", len(embedding) == 768)
+
+        # Step 3: Store in vectorstore
+        add_embedding(
+            log_entry_id="pipeline-log-1",
+            text=text_to_embed,
+            embedding=embedding,
+            metadata={"project_id": project_id, "user_id": "dev1"}
+        )
+        test("Pipeline: stored in vectorstore", count_embeddings(project_id) == 1)
+
+        # Step 4: Search for it
+        query_emb = await get_embedding("user registration signup")
+        results = search(query_emb, project_id)
+        test("Pipeline: search finds it", len(results) > 0)
+
+        # Step 5: Synthesize answer
+        if results:
+            context = results[0]["metadata"]["text"]
+            answer = await synthesize_answer(context, "What was done for user registration?")
+            test("Pipeline: answer synthesized", len(answer) > 20)
+
+        # Cleanup
+        delete_by_project(project_id)
+
+    except Exception as e:
+        test("Pipeline", False, str(e))
+
+
+async def test_edge_cases():
+    print("\n[4/4] Testing Edge Cases")
+    print("-" * 40)
+
+    # Test empty search
+    try:
+        init_vectorstore()
+        emb = await get_embedding("random query")
+        results = search(emb, "nonexistent-project-12345")
+        test("Empty search returns empty list", results == [])
+    except Exception as e:
+        test("Empty search", False, str(e))
+
+    # Test long text embedding
+    try:
+        long_text = "word " * 1000  # ~5000 chars
+        emb = await get_embedding(long_text)
+        test("Long text embedding works", len(emb) == 768)
+    except Exception as e:
+        test("Long text embedding", False, str(e))
+
+    # Test special characters
+    try:
+        special_text = "Code: `const x = 'hello';` // comment <script>alert('xss')</script>"
+        emb = await get_embedding(special_text)
+        test("Special chars embedding works", len(emb) == 768)
+    except Exception as e:
+        test("Special chars embedding", False, str(e))
+
+
+async def main():
+    print("=" * 50)
+    print("  DEV B TEST SUITE - Intelligence Layer")
+    print("=" * 50)
+
+    await test_llm()
+    await test_vectorstore()
+    await test_full_pipeline()
+    await test_edge_cases()
+
+    print("\n" + "=" * 50)
+    print(f"  RESULTS: {passed} passed, {failed} failed")
+    print("=" * 50)
+
+    if failed > 0:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

backend/tests/test_model_router.py

@@ -0,0 +1,408 @@
+"""Test cases for Model Router - multi-model rotation with rate limiting and caching."""
+
+import asyncio
+import time
+from unittest.mock import patch, MagicMock, AsyncMock
+from datetime import datetime, timedelta
+import sys
+import os
+
+# Add parent to path for imports
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from dotenv import load_dotenv
+load_dotenv()
+
+# Test configuration
+TESTS_PASSED = 0
+TESTS_FAILED = 0
+
+
+def test(name):
+    """Decorator for test functions."""
+    def decorator(func):
+        async def wrapper():
+            global TESTS_PASSED, TESTS_FAILED
+            try:
+                if asyncio.iscoroutinefunction(func):
+                    await func()
+                else:
+                    func()
+                print(f"[PASS] {name}")
+                TESTS_PASSED += 1
+            except AssertionError as e:
+                print(f"[FAIL] {name}: {e}")
+                TESTS_FAILED += 1
+            except Exception as e:
+                print(f"[ERROR] {name}: {e}")
+                TESTS_FAILED += 1
+        return wrapper
+    return decorator
+
+
+# ========== Model Selection Tests ==========
+
+@test("Model selection returns best model for chat task")
+def test_model_selection_chat():
+    from app.model_router import ModelRouter, TASK_PRIORITIES
+    router = ModelRouter()
+    model = router.get_model_for_task("chat")
+    assert model == "gemini-2.0-flash", f"Expected gemini-2.0-flash, got {model}"
+
+
+@test("Model selection returns best model for documentation task")
+def test_model_selection_documentation():
+    from app.model_router import ModelRouter, TASK_PRIORITIES
+    router = ModelRouter()
+    model = router.get_model_for_task("documentation")
+    assert model == "gemini-2.0-flash-lite", f"Expected gemini-2.0-flash-lite, got {model}"
+
+
+@test("Model selection returns best model for synthesis task")
+def test_model_selection_synthesis():
+    from app.model_router import ModelRouter, TASK_PRIORITIES
+    router = ModelRouter()
+    model = router.get_model_for_task("synthesis")
+    assert model == "gemma-3-27b-it", f"Expected gemma-3-27b-it, got {model}"
+
+
+@test("Model selection falls back to default for unknown task")
+def test_model_selection_unknown():
+    from app.model_router import ModelRouter
+    router = ModelRouter()
+    model = router.get_model_for_task("unknown_task_type")
+    assert model == "gemini-2.0-flash", f"Expected gemini-2.0-flash (default), got {model}"
+
+
+# ========== Rate Limiting Tests ==========
+
+@test("Rate limit tracking works correctly")
+def test_rate_limit_tracking():
+    from app.model_router import ModelRouter, MODEL_CONFIGS
+    router = ModelRouter()
+
+    # Initially all models should be available (key 0)
+    assert router._check_rate_limit("gemini-2.0-flash", 0) == True
+
+    # Record usage up to limit
+    rpm_limit = MODEL_CONFIGS["gemini-2.0-flash"]["rpm"]
+    for _ in range(rpm_limit):
+        router._record_usage("gemini-2.0-flash", 0)
+
+    # Should now be rate limited for key 0
+    assert router._check_rate_limit("gemini-2.0-flash", 0) == False
+
+
+@test("Model falls back when primary is rate limited")
+def test_model_fallback():
+    from app.model_router import ModelRouter, MODEL_CONFIGS
+    router = ModelRouter()
+
+    # Exhaust gemini-2.0-flash rate limit on all keys
+    rpm_limit = MODEL_CONFIGS["gemini-2.0-flash"]["rpm"]
+    for key_idx in range(len(router.api_keys)):
+        for _ in range(rpm_limit):
+            router._record_usage("gemini-2.0-flash", key_idx)
+
+    # Should fall back to next model in chat priority
+    model = router.get_model_for_task("chat")
+    assert model == "gemini-2.0-flash-lite", f"Expected fallback to gemini-2.0-flash-lite, got {model}"
+
+
+@test("Returns None when all models exhausted on all keys")
+def test_all_models_exhausted():
+    from app.model_router import ModelRouter, MODEL_CONFIGS
+    router = ModelRouter()
+
+    # Exhaust all models on all keys
+    for key_idx in range(len(router.api_keys)):
+        for model_name, config in MODEL_CONFIGS.items():
+            for _ in range(config["rpm"]):
+                router._record_usage(model_name, key_idx)
+
+    # Should return None
+    model = router.get_model_for_task("chat")
+    assert model is None, f"Expected None when all exhausted, got {model}"
+
+
+# ========== Cache Tests ==========
+
+@test("Cache stores and retrieves responses")
+def test_cache_store_retrieve():
+    from app.model_router import ModelRouter
+    router = ModelRouter()
+
+    cache_key = router._get_cache_key("chat", "user1", "test prompt")
+
+    # Initially empty
+    assert router._check_cache(cache_key) is None
+
+    # Store response
+    router._store_cache(cache_key, "cached response", "gemini-2.0-flash")
+
+    # Should retrieve
+    cached = router._check_cache(cache_key)
+    assert cached == "cached response", f"Expected 'cached response', got {cached}"
+
+
+@test("Cache key includes user_id")
+def test_cache_key_user_differentiation():
+    from app.model_router import ModelRouter
+    router = ModelRouter()
+
+    key1 = router._get_cache_key("chat", "user1", "same prompt")
+    key2 = router._get_cache_key("chat", "user2", "same prompt")
+
+    assert key1 != key2, "Cache keys should differ for different users"
+
+
+@test("Cache key includes task_type")
+def test_cache_key_task_differentiation():
+    from app.model_router import ModelRouter
+    router = ModelRouter()
+
+    key1 = router._get_cache_key("chat", "user1", "same prompt")
+    key2 = router._get_cache_key("documentation", "user1", "same prompt")
+
+    assert key1 != key2, "Cache keys should differ for different task types"
+
+
+@test("Cache expires after TTL")
+def test_cache_expiry():
+    from app.model_router import ModelRouter, CACHE_TTL
+    router = ModelRouter()
+
+    cache_key = router._get_cache_key("chat", "user1", "test prompt")
+    router._store_cache(cache_key, "cached response", "gemini-2.0-flash")
+
+    # Manually expire the cache entry
+    router.cache[cache_key]["timestamp"] = datetime.now() - timedelta(seconds=CACHE_TTL + 1)
+
+    # Should not retrieve expired entry
+    cached = router._check_cache(cache_key)
+    assert cached is None, "Expired cache entry should return None"
+
+
+@test("Cache cleaning removes expired entries")
+def test_cache_cleaning():
+    from app.model_router import ModelRouter, CACHE_TTL
+    router = ModelRouter()
+
+    # Add expired entries
+    for i in range(5):
+        key = f"expired_{i}"
+        router.cache[key] = {
+            "response": f"response_{i}",
+            "timestamp": datetime.now() - timedelta(seconds=CACHE_TTL + 1),
+            "model": "test"
+        }
+
+    # Add valid entry
+    router.cache["valid"] = {
+        "response": "valid_response",
+        "timestamp": datetime.now(),
+        "model": "test"
+    }
+
+    # Clean cache
+    router._clean_cache()
+
+    # Only valid entry should remain
+    assert len(router.cache) == 1, f"Expected 1 entry after cleaning, got {len(router.cache)}"
+    assert "valid" in router.cache, "Valid entry should remain after cleaning"
+
+
+# ========== Stats Tests ==========
+
+@test("Stats returns correct usage info")
+def test_stats():
+    from app.model_router import ModelRouter, MODEL_CONFIGS
+    router = ModelRouter()
+
+    # Record some usage on key 0
+    router._record_usage("gemini-2.0-flash", 0)
+    router._record_usage("gemini-2.0-flash", 0)
+    router._record_usage("gemma-3-27b-it", 0)
+
+    stats = router.get_stats()
+
+    assert stats["models"]["gemini-2.0-flash"]["used"] == 2, "Should show 2 uses for gemini-2.0-flash"
+    assert stats["models"]["gemma-3-27b-it"]["used"] == 1, "Should show 1 use for gemma-3-27b-it"
+    # Limit is per-key * num_keys
+    expected_limit = MODEL_CONFIGS["gemini-2.0-flash"]["rpm"] * len(router.api_keys)
+    assert stats["models"]["gemini-2.0-flash"]["limit"] == expected_limit
+
+
+# ========== Multi-Key Tests ==========
+
+@test("Multiple keys are loaded from environment")
+def test_multi_key_loading():
+    from app.model_router import ModelRouter
+    router = ModelRouter()
+    assert len(router.api_keys) >= 1, "Should have at least one API key"
+
+
+@test("Key health tracking works")
+def test_key_health_tracking():
+    from app.model_router import ModelRouter, KEY_COOLDOWN_RATE_LIMIT
+    router = ModelRouter()
+
+    # Initially all keys should be healthy
+    for i in range(len(router.api_keys)):
+        assert router._is_key_healthy(i) == True, f"Key {i} should be healthy initially"
+
+    # Mark first key as unhealthy
+    router._mark_key_unhealthy(0, Exception("Test error"), KEY_COOLDOWN_RATE_LIMIT)
+
+    assert router._is_key_healthy(0) == False, "Key 0 should be unhealthy after marking"
+    assert router.key_health[0]["last_error"] == "Test error"
+
+
+@test("Key rotation skips unhealthy keys")
+def test_key_rotation_skips_unhealthy():
+    from app.model_router import ModelRouter
+    router = ModelRouter()
+
+    if len(router.api_keys) < 2:
+        return  # Skip if only one key
+
+    # Mark key 0 as unhealthy
+    router._mark_key_unhealthy(0, Exception("Test"), 60)
+
+    # Get next key should skip key 0
+    key_idx, _ = router._get_next_key()
+    assert key_idx != 0 or len(router.api_keys) == 1, "Should skip unhealthy key 0"
+
+
+@test("Key auto-recovers after cooldown")
+def test_key_auto_recovery():
+    from app.model_router import ModelRouter
+    from datetime import datetime, timedelta
+    router = ModelRouter()
+
+    # Mark key as unhealthy with expired cooldown
+    router.key_health[0] = {
+        "healthy": False,
+        "last_error": "Test",
+        "retry_after": datetime.now() - timedelta(seconds=1)  # Already expired
+    }
+
+    # Should recover when checked
+    assert router._is_key_healthy(0) == True, "Key should auto-recover after cooldown"
+    assert router.key_health[0]["healthy"] == True
+    assert router.key_health[0]["last_error"] is None
+
+
+@test("Stats includes key information")
+def test_stats_includes_keys():
+    from app.model_router import ModelRouter
+    router = ModelRouter()
+
+    stats = router.get_stats()
+
+    assert "keys" in stats, "Stats should include keys info"
+    assert stats["keys"]["total"] >= 1, "Should have at least one key"
+    assert stats["keys"]["healthy"] >= 1, "Should have at least one healthy key"
+    assert "details" in stats["keys"], "Stats should include key details"
+
+
+# ========== Integration Tests (requires API key) ==========
+
+@test("Generate returns response and model info")
+async def test_generate_integration():
+    from app.model_router import generate_with_info
+
+    response, model = await generate_with_info(
+        "Say 'test' in one word.",
+        task_type="default",
+        use_cache=False
+    )
+
+    assert response is not None, "Response should not be None"
+    assert len(response) > 0, "Response should not be empty"
+    assert model in ["gemini-2.0-flash", "gemini-2.0-flash-lite", "gemma-3-27b-it",
+                     "gemma-3-12b-it", "gemma-3-4b-it", "gemma-3-1b-it", "cache"]
+
+
+@test("Generate uses cache on repeated calls")
+async def test_generate_uses_cache():
+    from app.model_router import generate_with_info, router
+
+    # Clear cache first
+    router.cache.clear()
+
+    prompt = "Say 'cached test' in two words."
+
+    # First call - should hit model
+    response1, model1 = await generate_with_info(prompt, task_type="default", use_cache=True)
+    assert model1 != "cache", f"First call should not be from cache, got {model1}"
+
+    # Second call - should hit cache
+    response2, model2 = await generate_with_info(prompt, task_type="default", use_cache=True)
+    assert model2 == "cache", f"Second call should be from cache, got {model2}"
+    assert response1 == response2, "Cached response should match original"
+
+
+# ========== Run Tests ==========
+
+async def run_tests():
+    """Run all tests."""
+    print("=" * 60)
+    print("Model Router Tests")
+    print("=" * 60)
+    print()
+
+    # Unit tests (no API needed)
+    print("--- Model Selection Tests ---")
+    await test_model_selection_chat()
+    await test_model_selection_documentation()
+    await test_model_selection_synthesis()
+    await test_model_selection_unknown()
+
+    print()
+    print("--- Rate Limiting Tests ---")
+    await test_rate_limit_tracking()
+    await test_model_fallback()
+    await test_all_models_exhausted()
+
+    print()
+    print("--- Cache Tests ---")
+    await test_cache_store_retrieve()
+    await test_cache_key_user_differentiation()
+    await test_cache_key_task_differentiation()
+    await test_cache_expiry()
+    await test_cache_cleaning()
+
+    print()
+    print("--- Stats Tests ---")
+    await test_stats()
+
+    print()
+    print("--- Multi-Key Tests ---")
+    await test_multi_key_loading()
+    await test_key_health_tracking()
+    await test_key_rotation_skips_unhealthy()
+    await test_key_auto_recovery()
+    await test_stats_includes_keys()
+
+    print()
+    print("--- Integration Tests (requires API key) ---")
+
+    # Check if API key is available
+    if not os.getenv("GEMINI_API_KEY") and not os.getenv("GEMINI_API_KEYS"):
+        print("[SKIP] Integration tests skipped - no API keys")
+    else:
+        await test_generate_integration()
+        await test_generate_uses_cache()
+
+    print()
+    print("=" * 60)
+    print(f"Results: {TESTS_PASSED} passed, {TESTS_FAILED} failed")
+    print("=" * 60)
+
+    return TESTS_FAILED == 0
+
+
+if __name__ == "__main__":
+    success = asyncio.run(run_tests())
+    exit(0 if success else 1)

backend/tests/test_models.py

@@ -0,0 +1,70 @@
+"""Test which Gemini/Gemma models are available for your API key."""
+
+import google.generativeai as genai
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
+GEMINI_API_KEY = os.getenv("GEMINI_API_KEY")
+if not GEMINI_API_KEY:
+    print("ERROR: GEMINI_API_KEY not found in .env")
+    exit(1)
+
+genai.configure(api_key=GEMINI_API_KEY)
+
+# Models to test
+MODELS = [
+    "gemini-2.0-flash",
+    "gemini-2.0-flash-lite",
+    "gemma-3-1b-it",
+    "gemma-3-4b-it",
+    "gemma-3-12b-it",
+    "gemma-3-27b-it",
+]
+
+TEST_PROMPT = "Say 'Hello' in one word."
+
+print("=" * 60)
+print("Testing Gemini/Gemma Models Availability")
+print("=" * 60)
+
+available = []
+unavailable = []
+
+for model_name in MODELS:
+    try:
+        model = genai.GenerativeModel(model_name)
+        response = model.generate_content(TEST_PROMPT)
+        text = response.text.strip()[:50]
+        print(f"[OK]  {model_name:25} -> {text}")
+        available.append(model_name)
+    except Exception as e:
+        error_msg = str(e)[:60]
+        print(f"[ERR] {model_name:25} -> {error_msg}")
+        unavailable.append(model_name)
+
+print("\n" + "=" * 60)
+print("SUMMARY")
+print("=" * 60)
+print(f"\nAvailable ({len(available)}):")
+for m in available:
+    print(f"  - {m}")
+
+print(f"\nUnavailable ({len(unavailable)}):")
+for m in unavailable:
+    print(f"  - {m}")
+
+# Calculate combined RPM
+rpm_map = {
+    "gemini-2.0-flash": 15,
+    "gemini-2.0-flash-lite": 30,
+    "gemma-3-1b-it": 30,
+    "gemma-3-4b-it": 30,
+    "gemma-3-12b-it": 30,
+    "gemma-3-27b-it": 30,
+}
+
+total_rpm = sum(rpm_map.get(m, 0) for m in available)
+print(f"\nCombined RPM capacity: {total_rpm} RPM")
+print(f"With 50% cache hit rate: ~{total_rpm * 2} effective RPM")

backend/tests/test_projects.py

@@ -0,0 +1,171 @@
+"""Unit tests for project tools."""
+
+import pytest
+from app.tools.projects import (
+    create_project, list_projects, join_project, check_project_id_available
+)
+from app.database import SessionLocal
+from app.models import Project, ProjectMembership
+
+
+class TestCheckProjectIdAvailable:
+    """Test project ID availability checking."""
+
+    def test_available_id(self, create_user):
+        """Test checking an available project ID."""
+        result = check_project_id_available("nonexistent-project")
+        
+        assert result["available"] == True
+        assert result["project_id"] == "nonexistent-project"
+
+    def test_unavailable_id(self, create_user):
+        """Test checking an ID that's already taken."""
+        user = create_user("Test", "User")
+        
+        # Create a project first
+        create_project("takenid", "Description", user.id)
+        
+        # Check if the ID is available
+        result = check_project_id_available("takenid")
+        
+        assert result["available"] == False
+        assert result["project_id"] == "takenid"
+
+
+class TestCreateProject:
+    """Test project creation with name as ID."""
+
+    def test_create_project_uses_name_as_id(self, create_user):
+        """Test that project name is used as project ID."""
+        user = create_user("Creator", "Test")
+        
+        result = create_project("fastgate", "A fast gateway", user.id)
+        
+        assert result["id"] == "fastgate"
+        assert result["name"] == "fastgate"
+        assert result["description"] == "A fast gateway"
+        assert result["created_by"] == user.id
+
+    def test_create_project_adds_owner_membership(self, create_user):
+        """Test that creator is added as owner."""
+        user = create_user("Owner", "Test")
+        
+        result = create_project("ownerproj", "Test", user.id)
+        
+        db = SessionLocal()
+        try:
+            membership = db.query(ProjectMembership).filter(
+                ProjectMembership.project_id == result["id"],
+                ProjectMembership.user_id == user.id
+            ).first()
+            
+            assert membership is not None
+            assert membership.role == "owner"
+        finally:
+            db.close()
+
+    def test_create_project_duplicate_id_fails(self, create_user):
+        """Test that creating project with existing ID fails."""
+        user = create_user("Test", "User")
+        
+        # Create first project
+        create_project("duplicate", "First project", user.id)
+        
+        # Try to create another with same name/ID
+        result = create_project("duplicate", "Second project", user.id)
+        
+        assert "error" in result
+        assert "already exists" in result["error"]
+
+    def test_create_project_nonexistent_user(self):
+        """Test creating project with non-existent user fails."""
+        result = create_project("orphan", "No owner", "nonexistent-user-id")
+        
+        assert "error" in result
+        assert "not found" in result["error"]
+
+
+class TestListProjects:
+    """Test listing user's projects."""
+
+    def test_list_projects_empty(self, create_user):
+        """Test listing projects for user with no projects."""
+        user = create_user("New", "User")
+        
+        result = list_projects(user.id)
+        
+        assert "projects" in result
+        assert len(result["projects"]) == 0
+
+    def test_list_projects_with_owned_project(self, create_user):
+        """Test listing projects includes owned projects."""
+        user = create_user("Owner", "Test")
+        create_project("ownedproj", "My project", user.id)
+        
+        result = list_projects(user.id)
+        
+        assert len(result["projects"]) == 1
+        assert result["projects"][0]["name"] == "ownedproj"
+        assert result["projects"][0]["role"] == "owner"
+
+    def test_list_projects_with_member_project(self, create_user):
+        """Test listing projects includes joined projects."""
+        owner = create_user("Owner", "Test")
+        member = create_user("Member", "Test")
+        
+        create_project("sharedproj", "Shared project", owner.id)
+        join_project("sharedproj", member.id)
+        
+        result = list_projects(member.id)
+        
+        assert len(result["projects"]) == 1
+        assert result["projects"][0]["name"] == "sharedproj"
+        assert result["projects"][0]["role"] == "member"
+
+
+class TestJoinProject:
+    """Test joining existing projects."""
+
+    def test_join_project_success(self, create_user):
+        """Test successfully joining a project."""
+        owner = create_user("Owner", "Test")
+        member = create_user("Member", "Test")
+        
+        create_project("jointest", "Test project", owner.id)
+        result = join_project("jointest", member.id)
+        
+        assert "message" in result
+        assert result["project_id"] == "jointest"
+        assert result["role"] == "member"
+
+    def test_join_project_already_member(self, create_user):
+        """Test joining a project you're already a member of."""
+        owner = create_user("Owner", "Test")
+        member = create_user("Member", "Test")
+        
+        create_project("alreadyin", "Test project", owner.id)
+        join_project("alreadyin", member.id)
+        
+        # Try joining again
+        result = join_project("alreadyin", member.id)
+        
+        assert "Already a member" in result.get("message", "")
+
+    def test_join_nonexistent_project(self, create_user):
+        """Test joining a project that doesn't exist."""
+        user = create_user("User", "Test")
+        
+        result = join_project("doesnotexist", user.id)
+        
+        assert "error" in result
+        assert "not found" in result["error"]
+
+    def test_join_project_nonexistent_user(self, create_user):
+        """Test joining with non-existent user."""
+        owner = create_user("Owner", "Test")
+        create_project("validproj", "Test", owner.id)
+        
+        result = join_project("validproj", "nonexistent-user")
+        
+        assert "error" in result
+        assert "not found" in result["error"]

backend/tests/test_scenarios.py

@@ -0,0 +1,148 @@
+import asyncio
+from concurrent.futures import ThreadPoolExecutor, as_completed
+import pytest
+from app.tools.projects import create_project, join_project
+from app.tools.tasks import create_task
+from app.tools import memory as memory_tools
+from app.database import SessionLocal
+from app.models import ProjectMembership, Task as TaskModel, LogEntry, TaskStatus
+
+@pytest.mark.timeout(30)
+def test_1_project_multiple_members(create_user):
+    """
+    Scenario: One project is created, and multiple members join it.
+    """
+    # 1. Setup users
+    owner = create_user("Owner", "One")
+    member2 = create_user("Member", "Two")
+    member3 = create_user("Member", "Three")
+
+    # 2. Create project
+    proj = create_project("Proj A", "Test project", owner.id)
+    pid = proj["id"]
+
+    # 3. Members join
+    join_project(pid, member2.id)
+    join_project(pid, member3.id)
+
+    # 4. Verify DB state
+    db = SessionLocal()
+    try:
+        memberships = db.query(ProjectMembership).filter(ProjectMembership.project_id == pid).all()
+        assert len(memberships) == 3  # Owner + 2 members
+    finally:
+        db.close()
+
+
+@pytest.mark.timeout(60)
+def test_multiple_projects_multiple_members(create_user):
+    """
+    Scenario: Multiple projects created at same time, and everyone joins all of them together.
+    """
+    # Create 5 users
+    users = [create_user(f"User{i}", f"Last{i}") for i in range(5)]
+    creator_ids = [u.id for u in users[:3]] # First 3 users create projects
+
+    # Helper to create project in a thread
+    def _mk(name, desc, uid):
+        return create_project(name, desc, uid)
+
+    # Run 3 creates in parallel
+    with ThreadPoolExecutor(max_workers=6) as tp:
+        futures = [tp.submit(_mk, f"P{i}", "desc", creator_ids[i]) for i in range(len(creator_ids))]
+        projects = [f.result() for f in futures]
+
+    pids = [p["id"] for p in projects]
+
+    # Helper to join project in a thread
+    def _join(pid, uid):
+        return join_project(pid, uid)
+
+    # Run ALL joins in parallel (3 projects * 5 users = 15 joins)
+    with ThreadPoolExecutor(max_workers=15) as tp:
+        futs = []
+        for pid in pids:
+            for u in users:
+                futs.append(tp.submit(_join, pid, u.id))
+        # Wait for all to finish
+        for f in as_completed(futs):
+            f.result()
+
+    # Verify: Every project should have 5 members
+    db = SessionLocal()
+    try:
+        for pid in pids:
+            mems = db.query(ProjectMembership).filter(ProjectMembership.project_id == pid).all()
+            unique_members = set(m.user_id for m in mems)
+            assert len(unique_members) == 5
+    finally:
+        db.close()
+
+
+@pytest.mark.asyncio
+@pytest.mark.timeout(60)
+async def test_concurrent_task_completion(create_user, monkeypatch):
+    """
+    Scenario: Multiple members complete tasks simultaneously.
+    (Uses mocks for LLM to run fast without API keys)
+    """
+    owner = create_user("Owner", "Test")
+    members = [create_user(f"Member{i}", f"Test{i}") for i in range(3)]
+    proj = create_project("Concurrency", "Simul tasks", owner.id)
+    pid = proj["id"]
+
+    # Mock LLM calls (fake them)
+    async def fake_doc(*args, **kwargs):
+        return {"summary": "Done", "details": "Details...", "tags": ["test"]}
+    
+    async def fake_embed(*args, **kwargs):
+        return [0.0] * 768 # Fake vector
+
+    # Replace real functions with fakes
+    monkeypatch.setattr(memory_tools, "generate_documentation", fake_doc)
+    monkeypatch.setattr(memory_tools, "get_embedding", fake_embed)
+    monkeypatch.setattr(memory_tools, "add_embedding", lambda **kw: None)
+
+    # Setup tasks
+    users = [owner] + members
+    tasks = [create_task(pid, f"Task {i}", "desc", assigned_to=u.id) for i, u in enumerate(users)]
+    
+    # Run completion in parallel
+    results = await asyncio.gather(*[
+        memory_tools.complete_task(tasks[i]["id"], pid, users[i].id, "Finished") 
+        for i in range(len(users))
+    ])
+
+    assert all(r.get("success") for r in results)
+
+
+@pytest.mark.timeout(30)
+@pytest.mark.xfail(reason="Known Issue: No DB constraint prevents duplicate joins under race conditions")
+def test_same_user_joining_twice_simultaneously(create_user):
+    """
+    Scenario: The same user tries to join the same project twice at the exact same time.
+    """
+    owner = create_user("Owner", "Two")
+    member = create_user("New", "Member")
+    proj = create_project("Proj Race", "Race condition join", owner.id)
+    pid = proj["id"]
+
+    # Helper to join
+    def _join():
+        return join_project(pid, member.id)
+
+    # Run 2 joins in parallel for SAME user
+    with ThreadPoolExecutor(max_workers=2) as tp:
+        futures = [tp.submit(_join) for _ in range(2)]
+        _ = [f.result() for f in futures]
+
+    # Assert: Should only be 1 membership record
+    db = SessionLocal()
+    try:
+        mems = db.query(ProjectMembership).filter(
+            ProjectMembership.project_id == pid,
+            ProjectMembership.user_id == member.id,
+        ).all()
+        assert len(mems) == 1
+    finally:
+        db.close()

backend/tests/test_schemas.py

@@ -0,0 +1,198 @@
+"""Unit tests for Pydantic schemas."""
+
+import pytest
+from datetime import datetime
+from pydantic import ValidationError
+
+from app.schemas import (
+    UserBase, UserCreate, User,
+    ProjectBase, ProjectCreate, ProjectJoin, Project,
+    TaskBase, TaskCreate, Task,
+    TaskCompleteRequest, TaskCompleteResponse,
+    SearchRequest, SearchFilters, SearchResponse,
+    SmartQueryRequest, SmartQueryResponse
+)
+
+
+class TestUserSchemas:
+    """Test User-related schemas."""
+
+    def test_user_base_requires_names(self):
+        """Test UserBase requires firstName and lastName."""
+        user = UserBase(firstName="John", lastName="Doe")
+        assert user.firstName == "John"
+        assert user.lastName == "Doe"
+
+    def test_user_base_no_email_field(self):
+        """Test UserBase does not have email field."""
+        user = UserBase(firstName="Test", lastName="User")
+        assert not hasattr(user, "email")
+
+    def test_user_base_optional_avatar(self):
+        """Test avatar_url is optional."""
+        user = UserBase(firstName="Test", lastName="User")
+        assert user.avatar_url is None
+        
+        user_with_avatar = UserBase(
+            firstName="Test",
+            lastName="User",
+            avatar_url="https://example.com/avatar.png"
+        )
+        assert user_with_avatar.avatar_url == "https://example.com/avatar.png"
+
+    def test_user_create_inherits_user_base(self):
+        """Test UserCreate has same fields as UserBase."""
+        user = UserCreate(firstName="New", lastName="User")
+        assert user.firstName == "New"
+        assert user.lastName == "User"
+
+    def test_user_validation_missing_first_name(self):
+        """Test validation fails without firstName."""
+        with pytest.raises(ValidationError):
+            UserBase(lastName="Doe")
+
+    def test_user_validation_missing_last_name(self):
+        """Test validation fails without lastName."""
+        with pytest.raises(ValidationError):
+            UserBase(firstName="John")
+
+    def test_user_schema_has_id_and_created_at(self):
+        """Test User schema includes id and created_at."""
+        user = User(
+            id="tes1234",
+            firstName="Test",
+            lastName="User",
+            created_at=datetime.now()
+        )
+        assert user.id == "tes1234"
+        assert user.created_at is not None
+
+
+class TestProjectSchemas:
+    """Test Project-related schemas."""
+
+    def test_project_base(self):
+        """Test ProjectBase schema."""
+        project = ProjectBase(name="myproject", description="A test project")
+        assert project.name == "myproject"
+        assert project.description == "A test project"
+
+    def test_project_create_requires_user_id(self):
+        """Test ProjectCreate requires userId."""
+        project = ProjectCreate(
+            name="testproj",
+            description="Test",
+            userId="usr1234"
+        )
+        assert project.userId == "usr1234"
+
+    def test_project_join_schema(self):
+        """Test ProjectJoin schema."""
+        join = ProjectJoin(userId="usr1234")
+        assert join.userId == "usr1234"
+
+    def test_project_schema(self):
+        """Test full Project schema."""
+        project = Project(
+            id="myproject",
+            name="myproject",
+            description="Test",
+            created_by="usr1234",
+            created_at=datetime.now()
+        )
+        assert project.id == project.name  # ID is the name
+
+
+class TestTaskSchemas:
+    """Test Task-related schemas."""
+
+    def test_task_base(self):
+        """Test TaskBase schema."""
+        task = TaskBase(title="Test Task")
+        assert task.title == "Test Task"
+        assert task.description is None
+
+    def test_task_create_optional_assigned_to(self):
+        """Test TaskCreate has optional assignedTo."""
+        task = TaskCreate(title="Unassigned Task")
+        assert task.assignedTo is None
+        
+        assigned_task = TaskCreate(title="Assigned", assignedTo="usr1234")
+        assert assigned_task.assignedTo == "usr1234"
+
+    def test_task_complete_request(self):
+        """Test TaskCompleteRequest schema."""
+        request = TaskCompleteRequest(
+            userId="usr1234",
+            whatIDid="Fixed the bug",
+            codeSnippet="def fix(): pass"
+        )
+        assert request.userId == "usr1234"
+        assert request.whatIDid == "Fixed the bug"
+        assert request.codeSnippet == "def fix(): pass"
+
+    def test_task_complete_request_optional_code(self):
+        """Test codeSnippet is optional."""
+        request = TaskCompleteRequest(
+            userId="usr1234",
+            whatIDid="Fixed the bug"
+        )
+        assert request.codeSnippet is None
+
+
+class TestSearchSchemas:
+    """Test Search-related schemas."""
+
+    def test_search_filters_all_optional(self):
+        """Test SearchFilters has all optional fields."""
+        filters = SearchFilters()
+        assert filters.userId is None
+        assert filters.dateFrom is None
+        assert filters.dateTo is None
+        assert filters.tags is None
+
+    def test_search_request(self):
+        """Test SearchRequest schema."""
+        request = SearchRequest(query="authentication")
+        assert request.query == "authentication"
+        assert request.filters is None
+
+    def test_search_request_with_filters(self):
+        """Test SearchRequest with filters."""
+        filters = SearchFilters(userId="usr1234", tags=["auth", "security"])
+        request = SearchRequest(query="login", filters=filters)
+        assert request.filters.userId == "usr1234"
+        assert request.filters.tags == ["auth", "security"]
+
+
+class TestSmartQuerySchemas:
+    """Test SmartQuery-related schemas."""
+
+    def test_smart_query_request(self):
+        """Test SmartQueryRequest schema."""
+        request = SmartQueryRequest(
+            query="What did I do yesterday?",
+            currentUserId="usr1234"
+        )
+        assert request.query == "What did I do yesterday?"
+        assert request.currentUserId == "usr1234"
+        assert request.currentDatetime is None
+
+    def test_smart_query_request_with_datetime(self):
+        """Test SmartQueryRequest with datetime."""
+        request = SmartQueryRequest(
+            query="What tasks are done?",
+            currentUserId="usr1234",
+            currentDatetime="2025-11-30T12:00:00Z"
+        )
+        assert request.currentDatetime == "2025-11-30T12:00:00Z"
+
+    def test_smart_query_response(self):
+        """Test SmartQueryResponse schema."""
+        response = SmartQueryResponse(
+            answer="You completed the auth task yesterday.",
+            tools_used=["get_user_activity"],
+            sources=[]
+        )
+        assert response.answer == "You completed the auth task yesterday."
+        assert "get_user_activity" in response.tools_used

backend/tests/test_smart_query.py

@@ -0,0 +1,656 @@
+"""
+Smart Query Test Suite - Run with: python test_smart_query.py
+
+Tests the smart query tool functions and integration.
+Requires GEMINI_API_KEY for full integration tests.
+"""
+
+import asyncio
+import sys
+from datetime import datetime, timedelta
+
+sys.path.insert(0, '.')
+
+from app.database import init_db, SessionLocal
+from app.models import User, Task, LogEntry, TaskStatus, ActorType, ActionType, ProjectMembership
+from app.tools.projects import create_project
+from app.tools.tasks import create_task
+from app.vectorstore import init_vectorstore, delete_by_project
+
+# Test counters
+passed = 0
+failed = 0
+
+
+def test(name, condition, details=""):
+    global passed, failed
+    if condition:
+        print(f"  [PASS] {name}")
+        passed += 1
+    else:
+        print(f"  [FAIL] {name} - {details}")
+        failed += 1
+
+
+def create_test_user(db, first_name: str, last_name: str) -> User:
+    """Create a test user and return the user object."""
+    from app.models import generate_user_id
+    user_id = generate_user_id(first_name)
+    user = User(id=user_id, first_name=first_name, last_name=last_name)
+    db.add(user)
+    db.commit()
+    db.refresh(user)
+    return user
+
+
+def create_test_log_entry(db, project_id: str, task_id: str, user_id: str, raw_input: str, hours_ago: int = 0) -> LogEntry:
+    """Create a test log entry."""
+    entry = LogEntry(
+        project_id=project_id,
+        task_id=task_id,
+        user_id=user_id,
+        actor_type=ActorType.human,
+        action_type=ActionType.task_completed,
+        raw_input=raw_input,
+        generated_doc=f"Documentation for: {raw_input}",
+        tags=["test"],
+        created_at=datetime.now() - timedelta(hours=hours_ago)
+    )
+    db.add(entry)
+    db.commit()
+    db.refresh(entry)
+    return entry
+
+
+def setup_test_data():
+    """Set up test data and return IDs."""
+    db = SessionLocal()
+    try:
+        # Create users
+        user1 = create_test_user(db, "Alice", "Developer")
+        user2 = create_test_user(db, "Bob", "Developer")
+
+        # Create project
+        project_result = create_project(
+            name=f"Smart Query Test Project {datetime.now().timestamp()}",
+            description="Testing smart query functionality",
+            user_id=user1.id
+        )
+        project_id = project_result["id"]
+
+        # Add user2 to project
+        membership = ProjectMembership(project_id=project_id, user_id=user2.id, role="member")
+        db.add(membership)
+        db.commit()
+
+        # Create tasks
+        task1_result = create_task(
+            project_id=project_id,
+            title="Implement Authentication API",
+            description="Build JWT auth system",
+            assigned_to=user1.id
+        )
+        task1_id = task1_result["id"]
+
+        task2_result = create_task(
+            project_id=project_id,
+            title="Write Unit Tests",
+            description="Create test coverage",
+            assigned_to=user2.id
+        )
+        task2_id = task2_result["id"]
+
+        # Mark task1 as done
+        task1 = db.query(Task).filter(Task.id == task1_id).first()
+        task1.status = TaskStatus.done
+        task1.completed_at = datetime.now() - timedelta(hours=2)
+        db.commit()
+
+        # Create log entries
+        log1 = create_test_log_entry(
+            db, project_id, task1_id, user1.id,
+            "Implemented JWT authentication with refresh tokens",
+            hours_ago=2
+        )
+
+        log2 = create_test_log_entry(
+            db, project_id, task1_id, user1.id,
+            "Added password hashing with bcrypt",
+            hours_ago=25  # Yesterday
+        )
+
+        log3 = create_test_log_entry(
+            db, project_id, task2_id, user2.id,
+            "Created unit tests for auth module",
+            hours_ago=1
+        )
+
+        return {
+            "project_id": project_id,
+            "user1_id": user1.id,
+            "user1_name": user1.name,
+            "user2_id": user2.id,
+            "user2_name": user2.name,
+            "task1_id": task1_id,
+            "task2_id": task2_id,
+            "log1_id": log1.id,
+            "log2_id": log2.id,
+            "log3_id": log3.id,
+        }
+    finally:
+        db.close()
+
+
+def test_tool_functions(test_data):
+    """Test individual tool functions."""
+    print("\n[1/4] Testing Smart Query Tool Functions")
+    print("-" * 50)
+
+    from app.smart_query import (
+        _tool_get_user_activity,
+        _tool_get_task_status,
+        _tool_check_completion,
+        _tool_list_users,
+        QueryContext,
+    )
+
+    db = SessionLocal()
+    context = QueryContext(
+        current_user_id=test_data["user1_id"],
+        current_datetime=datetime.now(),
+        project_id=test_data["project_id"]
+    )
+
+    try:
+        # Test _tool_get_user_activity with user_id
+        print("\n  Testing _tool_get_user_activity...")
+        today = datetime.now().date()
+        yesterday = (datetime.now() - timedelta(days=1)).date()
+
+        result = _tool_get_user_activity(db, context, {
+            "user_id": test_data["user1_id"],
+            "date_from": yesterday.isoformat(),
+            "date_to": (today + timedelta(days=1)).isoformat()
+        })
+        test("get_user_activity returns dict", isinstance(result, dict))
+        test("get_user_activity has count", "count" in result)
+        test("get_user_activity has activities", "activities" in result)
+        test("get_user_activity finds entries", result["count"] >= 1, f"got {result['count']}")
+
+        # Test _tool_get_user_activity with user_name
+        result2 = _tool_get_user_activity(db, context, {
+            "user_name": "Alice",
+            "date_from": yesterday.isoformat(),
+            "date_to": (today + timedelta(days=1)).isoformat()
+        })
+        test("get_user_activity resolves name", result2["user_id"] == test_data["user1_id"])
+
+        # Test _tool_get_task_status by ID
+        print("\n  Testing _tool_get_task_status...")
+        result = _tool_get_task_status(db, test_data["project_id"], {
+            "task_id": test_data["task1_id"]
+        })
+        test("get_task_status returns dict", isinstance(result, dict))
+        test("get_task_status found=True", result.get("found") == True)
+        test("get_task_status has task", "task" in result)
+        test("get_task_status correct title", "Authentication" in result["task"]["title"])
+        test("get_task_status status is done", result["task"]["status"] == "done")
+
+        # Test _tool_get_task_status by title
+        result2 = _tool_get_task_status(db, test_data["project_id"], {
+            "task_title": "Unit Tests"
+        })
+        test("get_task_status by title works", result2.get("found") == True)
+        test("get_task_status by title correct", "Unit Tests" in result2["task"]["title"])
+
+        # Test _tool_get_task_status not found
+        result3 = _tool_get_task_status(db, test_data["project_id"], {
+            "task_title": "Nonexistent Task XYZ"
+        })
+        test("get_task_status not found", result3.get("found") == False)
+
+        # Test _tool_check_completion
+        print("\n  Testing _tool_check_completion...")
+        result = _tool_check_completion(db, test_data["project_id"], {
+            "task_title": "Authentication"
+        })
+        test("check_completion returns dict", isinstance(result, dict))
+        test("check_completion found", result.get("found") == True)
+        test("check_completion is_completed", result.get("is_completed") == True)
+        test("check_completion has details", result.get("completion_details") is not None)
+
+        # Test _tool_check_completion with user
+        result2 = _tool_check_completion(db, test_data["project_id"], {
+            "task_title": "Authentication",
+            "user_name": "Alice"
+        })
+        test("check_completion by user works", result2.get("completed_by_specified_user") == True)
+
+        result3 = _tool_check_completion(db, test_data["project_id"], {
+            "task_title": "Authentication",
+            "user_name": "Bob"
+        })
+        test("check_completion wrong user", result3.get("completed_by_specified_user") == False)
+
+        # Test _tool_list_users
+        print("\n  Testing _tool_list_users...")
+        result = _tool_list_users(db, test_data["project_id"])
+        test("list_users returns dict", isinstance(result, dict))
+        test("list_users has users", "users" in result)
+        test("list_users has count", "count" in result)
+        test("list_users finds 2 users", result["count"] == 2, f"got {result['count']}")
+
+        user_names = [u["name"] for u in result["users"]]
+        test("list_users includes Alice", any("Alice" in n for n in user_names))
+        test("list_users includes Bob", any("Bob" in n for n in user_names))
+
+    finally:
+        db.close()
+
+
+def test_extract_sources():
+    """Test the extract_sources helper."""
+    print("\n[2/4] Testing extract_sources Helper")
+    print("-" * 50)
+
+    from app.smart_query import extract_sources
+
+    # Test with activity results
+    tool_results = [
+        {
+            "tool": "get_user_activity",
+            "result": {
+                "activities": [
+                    {"id": "log-1", "what_was_done": "Built auth", "timestamp": "2024-01-01T10:00:00"},
+                    {"id": "log-2", "what_was_done": "Fixed bug", "timestamp": "2024-01-01T11:00:00"},
+                ]
+            }
+        }
+    ]
+    sources = extract_sources(tool_results)
+    test("extract_sources returns list", isinstance(sources, list))
+    test("extract_sources extracts activities", len(sources) == 2)
+    test("extract_sources has type=activity", sources[0]["type"] == "activity")
+
+    # Test with semantic search results
+    tool_results2 = [
+        {
+            "tool": "semantic_search",
+            "result": {
+                "results": [
+                    {"id": "mem-1", "what_was_done": "Implemented login", "relevance_score": 0.95},
+                ]
+            }
+        }
+    ]
+    sources2 = extract_sources(tool_results2)
+    test("extract_sources handles search results", len(sources2) == 1)
+    test("extract_sources has type=memory", sources2[0]["type"] == "memory")
+
+    # Test with task results
+    tool_results3 = [
+        {
+            "tool": "get_task_status",
+            "result": {
+                "found": True,
+                "task": {"id": "task-1", "title": "Auth API", "status": "done"}
+            }
+        }
+    ]
+    sources3 = extract_sources(tool_results3)
+    test("extract_sources handles task results", len(sources3) == 1)
+    test("extract_sources has type=task", sources3[0]["type"] == "task")
+
+    # Test deduplication
+    tool_results4 = [
+        {"tool": "get_user_activity", "result": {"activities": [{"id": "dup-1", "what_was_done": "Test"}]}},
+        {"tool": "get_user_activity", "result": {"activities": [{"id": "dup-1", "what_was_done": "Test"}]}},
+    ]
+    sources4 = extract_sources(tool_results4)
+    test("extract_sources deduplicates", len(sources4) == 1)
+
+
+def test_query_context():
+    """Test QueryContext dataclass."""
+    print("\n[3/4] Testing QueryContext")
+    print("-" * 50)
+
+    from app.smart_query import QueryContext
+
+    ctx = QueryContext(
+        current_user_id="user-123",
+        current_datetime=datetime(2024, 1, 15, 10, 30, 0),
+        project_id="proj-456"
+    )
+
+    test("QueryContext has current_user_id", ctx.current_user_id == "user-123")
+    test("QueryContext has current_datetime", ctx.current_datetime.year == 2024)
+    test("QueryContext has project_id", ctx.project_id == "proj-456")
+
+
+async def test_semantic_search_tool(test_data):
+    """Test semantic search tool (requires API key)."""
+    print("\n[4/4] Testing Semantic Search Tool (requires API)")
+    print("-" * 50)
+
+    try:
+        from app.smart_query import _tool_semantic_search
+        from app.llm import get_embedding
+        from app.vectorstore import add_embedding
+
+        # Add test embedding
+        text = "Implemented JWT authentication with refresh tokens"
+        emb = await get_embedding(text)
+        add_embedding(
+            log_entry_id=test_data["log1_id"],
+            text=text,
+            embedding=emb,
+            metadata={
+                "project_id": test_data["project_id"],
+                "user_id": test_data["user1_id"],
+                "task_id": test_data["task1_id"],
+                "created_at": datetime.now().isoformat()
+            }
+        )
+
+        # Test semantic search
+        result = await _tool_semantic_search(test_data["project_id"], {
+            "search_query": "authentication JWT"
+        })
+
+        test("semantic_search returns dict", isinstance(result, dict))
+        test("semantic_search has results", "results" in result)
+        test("semantic_search has count", "count" in result)
+        test("semantic_search finds results", result["count"] > 0, f"got {result['count']}")
+
+        if result["results"]:
+            test("semantic_search result has id", "id" in result["results"][0])
+            test("semantic_search result has relevance", "relevance_score" in result["results"][0])
+
+    except Exception as e:
+        test("semantic_search (API required)", False, str(e))
+
+
+async def test_full_smart_query(test_data):
+    """Test the full smart_query function (requires API key)."""
+    print("\n[BONUS] Testing Full smart_query Integration")
+    print("-" * 50)
+
+    try:
+        from app.smart_query import smart_query
+
+        # Test simple query
+        result = await smart_query(
+            project_id=test_data["project_id"],
+            query="What tasks are done?",
+            current_user_id=test_data["user1_id"],
+            current_datetime=datetime.now().isoformat()
+        )
+
+        test("smart_query returns dict", isinstance(result, dict))
+        test("smart_query has answer", "answer" in result)
+        test("smart_query has tools_used", "tools_used" in result)
+        test("smart_query has sources", "sources" in result)
+        test("smart_query answer not empty", len(result.get("answer", "")) > 0)
+
+        print(f"\n  Query: 'What tasks are done?'")
+        print(f"  Answer: {result.get('answer', '')[:200]}...")
+        print(f"  Tools used: {result.get('tools_used', [])}")
+
+    except Exception as e:
+        test("smart_query integration (API required)", False, str(e))
+
+
+def test_user_resolution(test_data):
+    """Test duplicate name handling in user resolution."""
+    print("\n[NEW] Testing User Resolution & Duplicate Name Handling")
+    print("-" * 50)
+
+    from app.smart_query import (
+        _resolve_user_in_project,
+        _get_recent_work_hint,
+        _tool_get_user_activity,
+        _tool_check_completion,
+        QueryContext,
+    )
+
+    db = SessionLocal()
+
+    try:
+        # Test _get_recent_work_hint
+        print("\n  Testing _get_recent_work_hint...")
+        hint = _get_recent_work_hint(db, str(test_data["user1_id"]), test_data["project_id"])
+        test("get_recent_work_hint returns string", isinstance(hint, str))
+        test("get_recent_work_hint has content", len(hint) > 0)
+        test("get_recent_work_hint format correct", "worked on:" in hint or hint == "no recent activity")
+
+        # Test _resolve_user_in_project - single match
+        print("\n  Testing _resolve_user_in_project (single match)...")
+        result = _resolve_user_in_project(db, test_data["project_id"], "Alice")
+        test("resolve single user found=True", result.get("found") == True)
+        test("resolve single user has user_id", "user_id" in result)
+        test("resolve single user correct id", result.get("user_id") == str(test_data["user1_id"]))
+
+        # Test _resolve_user_in_project - not found
+        print("\n  Testing _resolve_user_in_project (not found)...")
+        result2 = _resolve_user_in_project(db, test_data["project_id"], "NonExistentUser")
+        test("resolve not found returns found=False", result2.get("found") == False)
+        test("resolve not found reason=not_found", result2.get("reason") == "not_found")
+        test("resolve not found has message", "message" in result2)
+
+        # Create duplicate name scenario
+        print("\n  Testing duplicate name handling...")
+        # Add another user with similar name to the project
+        duplicate_user = User(name="Dev Alice Smith", email=f"alice.smith_{datetime.now().timestamp()}@test.com")
+        db.add(duplicate_user)
+        db.commit()
+        db.refresh(duplicate_user)
+
+        # Add to project
+        membership = ProjectMembership(project_id=test_data["project_id"], user_id=duplicate_user.id, role="member")
+        db.add(membership)
+        db.commit()
+
+        # Now search for "Alice" - should find 2 users
+        result3 = _resolve_user_in_project(db, test_data["project_id"], "Alice")
+        test("resolve ambiguous found=False", result3.get("found") == False)
+        test("resolve ambiguous reason=ambiguous", result3.get("reason") == "ambiguous")
+        test("resolve ambiguous has options", "options" in result3)
+        test("resolve ambiguous options is list", isinstance(result3.get("options"), list))
+        test("resolve ambiguous has 2 options", len(result3.get("options", [])) == 2, f"got {len(result3.get('options', []))}")
+
+        if result3.get("options"):
+            opt = result3["options"][0]
+            test("option has user_id", "user_id" in opt)
+            test("option has name", "name" in opt)
+            test("option has email", "email" in opt)
+            test("option has role", "role" in opt)
+            test("option has recent_work", "recent_work" in opt)
+
+        # Test that _tool_get_user_activity returns disambiguation
+        print("\n  Testing tool returns disambiguation...")
+        context = QueryContext(
+            current_user_id=str(test_data["user1_id"]),
+            current_datetime=datetime.now(),
+            project_id=test_data["project_id"]
+        )
+        today = datetime.now().date()
+        yesterday = (datetime.now() - timedelta(days=1)).date()
+
+        activity_result = _tool_get_user_activity(db, context, {
+            "user_name": "Alice",
+            "date_from": yesterday.isoformat(),
+            "date_to": (today + timedelta(days=1)).isoformat()
+        })
+        test("tool returns ambiguous response", activity_result.get("found") == False)
+        test("tool has options", "options" in activity_result)
+
+        # Test that _tool_check_completion returns disambiguation
+        completion_result = _tool_check_completion(db, test_data["project_id"], {
+            "task_title": "Authentication",
+            "user_name": "Alice"
+        })
+        test("check_completion returns ambiguous", completion_result.get("found") == False)
+        test("check_completion has options", "options" in completion_result)
+
+        # Cleanup the duplicate user
+        db.query(ProjectMembership).filter(ProjectMembership.user_id == duplicate_user.id).delete()
+        db.query(User).filter(User.id == duplicate_user.id).delete()
+        db.commit()
+
+        # Test email fallback
+        print("\n  Testing email fallback...")
+        result4 = _resolve_user_in_project(db, test_data["project_id"], "alice")  # Part of email
+        # This might match by name or email depending on data
+        test("email fallback works", result4.get("found") == True or result4.get("reason") == "ambiguous")
+
+    finally:
+        db.close()
+
+
+async def test_memory_search_filters(test_data):
+    """Test memory_search with filters (requires API key)."""
+    print("\n[FILTERS] Testing memory_search Filters")
+    print("-" * 50)
+
+    try:
+        from app.tools.memory import memory_search
+        from app.llm import get_embedding
+        from app.vectorstore import add_embedding
+
+        # Add test embeddings with different users and dates
+        text1 = "User1 implemented login feature yesterday"
+        text2 = "User2 added payment processing today"
+
+        emb1 = await get_embedding(text1)
+        emb2 = await get_embedding(text2)
+
+        yesterday = (datetime.now() - timedelta(days=1)).isoformat()
+        today = datetime.now().isoformat()
+
+        add_embedding(
+            log_entry_id=str(test_data["log1_id"]) + "-filter1",
+            text=text1,
+            embedding=emb1,
+            metadata={
+                "project_id": test_data["project_id"],
+                "user_id": str(test_data["user1_id"]),
+                "task_id": str(test_data["task1_id"]),
+                "created_at": yesterday
+            }
+        )
+
+        add_embedding(
+            log_entry_id=str(test_data["log2_id"]) + "-filter2",
+            text=text2,
+            embedding=emb2,
+            metadata={
+                "project_id": test_data["project_id"],
+                "user_id": str(test_data["user2_id"]),
+                "task_id": str(test_data["task2_id"]),
+                "created_at": today
+            }
+        )
+
+        # Test 1: Search without filters
+        print("\n  Testing search without filters...")
+        result_no_filter = await memory_search(
+            project_id=test_data["project_id"],
+            query="feature implementation"
+        )
+        test("search without filters returns answer", "answer" in result_no_filter)
+
+        # Test 2: Search with userId filter
+        print("\n  Testing search with userId filter...")
+        result_user_filter = await memory_search(
+            project_id=test_data["project_id"],
+            query="feature implementation",
+            filters={"userId": str(test_data["user1_id"])}
+        )
+        test("search with userId filter returns answer", "answer" in result_user_filter)
+
+        # Test 3: Search with date range filter
+        print("\n  Testing search with date filters...")
+        tomorrow = (datetime.now() + timedelta(days=1)).strftime("%Y-%m-%d")
+        result_date_filter = await memory_search(
+            project_id=test_data["project_id"],
+            query="feature implementation",
+            filters={
+                "dateFrom": (datetime.now() - timedelta(days=2)).strftime("%Y-%m-%d"),
+                "dateTo": tomorrow
+            }
+        )
+        test("search with date filter returns answer", "answer" in result_date_filter)
+
+        # Test 4: Search with combined filters
+        print("\n  Testing search with combined filters...")
+        result_combined = await memory_search(
+            project_id=test_data["project_id"],
+            query="feature",
+            filters={
+                "userId": str(test_data["user1_id"]),
+                "dateFrom": (datetime.now() - timedelta(days=2)).strftime("%Y-%m-%d")
+            }
+        )
+        test("search with combined filters returns answer", "answer" in result_combined)
+
+        print("\n  Filter wiring tests passed!")
+
+    except Exception as e:
+        test("memory_search filters (API required)", False, str(e))
+
+
+def cleanup_test_data(test_data):
+    """Clean up test data."""
+    try:
+        delete_by_project(test_data["project_id"])
+    except:
+        pass
+
+
+async def main():
+    print("=" * 60)
+    print("  SMART QUERY TEST SUITE")
+    print("=" * 60)
+
+    # Initialize
+    print("\nInitializing database and vectorstore...")
+    init_db()
+    init_vectorstore()
+
+    # Setup test data
+    print("Setting up test data...")
+    test_data = setup_test_data()
+    print(f"  Project ID: {test_data['project_id']}")
+    print(f"  User 1: {test_data['user1_name']} ({test_data['user1_id']})")
+    print(f"  User 2: {test_data['user2_name']} ({test_data['user2_id']})")
+
+    try:
+        # Run tests
+        test_tool_functions(test_data)
+        test_extract_sources()
+        test_query_context()
+        test_user_resolution(test_data)  # New: duplicate name handling tests
+
+        # API-dependent tests (will fail gracefully without API key)
+        await test_semantic_search_tool(test_data)
+        await test_memory_search_filters(test_data)  # New: filter wiring tests
+        await test_full_smart_query(test_data)
+
+    finally:
+        # Cleanup
+        print("\nCleaning up test data...")
+        cleanup_test_data(test_data)
+
+    # Results
+    print("\n" + "=" * 60)
+    print(f"  RESULTS: {passed} passed, {failed} failed")
+    print("=" * 60)
+
+    if failed > 0:
+        print("\nNote: Some tests require GEMINI_API_KEY to be set.")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

backend/tests/test_tools.py

@@ -0,0 +1,100 @@
+"""Test script to verify MCP tools work correctly."""
+
+import sys
+sys.path.insert(0, '.')
+
+from app.database import init_db, SessionLocal
+from app.models import User, generate_user_id
+from app.tools.projects import create_project, list_projects, join_project
+from app.tools.tasks import create_task, list_tasks, list_activity
+
+
+def create_test_user(first_name: str, last_name: str) -> str:
+    """Create a test user and return their ID."""
+    db = SessionLocal()
+    try:
+        user_id = generate_user_id(first_name)
+        user = User(id=user_id, first_name=first_name, last_name=last_name)
+        db.add(user)
+        db.commit()
+        return user.id
+    finally:
+        db.close()
+
+
+def main():
+    # Initialize database
+    print("Initializing database...")
+    init_db()
+    
+    # Create test users
+    print("\n1. Creating test users...")
+    user1_id = create_test_user("Alice", "Developer")
+    user2_id = create_test_user("Bob", "Engineer")
+    print(f"   Created User 1: {user1_id}")
+    print(f"   Created User 2: {user2_id}")
+    
+    # Test create_project
+    print("\n2. Testing create_project...")
+    project = create_project(
+        name="AI Memory System",
+        description="Building a shared AI memory for dev teams",
+        user_id=user1_id
+    )
+    print(f"   Created project: {project}")
+    project_id = project["id"]
+    
+    # Test list_projects
+    print("\n3. Testing list_projects...")
+    projects = list_projects(user_id=user1_id)
+    print(f"   User 1's projects: {projects}")
+    
+    # Test join_project
+    print("\n4. Testing join_project...")
+    join_result = join_project(project_id=project_id, user_id=user2_id)
+    print(f"   Join result: {join_result}")
+    
+    # Verify User 2 now sees the project
+    projects2 = list_projects(user_id=user2_id)
+    print(f"   User 2's projects: {projects2}")
+    
+    # Test create_task
+    print("\n5. Testing create_task...")
+    task1 = create_task(
+        project_id=project_id,
+        title="Set up database schema",
+        description="Create SQLAlchemy models for all entities",
+        assigned_to=user1_id
+    )
+    print(f"   Created task 1: {task1}")
+    
+    task2 = create_task(
+        project_id=project_id,
+        title="Implement MCP server",
+        description="Set up MCP server with tool definitions"
+    )
+    print(f"   Created task 2: {task2}")
+    
+    # Test list_tasks
+    print("\n6. Testing list_tasks...")
+    tasks = list_tasks(project_id=project_id)
+    print(f"   All tasks: {tasks}")
+    
+    # Test list_tasks with status filter
+    print("\n7. Testing list_tasks with status filter...")
+    todo_tasks = list_tasks(project_id=project_id, status="todo")
+    print(f"   Todo tasks: {todo_tasks}")
+    
+    # Test list_activity (should be empty initially)
+    print("\n8. Testing list_activity...")
+    activity = list_activity(project_id=project_id)
+    print(f"   Activity (empty expected): {activity}")
+    
+    print("\n✅ All Foundation Layer tests passed!")
+    print("\nReady for Dev B to implement:")
+    print("   - complete_task (with LLM documentation generation)")
+    print("   - memory_search (with vector search)")
+
+
+if __name__ == "__main__":
+    main()

backend/tests/test_user_models.py

@@ -0,0 +1,189 @@
+"""Unit tests for models module."""
+
+import pytest
+from datetime import datetime
+
+from app.database import SessionLocal, init_db
+from app.models import (
+    User, Project, Task, LogEntry, ProjectMembership,
+    generate_uuid, generate_user_id,
+    TaskStatus, ActorType, ActionType
+)
+
+
+class TestGenerateUserId:
+    """Test user ID generation function."""
+
+    def test_generate_user_id_format(self):
+        """Test generated ID has correct format: 3 letters + 4 digits."""
+        user_id = generate_user_id("Alice")
+        
+        assert len(user_id) == 7
+        assert user_id[:3] == "ali"  # First 3 letters lowercase
+        assert user_id[3:].isdigit()  # Last 4 are digits
+
+    def test_generate_user_id_lowercase(self):
+        """Test first name is lowercased."""
+        user_id = generate_user_id("JOHN")
+        assert user_id[:3] == "joh"
+
+    def test_generate_user_id_short_name(self):
+        """Test with name shorter than 3 characters."""
+        user_id = generate_user_id("Jo")
+        assert user_id[:2] == "jo"
+        assert len(user_id) == 6  # 2 letters + 4 digits
+
+    def test_generate_user_id_uniqueness(self):
+        """Test that multiple calls generate different IDs."""
+        ids = [generate_user_id("Test") for _ in range(10)]
+        # With 4 random digits, collisions are unlikely
+        assert len(set(ids)) > 5  # At least some should be unique
+
+    def test_generate_user_id_example(self):
+        """Test example from requirements: Amal -> ama + 4 digits."""
+        user_id = generate_user_id("Amal")
+        assert user_id.startswith("ama")
+        assert len(user_id) == 7
+
+
+class TestGenerateUuid:
+    """Test UUID generation function."""
+
+    def test_generate_uuid_format(self):
+        """Test UUID is valid format."""
+        uuid = generate_uuid()
+        assert len(uuid) == 36  # Standard UUID length with hyphens
+        assert uuid.count("-") == 4
+
+    def test_generate_uuid_uniqueness(self):
+        """Test UUIDs are unique."""
+        uuids = [generate_uuid() for _ in range(100)]
+        assert len(set(uuids)) == 100
+
+
+class TestUserModel:
+    """Test User model."""
+
+    def test_user_creation(self, db_session):
+        """Test creating a user with new fields."""
+        user_id = generate_user_id("Test")
+        user = User(
+            id=user_id,
+            first_name="Test",
+            last_name="User"
+        )
+        db_session.add(user)
+        db_session.commit()
+        
+        assert user.id == user_id
+        assert user.first_name == "Test"
+        assert user.last_name == "User"
+        assert user.created_at is not None
+
+    def test_user_name_property(self, db_session):
+        """Test the name property returns full name."""
+        user_id = generate_user_id("John")
+        user = User(id=user_id, first_name="John", last_name="Doe")
+        db_session.add(user)
+        db_session.commit()
+        
+        assert user.name == "John Doe"
+
+    def test_user_optional_avatar(self, db_session):
+        """Test avatar_url is optional."""
+        user_id = generate_user_id("Jane")
+        user = User(id=user_id, first_name="Jane", last_name="Smith")
+        db_session.add(user)
+        db_session.commit()
+        
+        assert user.avatar_url is None
+
+    def test_user_with_avatar(self, db_session):
+        """Test user with avatar URL."""
+        user_id = generate_user_id("Bob")
+        user = User(
+            id=user_id,
+            first_name="Bob",
+            last_name="Builder",
+            avatar_url="https://example.com/avatar.jpg"
+        )
+        db_session.add(user)
+        db_session.commit()
+        
+        assert user.avatar_url == "https://example.com/avatar.jpg"
+
+
+class TestProjectModel:
+    """Test Project model."""
+
+    def test_project_with_name_as_id(self, db_session, create_user):
+        """Test creating project with name as ID."""
+        user = create_user("Owner", "Test")
+        
+        project = Project(
+            id="myproject",  # Name used as ID
+            name="myproject",
+            description="Test project",
+            created_by=user.id
+        )
+        db_session.add(project)
+        db_session.commit()
+        
+        assert project.id == "myproject"
+        assert project.name == "myproject"
+
+    def test_project_id_uniqueness(self, db_session, create_user):
+        """Test that duplicate project IDs fail."""
+        user = create_user("Owner", "Test")
+        
+        project1 = Project(id="unique", name="unique", description="First", created_by=user.id)
+        db_session.add(project1)
+        db_session.commit()
+        
+        project2 = Project(id="unique", name="unique", description="Second", created_by=user.id)
+        db_session.add(project2)
+        
+        with pytest.raises(Exception):  # IntegrityError
+            db_session.commit()
+
+
+class TestTaskModel:
+    """Test Task model."""
+
+    def test_task_status_enum(self):
+        """Test TaskStatus enum values."""
+        assert TaskStatus.todo.value == "todo"
+        assert TaskStatus.in_progress.value == "in_progress"
+        assert TaskStatus.done.value == "done"
+
+    def test_task_default_status(self, db_session, create_user):
+        """Test task defaults to 'todo' status."""
+        user = create_user("Dev", "Test")
+        project = Project(id="taskproj", name="taskproj", description="Test", created_by=user.id)
+        db_session.add(project)
+        db_session.commit()
+        
+        task = Task(
+            project_id=project.id,
+            title="Test Task",
+            description="Test description"
+        )
+        db_session.add(task)
+        db_session.commit()
+        
+        assert task.status == TaskStatus.todo
+
+
+class TestEnums:
+    """Test enum definitions."""
+
+    def test_actor_type_enum(self):
+        """Test ActorType enum."""
+        assert ActorType.human.value == "human"
+        assert ActorType.agent.value == "agent"
+
+    def test_action_type_enum(self):
+        """Test ActionType enum."""
+        assert ActionType.task_completed.value == "task_completed"
+        assert ActionType.doc_generated.value == "doc_generated"
+        assert ActionType.query_answered.value == "query_answered"

backend/tests/test_vector_query.py

@@ -0,0 +1,410 @@
+"""
+Vector Query End-to-End Test - Run with: python test_vector_query.py
+
+This test:
+1. Creates a project with users, tasks, and log entries
+2. Generates embeddings and stores them in the vector store
+3. Tests various smart queries against the populated data
+
+Requires GEMINI_API_KEY environment variable.
+"""
+
+import asyncio
+import sys
+from datetime import datetime, timedelta, timezone
+
+sys.path.insert(0, '.')
+
+from sqlalchemy import text
+from app.database import init_db, SessionLocal
+from app.models import User, Task, LogEntry, TaskStatus, ActorType, ActionType, ProjectMembership
+from app.vectorstore import init_vectorstore, add_embedding, delete_by_project, count_embeddings
+from app.llm import get_embedding
+
+# Test project ID (fixed for easy cleanup)
+TEST_PROJECT_ID = "vector-test-project-001"
+
+
+async def setup_test_environment():
+    """Create test users, project, tasks, and log entries with embeddings."""
+    print("\n" + "=" * 60)
+    print("  SETTING UP TEST ENVIRONMENT")
+    print("=" * 60)
+
+    init_db()
+    init_vectorstore()
+
+    # Clean up any previous test data
+    print("\n[1] Cleaning up previous test data...")
+    delete_by_project(TEST_PROJECT_ID)
+
+    db = SessionLocal()
+    try:
+        # Delete existing test project and related data
+        db.execute(text(f"DELETE FROM log_entries WHERE project_id = '{TEST_PROJECT_ID}'"))
+        db.execute(text(f"DELETE FROM tasks WHERE project_id = '{TEST_PROJECT_ID}'"))
+        db.execute(text(f"DELETE FROM project_memberships WHERE project_id = '{TEST_PROJECT_ID}'"))
+        db.execute(text(f"DELETE FROM projects WHERE id = '{TEST_PROJECT_ID}'"))
+        db.commit()
+    except:
+        db.rollback()
+    finally:
+        db.close()
+
+    db = SessionLocal()
+    try:
+        # Create users
+        print("\n[2] Creating test users...")
+        user_alice = User(
+            id="user-alice-001",
+            first_name="Alice",
+            last_name="Developer"
+        )
+        user_bob = User(
+            id="user-bob-001",
+            first_name="Bob",
+            last_name="Engineer"
+        )
+        db.add(user_alice)
+        db.add(user_bob)
+        db.commit()
+        print(f"   Created: {user_alice.name} ({user_alice.id})")
+        print(f"   Created: {user_bob.name} ({user_bob.id})")
+
+        # Create project
+        print("\n[3] Creating test project...")
+        from app.models import Project
+        project = Project(
+            id=TEST_PROJECT_ID,
+            name="E-Commerce Platform",
+            description="Building an online shopping platform",
+            created_by=user_alice.id
+        )
+        db.add(project)
+        db.commit()
+        print(f"   Created: {project.name} ({project.id})")
+
+        # Add memberships
+        print("\n[4] Adding project memberships...")
+        membership1 = ProjectMembership(project_id=TEST_PROJECT_ID, user_id=user_alice.id, role="owner")
+        membership2 = ProjectMembership(project_id=TEST_PROJECT_ID, user_id=user_bob.id, role="member")
+        db.add(membership1)
+        db.add(membership2)
+        db.commit()
+        print(f"   Added Alice as owner")
+        print(f"   Added Bob as member")
+
+        # Create tasks
+        print("\n[5] Creating tasks...")
+        tasks_data = [
+            {
+                "id": "task-auth-001",
+                "title": "Implement User Authentication",
+                "description": "Build JWT-based login and registration system",
+                "assigned_to": user_alice.id,
+                "status": TaskStatus.done,
+                "completed_at": datetime.now(timezone.utc) - timedelta(days=2)
+            },
+            {
+                "id": "task-cart-001",
+                "title": "Build Shopping Cart",
+                "description": "Create cart functionality with add/remove items",
+                "assigned_to": user_bob.id,
+                "status": TaskStatus.done,
+                "completed_at": datetime.now(timezone.utc) - timedelta(days=1)
+            },
+            {
+                "id": "task-checkout-001",
+                "title": "Implement Checkout Flow",
+                "description": "Payment integration and order processing",
+                "assigned_to": user_alice.id,
+                "status": TaskStatus.in_progress
+            },
+            {
+                "id": "task-tests-001",
+                "title": "Write Unit Tests",
+                "description": "Create test coverage for auth and cart modules",
+                "assigned_to": user_bob.id,
+                "status": TaskStatus.done,
+                "completed_at": datetime.now(timezone.utc) - timedelta(hours=5)
+            }
+        ]
+
+        for t in tasks_data:
+            task = Task(
+                id=t["id"],
+                project_id=TEST_PROJECT_ID,
+                title=t["title"],
+                description=t["description"],
+                assigned_to=t["assigned_to"],
+                status=t["status"],
+                completed_at=t.get("completed_at")
+            )
+            db.add(task)
+            print(f"   Created: {task.title} ({task.status.value})")
+        db.commit()
+
+        # Create log entries with embeddings
+        print("\n[6] Creating log entries and embeddings...")
+        log_entries_data = [
+            {
+                "id": "log-auth-001",
+                "task_id": "task-auth-001",
+                "user_id": user_alice.id,
+                "raw_input": "Implemented JWT authentication with access and refresh tokens. Added password hashing using bcrypt.",
+                "generated_doc": "Authentication system implemented using JWT tokens. The system generates short-lived access tokens (15 min) and long-lived refresh tokens (7 days). Passwords are securely hashed using bcrypt with salt rounds of 12. Login endpoint validates credentials and returns both tokens. Refresh endpoint allows obtaining new access tokens.",
+                "tags": ["auth", "jwt", "security", "bcrypt"],
+                "hours_ago": 48
+            },
+            {
+                "id": "log-cart-001",
+                "task_id": "task-cart-001",
+                "user_id": user_bob.id,
+                "raw_input": "Built shopping cart with Redux state management. Added add/remove/update quantity functions.",
+                "generated_doc": "Shopping cart functionality using Redux for state management. Cart persists to localStorage. Features include: adding products with quantities, removing items, updating quantities, calculating totals with tax, and applying discount codes. Cart state syncs across browser tabs.",
+                "tags": ["cart", "redux", "frontend", "state"],
+                "hours_ago": 24
+            },
+            {
+                "id": "log-api-001",
+                "task_id": "task-auth-001",
+                "user_id": user_alice.id,
+                "raw_input": "Created REST API endpoints for user profile management.",
+                "generated_doc": "REST API endpoints for user profiles. GET /api/users/me returns current user. PUT /api/users/me updates profile fields (name, avatar, preferences). Password change requires current password verification. All endpoints require valid JWT in Authorization header.",
+                "tags": ["api", "rest", "profile", "user"],
+                "hours_ago": 36
+            },
+            {
+                "id": "log-tests-001",
+                "task_id": "task-tests-001",
+                "user_id": user_bob.id,
+                "raw_input": "Wrote unit tests for authentication and cart modules. Achieved 85% coverage.",
+                "generated_doc": "Unit test suite for authentication and cart modules. Auth tests cover: login success/failure, token refresh, password validation, protected routes. Cart tests cover: add/remove items, quantity updates, price calculations, discount application. Using Jest with React Testing Library. Coverage at 85%.",
+                "tags": ["tests", "jest", "coverage", "unit-tests"],
+                "hours_ago": 5
+            },
+            {
+                "id": "log-today-001",
+                "task_id": "task-checkout-001",
+                "user_id": user_alice.id,
+                "raw_input": "Started working on Stripe payment integration for checkout.",
+                "generated_doc": "Began Stripe payment integration. Set up Stripe SDK and test account. Created payment intent endpoint. Working on client-side card element component. Next: handle payment confirmation and webhooks for order updates.",
+                "tags": ["checkout", "stripe", "payments", "integration"],
+                "hours_ago": 2
+            }
+        ]
+
+        for entry_data in log_entries_data:
+            # Create log entry
+            entry = LogEntry(
+                id=entry_data["id"],
+                project_id=TEST_PROJECT_ID,
+                task_id=entry_data["task_id"],
+                user_id=entry_data["user_id"],
+                actor_type=ActorType.human,
+                action_type=ActionType.task_completed,
+                raw_input=entry_data["raw_input"],
+                generated_doc=entry_data["generated_doc"],
+                tags=entry_data["tags"],
+                created_at=datetime.now(timezone.utc) - timedelta(hours=entry_data["hours_ago"])
+            )
+            db.add(entry)
+            db.commit()
+
+            # Create embedding
+            text_to_embed = f"""
+            Task: {entry_data['raw_input']}
+            Documentation: {entry_data['generated_doc']}
+            Tags: {', '.join(entry_data['tags'])}
+            """
+            embedding = await get_embedding(text_to_embed)
+            add_embedding(
+                log_entry_id=entry_data["id"],
+                text=text_to_embed,
+                embedding=embedding,
+                metadata={
+                    "project_id": TEST_PROJECT_ID,
+                    "user_id": entry_data["user_id"],
+                    "task_id": entry_data["task_id"],
+                    "created_at": entry.created_at.isoformat()
+                }
+            )
+            print(f"   Created: {entry_data['id']} + embedding")
+
+        db.commit()
+
+        # Verify embeddings
+        embed_count = count_embeddings(TEST_PROJECT_ID)
+        print(f"\n   Total embeddings stored: {embed_count}")
+
+        return {
+            "project_id": TEST_PROJECT_ID,
+            "user_alice_id": user_alice.id,
+            "user_bob_id": user_bob.id
+        }
+
+    finally:
+        db.close()
+
+
+async def run_test_queries(test_data):
+    """Run various queries against the test data."""
+    print("\n" + "=" * 60)
+    print("  RUNNING TEST QUERIES")
+    print("=" * 60)
+
+    from app.smart_query import smart_query
+
+    queries = [
+        {
+            "query": "What did I do yesterday?",
+            "user_id": test_data["user_alice_id"],
+            "description": "User activity query (yesterday)"
+        },
+        {
+            "query": "What did Bob work on?",
+            "user_id": test_data["user_alice_id"],
+            "description": "Other user's activity"
+        },
+        {
+            "query": "How does authentication work?",
+            "user_id": test_data["user_alice_id"],
+            "description": "Semantic search for auth"
+        },
+        {
+            "query": "Status of the checkout task?",
+            "user_id": test_data["user_alice_id"],
+            "description": "Task status query"
+        },
+        {
+            "query": "Did Bob complete the shopping cart?",
+            "user_id": test_data["user_alice_id"],
+            "description": "Task completion check"
+        },
+        {
+            "query": "What tests were written?",
+            "user_id": test_data["user_bob_id"],
+            "description": "Semantic search for tests"
+        },
+        {
+            "query": "What payment system is being used?",
+            "user_id": test_data["user_alice_id"],
+            "description": "Semantic search for payments"
+        },
+        {
+            "query": "Who are the team members?",
+            "user_id": test_data["user_alice_id"],
+            "description": "List users query"
+        }
+    ]
+
+    results = []
+    for i, q in enumerate(queries, 1):
+        print(f"\n[Query {i}] {q['description']}")
+        print(f"   Question: \"{q['query']}\"")
+        print(f"   User: {q['user_id']}")
+
+        try:
+            result = await smart_query(
+                project_id=test_data["project_id"],
+                query=q["query"],
+                current_user_id=q["user_id"],
+                current_datetime=datetime.now(timezone.utc).isoformat()
+            )
+
+            print(f"\n   Tools Used: {result.get('tools_used', [])}")
+            print(f"\n   Answer:")
+            answer = result.get("answer", "No answer")
+            # Print answer with word wrap
+            for line in answer.split('\n'):
+                print(f"   {line}")
+
+            if result.get("sources"):
+                print(f"\n   Sources ({len(result['sources'])}):")
+                for src in result["sources"][:3]:
+                    print(f"     - [{src.get('type', 'unknown')}] {src.get('summary', 'No summary')[:60]}...")
+
+            results.append({"query": q, "result": result, "success": True})
+
+        except Exception as e:
+            print(f"\n   ERROR: {str(e)}")
+            results.append({"query": q, "error": str(e), "success": False})
+
+        print("\n" + "-" * 60)
+
+    return results
+
+
+def print_summary(results):
+    """Print test summary."""
+    print("\n" + "=" * 60)
+    print("  TEST SUMMARY")
+    print("=" * 60)
+
+    successful = sum(1 for r in results if r["success"])
+    failed = len(results) - successful
+
+    print(f"\n  Total queries: {len(results)}")
+    print(f"  Successful: {successful}")
+    print(f"  Failed: {failed}")
+
+    if failed > 0:
+        print("\n  Failed queries:")
+        for r in results:
+            if not r["success"]:
+                print(f"    - {r['query']['description']}: {r.get('error', 'Unknown error')}")
+
+
+def cleanup():
+    """Clean up test data."""
+    print("\n[CLEANUP] Removing test data...")
+    try:
+        delete_by_project(TEST_PROJECT_ID)
+        db = SessionLocal()
+        try:
+            db.execute(text(f"DELETE FROM log_entries WHERE project_id = '{TEST_PROJECT_ID}'"))
+            db.execute(text(f"DELETE FROM tasks WHERE project_id = '{TEST_PROJECT_ID}'"))
+            db.execute(text(f"DELETE FROM project_memberships WHERE project_id = '{TEST_PROJECT_ID}'"))
+            db.execute(text(f"DELETE FROM projects WHERE id = '{TEST_PROJECT_ID}'"))
+            db.commit()
+            print("   Cleanup complete.")
+        finally:
+            db.close()
+    except Exception as e:
+        print(f"   Cleanup error: {e}")
+
+
+async def main():
+    print("=" * 60)
+    print("  VECTOR QUERY END-TO-END TEST")
+    print("  Tests smart_query against populated vector store")
+    print("=" * 60)
+
+    try:
+        # Setup
+        test_data = await setup_test_environment()
+
+        # Run queries
+        results = await run_test_queries(test_data)
+
+        # Summary
+        print_summary(results)
+
+    except Exception as e:
+        print(f"\nFATAL ERROR: {e}")
+        import traceback
+        traceback.print_exc()
+
+    finally:
+        # Ask about cleanup
+        print("\n" + "=" * 60)
+        response = input("Clean up test data? (y/n): ").strip().lower()
+        if response == 'y':
+            cleanup()
+        else:
+            print(f"Test data retained. Project ID: {TEST_PROJECT_ID}")
+            print("Run cleanup manually or delete project from database.")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

docker-compose.yml

@@ -0,0 +1,30 @@
+services:
+  backend:
+    build: ./backend
+    container_name: pm-backend
+    ports:
+      - "8000:8000"
+    env_file: ./backend/.env
+    volumes:
+      - backend-data:/app/data
+    networks:
+      - pm-network
+    restart: unless-stopped
+
+  frontend:
+    build: ./frontend
+    container_name: pm-frontend
+    ports:
+      - "80:80"
+    depends_on:
+      - backend
+    networks:
+      - pm-network
+    restart: unless-stopped
+
+networks:
+  pm-network:
+    driver: bridge
+
+volumes:
+  backend-data: {}

frontend/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

frontend/Dockerfile

@@ -0,0 +1,32 @@
+# Frontend Dockerfile
+FROM node:20-alpine AS builder
+
+# Set working directory
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install dependencies
+RUN npm ci
+
+# Copy source code
+COPY . .
+
+# Build the application
+RUN npm run build
+
+# Production stage
+FROM nginx:alpine
+
+# Copy built files to nginx
+COPY --from=builder /app/dist /usr/share/nginx/html
+
+# Copy nginx configuration
+COPY nginx.conf /etc/nginx/conf.d/default.conf
+
+# Expose port
+EXPOSE 80
+
+# Start nginx
+CMD ["nginx", "-g", "daemon off;"]

frontend/README.md

@@ -0,0 +1,73 @@
+# React + TypeScript + Vite
+
+This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+
+Currently, two official plugins are available:
+
+- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
+- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+
+## React Compiler
+
+The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+
+## Expanding the ESLint configuration
+
+If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+
+```js
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+
+      // Remove tseslint.configs.recommended and replace with this
+      tseslint.configs.recommendedTypeChecked,
+      // Alternatively, use this for stricter rules
+      tseslint.configs.strictTypeChecked,
+      // Optionally, add this for stylistic rules
+      tseslint.configs.stylisticTypeChecked,
+
+      // Other configs...
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```
+
+You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
+
+```js
+// eslint.config.js
+import reactX from 'eslint-plugin-react-x'
+import reactDom from 'eslint-plugin-react-dom'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+      // Enable lint rules for React
+      reactX.configs['recommended-typescript'],
+      // Enable lint rules for React DOM
+      reactDom.configs.recommended,
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```

frontend/eslint.config.js

@@ -0,0 +1,23 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import tseslint from 'typescript-eslint'
+import { defineConfig, globalIgnores } from 'eslint/config'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      reactHooks.configs.flat.recommended,
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+  },
+])

frontend/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>frontend</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

frontend/nginx.conf

@@ -0,0 +1,33 @@
+server {
+    listen 80;
+    server_name localhost;
+    
+    root /usr/share/nginx/html;
+    index index.html;
+    
+    # Frontend routes
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+    
+    # API proxy
+    location /api {
+        proxy_pass http://backend:8000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        proxy_cache_bypass $http_upgrade;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+    
+    # WebSocket support (if needed)
+    location /ws {
+        proxy_pass http://backend:8000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+    }
+}

frontend/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "frontend",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "lint": "eslint .",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "react-markdown": "^10.1.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@tailwindcss/vite": "^4.1.17",
+    "@types/node": "^24.10.1",
+    "@types/react": "^19.2.5",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.1",
+    "eslint": "^9.39.1",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.4.24",
+    "globals": "^16.5.0",
+    "tailwindcss": "^4.1.17",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.46.4",
+    "vite": "^7.2.4"
+  }
+}

frontend/src/App.tsx

@@ -0,0 +1,107 @@
+import { useState, useEffect } from 'react';
+import { UserProvider, useUser } from './context/UserContext';
+import { ProjectProvider, useProject } from './context/ProjectContext';
+import { LoginPage } from './pages/LoginPage';
+import { ProjectSelectionPage } from './pages/ProjectSelectionPage';
+import { TaskSetupPage } from './pages/TaskSetupPage';
+import { ActivityPage } from './pages/ActivityPage';
+import { TaskSolverPage } from './pages/TaskSolverPage';
+import { api } from './api/client';
+import type { Task } from './types';
+
+function AppContent() {
+  const { user, isLoading: userLoading } = useUser();
+  const { currentProject } = useProject();
+  const [taskSetupComplete, setTaskSetupComplete] = useState<boolean | null>(null);
+  const [checkingTasks, setCheckingTasks] = useState(false);
+  const [activeTask, setActiveTask] = useState<Task | null>(null);
+
+  // Check if project has tasks (for owner flow)
+  useEffect(() => {
+    if (!currentProject || !user) {
+      setTaskSetupComplete(null);
+      return;
+    }
+
+    // Members skip task setup
+    if (currentProject.role !== 'owner') {
+      setTaskSetupComplete(true);
+      return;
+    }
+
+    // Owners: check if tasks exist
+    const checkTasks = async () => {
+      setCheckingTasks(true);
+      try {
+        const result = await api.listTasks(currentProject.id);
+        setTaskSetupComplete((result.tasks?.length || 0) > 0);
+      } catch {
+        // If error, assume setup not complete
+        setTaskSetupComplete(false);
+      } finally {
+        setCheckingTasks(false);
+      }
+    };
+
+    checkTasks();
+  }, [currentProject, user]);
+
+  // Show loading state while checking for stored user
+  if (userLoading) {
+    return (
+      <div className="min-h-screen bg-gradient-to-br from-slate-900 via-purple-900 to-slate-900 flex items-center justify-center">
+        <div className="text-white text-xl">Loading...</div>
+      </div>
+    );
+  }
+
+  // No user → Login
+  if (!user) {
+    return <LoginPage />;
+  }
+
+  // User but no project → Project Selection
+  if (!currentProject) {
+    return <ProjectSelectionPage />;
+  }
+
+  // Checking tasks status
+  if (checkingTasks || taskSetupComplete === null) {
+    return (
+      <div className="min-h-screen bg-gradient-to-br from-slate-900 via-purple-900 to-slate-900 flex items-center justify-center">
+        <div className="text-white text-xl">Loading project...</div>
+      </div>
+    );
+  }
+
+  // Owner + no tasks → Task Setup
+  if (currentProject.role === 'owner' && !taskSetupComplete) {
+    return <TaskSetupPage onComplete={() => setTaskSetupComplete(true)} />;
+  }
+
+  // Active task → Task Solver Page
+  if (activeTask) {
+    return (
+      <TaskSolverPage
+        task={activeTask}
+        onBack={() => setActiveTask(null)}
+        onTaskCompleted={() => setActiveTask(null)}
+      />
+    );
+  }
+
+  // User + Project + Tasks → Activity Page
+  return <ActivityPage onStartTask={setActiveTask} />;
+}
+
+function App() {
+  return (
+    <UserProvider>
+      <ProjectProvider>
+        <AppContent />
+      </ProjectProvider>
+    </UserProvider>
+  );
+}
+
+export default App;

frontend/src/api/client.ts

@@ -0,0 +1,146 @@
+import type { User, UserCreate, Project, ProjectCreate, ProjectsResponse, ProjectAvailability, Task, TaskCreate, TasksResponse, MembersResponse, ActivityResponse } from '../types';
+
+const API_BASE = 'http://localhost:8000/api';
+
+class ApiClient {
+  private async request<T>(endpoint: string, options?: RequestInit): Promise<T> {
+    const response = await fetch(`${API_BASE}${endpoint}`, {
+      headers: {
+        'Content-Type': 'application/json',
+        ...options?.headers,
+      },
+      ...options,
+    });
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({ error: 'Request failed' }));
+      throw new Error(error.error || error.detail || 'Request failed');
+    }
+
+    return response.json();
+  }
+
+  // User endpoints
+  async createUser(data: UserCreate): Promise<User> {
+    return this.request<User>('/users', {
+      method: 'POST',
+      body: JSON.stringify(data),
+    });
+  }
+
+  async getUser(userId: string): Promise<User> {
+    return this.request<User>(`/users/${userId}`);
+  }
+
+  async listUsers(): Promise<User[]> {
+    return this.request<User[]>('/users');
+  }
+
+  // Project endpoints
+  async checkProjectAvailability(projectId: string): Promise<ProjectAvailability> {
+    return this.request<ProjectAvailability>(`/projects/check/${projectId}`);
+  }
+
+  async listProjects(userId: string): Promise<ProjectsResponse> {
+    return this.request<ProjectsResponse>(`/projects?userId=${userId}`);
+  }
+
+  async createProject(data: ProjectCreate): Promise<Project> {
+    return this.request<Project>('/projects', {
+      method: 'POST',
+      body: JSON.stringify(data),
+    });
+  }
+
+  async joinProject(projectId: string, userId: string): Promise<{ message: string; project_id: string; role: string }> {
+    return this.request(`/projects/${projectId}/join`, {
+      method: 'POST',
+      body: JSON.stringify({ userId }),
+    });
+  }
+
+  // Task endpoints
+  async listTasks(projectId: string, status?: string): Promise<TasksResponse> {
+    const query = status ? `?status=${status}` : '';
+    return this.request<TasksResponse>(`/projects/${projectId}/tasks${query}`);
+  }
+
+  async createTask(projectId: string, data: TaskCreate): Promise<Task> {
+    return this.request<Task>(`/projects/${projectId}/tasks`, {
+      method: 'POST',
+      body: JSON.stringify(data),
+    });
+  }
+
+  async generateTasks(projectId: string, count = 50): Promise<{ tasks: { title: string; description: string }[] }> {
+    return this.request(`/projects/${projectId}/tasks/generate`, {
+      method: 'POST',
+      body: JSON.stringify({ count: Math.min(count, 50) }),
+    });
+  }
+
+  async completeTask(taskId: string, data: { userId: string; whatIDid: string; codeSnippet?: string }) {
+    return this.request(`/tasks/${taskId}/complete`, {
+      method: 'POST',
+      body: JSON.stringify(data),
+    });
+  }
+
+  async updateTaskStatus(taskId: string, status: 'todo' | 'in_progress' | 'done'): Promise<Task> {
+    return this.request<Task>(`/tasks/${taskId}/status`, {
+      method: 'PATCH',
+      body: JSON.stringify({ status }),
+    });
+  }
+
+  // Members
+  async getMembers(projectId: string): Promise<MembersResponse> {
+    return this.request<MembersResponse>(`/projects/${projectId}/members`);
+  }
+
+  // Search & Activity
+  async searchProject(projectId: string, query: string, filters?: { userId?: string; dateFrom?: string; dateTo?: string }) {
+    return this.request(`/projects/${projectId}/search`, {
+      method: 'POST',
+      body: JSON.stringify({ query, filters }),
+    });
+  }
+
+  async getActivity(projectId: string, limit = 20): Promise<ActivityResponse> {
+    return this.request<ActivityResponse>(`/projects/${projectId}/activity?limit=${limit}`);
+  }
+
+  // Smart Query
+  async smartQuery(projectId: string, query: string, currentUserId: string) {
+    return this.request(`/projects/${projectId}/smart-query`, {
+      method: 'POST',
+      body: JSON.stringify({
+        query,
+        currentUserId,
+        currentDatetime: new Date().toISOString(),
+      }),
+    });
+  }
+
+  // Task Chat (Agent)
+  async taskChat(
+    projectId: string,
+    taskId: string,
+    userId: string,
+    message: string,
+    history: { role: string; content: string }[]
+  ): Promise<{ message: string; taskCompleted?: boolean; taskStatus?: string }> {
+    return this.request(`/tasks/${taskId}/chat`, {
+      method: 'POST',
+      body: JSON.stringify({
+        projectId,
+        userId,
+        message,
+        history,
+        currentDatetime: new Date().toISOString(),
+      }),
+    });
+  }
+}
+
+export const api = new ApiClient();

frontend/src/components/TaskCompleteModal.tsx

@@ -0,0 +1,109 @@
+import { useState } from 'react';
+import type { Task } from '../types';
+
+interface TaskCompleteModalProps {
+  task: Task;
+  onClose: () => void;
+  onComplete: (taskId: string, whatIDid: string, codeSnippet?: string) => Promise<void>;
+}
+
+export function TaskCompleteModal({ task, onClose, onComplete }: TaskCompleteModalProps) {
+  const [whatIDid, setWhatIDid] = useState('');
+  const [codeSnippet, setCodeSnippet] = useState('');
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [error, setError] = useState('');
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    if (!whatIDid.trim()) {
+      setError('Please describe what you did');
+      return;
+    }
+
+    setIsSubmitting(true);
+    setError('');
+
+    try {
+      await onComplete(task.id, whatIDid.trim(), codeSnippet.trim() || undefined);
+      onClose();
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Failed to complete task');
+    } finally {
+      setIsSubmitting(false);
+    }
+  };
+
+  return (
+    <div className="fixed inset-0 z-50 flex items-center justify-center">
+      {/* Backdrop */}
+      <div
+        className="absolute inset-0 bg-black/60 backdrop-blur-sm"
+        onClick={onClose}
+      />
+
+      {/* Modal */}
+      <div className="relative bg-slate-900 border border-white/20 rounded-xl w-full max-w-lg mx-4 shadow-2xl">
+        {/* Header */}
+        <div className="px-6 py-4 border-b border-white/10">
+          <h2 className="text-xl font-bold text-white">Complete Task</h2>
+          <p className="text-purple-300/70 text-sm mt-1 truncate">{task.title}</p>
+        </div>
+
+        {/* Form */}
+        <form onSubmit={handleSubmit} className="p-6 space-y-4">
+          {error && (
+            <div className="p-3 bg-red-500/20 border border-red-500/50 rounded-lg text-red-200 text-sm">
+              {error}
+            </div>
+          )}
+
+          <div>
+            <label className="block text-white text-sm font-medium mb-2">
+              What did you do? <span className="text-red-400">*</span>
+            </label>
+            <textarea
+              value={whatIDid}
+              onChange={(e) => setWhatIDid(e.target.value)}
+              placeholder="Describe what you accomplished..."
+              rows={3}
+              className="w-full px-4 py-3 bg-white/5 border border-white/10 rounded-lg text-white placeholder-white/40 focus:outline-none focus:ring-2 focus:ring-purple-500 resize-none"
+              autoFocus
+            />
+          </div>
+
+          <div>
+            <label className="block text-white text-sm font-medium mb-2">
+              Code snippet (optional)
+            </label>
+            <textarea
+              value={codeSnippet}
+              onChange={(e) => setCodeSnippet(e.target.value)}
+              placeholder="Paste any relevant code..."
+              rows={4}
+              className="w-full px-4 py-3 bg-white/5 border border-white/10 rounded-lg text-white placeholder-white/40 focus:outline-none focus:ring-2 focus:ring-purple-500 resize-none font-mono text-sm"
+            />
+          </div>
+
+          {/* Actions */}
+          <div className="flex gap-3 pt-2">
+            <button
+              type="button"
+              onClick={onClose}
+              disabled={isSubmitting}
+              className="flex-1 px-4 py-3 bg-white/10 hover:bg-white/20 text-white rounded-lg transition-all"
+            >
+              Cancel
+            </button>
+            <button
+              type="submit"
+              disabled={isSubmitting || !whatIDid.trim()}
+              className="flex-1 px-4 py-3 bg-green-600 hover:bg-green-700 disabled:bg-green-800 disabled:cursor-not-allowed text-white font-medium rounded-lg transition-all"
+            >
+              {isSubmitting ? 'Completing...' : 'Complete Task'}
+            </button>
+          </div>
+        </form>
+      </div>
+    </div>
+  );
+}

frontend/src/context/ProjectContext.tsx

@@ -0,0 +1,56 @@
+import { createContext, useContext, useState, useEffect, type ReactNode } from 'react';
+import type { Project } from '../types';
+
+interface ProjectContextType {
+  currentProject: Project | null;
+  setCurrentProject: (project: Project | null) => void;
+  clearProject: () => void;
+}
+
+const ProjectContext = createContext<ProjectContextType | null>(null);
+
+const PROJECT_STORAGE_KEY = 'project_memory_current_project';
+
+export function ProjectProvider({ children }: { children: ReactNode }) {
+  const [currentProject, setCurrentProjectState] = useState<Project | null>(null);
+
+  // Load from localStorage on mount
+  useEffect(() => {
+    const stored = localStorage.getItem(PROJECT_STORAGE_KEY);
+    if (stored) {
+      try {
+        setCurrentProjectState(JSON.parse(stored));
+      } catch {
+        localStorage.removeItem(PROJECT_STORAGE_KEY);
+      }
+    }
+  }, []);
+
+  const setCurrentProject = (project: Project | null) => {
+    setCurrentProjectState(project);
+    if (project) {
+      localStorage.setItem(PROJECT_STORAGE_KEY, JSON.stringify(project));
+    } else {
+      localStorage.removeItem(PROJECT_STORAGE_KEY);
+    }
+  };
+
+  const clearProject = () => {
+    setCurrentProjectState(null);
+    localStorage.removeItem(PROJECT_STORAGE_KEY);
+  };
+
+  return (
+    <ProjectContext.Provider value={{ currentProject, setCurrentProject, clearProject }}>
+      {children}
+    </ProjectContext.Provider>
+  );
+}
+
+export function useProject() {
+  const context = useContext(ProjectContext);
+  if (!context) {
+    throw new Error('useProject must be used within a ProjectProvider');
+  }
+  return context;
+}