deploy to hf space

.env.example

@@ -0,0 +1,9 @@
+# Gemini API key (required for repository analysis, chat, and semantic search)
+GEMINI_API_KEY=your_gemini_api_key_here
+
+# Optional: comma-separated CORS origins (default: *)
+# CORS_ORIGINS=http://localhost:5173,http://127.0.0.1:5173
+
+# Frontend (local dev) — leave empty to use Vite proxy
+# VITE_API_URL=
+# VITE_API_PROXY=http://localhost:8000

Dockerfile

@@ -0,0 +1,32 @@
+# --- Stage 1: Build Frontend ---
+FROM node:20-alpine AS frontend-builder
+WORKDIR /app/frontend
+COPY frontend/package*.json ./
+RUN npm install
+COPY frontend/ ./
+RUN npm run build
+
+# --- Stage 2: Serve Backend & Frontend ---
+FROM python:3.11-slim
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Copy backend requirements and install
+COPY backend/requirements.txt ./backend/
+RUN pip install --no-cache-dir -r backend/requirements.txt
+
+# Copy backend source
+COPY backend/ ./backend/
+
+# Copy compiled frontend build
+COPY --from=frontend-builder /app/frontend/dist /app/frontend/dist
+
+# Expose port (Hugging Face Spaces requires port 7860)
+EXPOSE 7860
+
+# Run FastAPI from the backend directory so imports resolve locally
+WORKDIR /app/backend
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,10 +1,221 @@
 ---
-title: Software Engineer Agent
-emoji: 🐠
-colorFrom: pink
-colorTo: yellow
+title: Repository Intelligence Layer
+emoji: 🔍
+colorFrom: green
+colorTo: blue
 sdk: docker
+app_port: 7860
 pinned: false
+license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Repository Intelligence Layer
+
+AI-powered repository analysis platform that clones or uploads codebases, generates structured intelligence artifacts with **Gemini 2.5 Flash**, and provides an interactive dashboard with graph visualization, semantic search, and multi-agent chat.
+
+![Dashboard Screenshot](./docs/screenshots/dashboard.png)
+<!-- Replace with actual screenshot after first run -->
+
+## Features
+
+- **GitHub cloning** — public and private repos (PAT authentication)
+- **ZIP upload** — drag-and-drop repository archives
+- **Repository scanner** — file tree, manifest parsing, static profiling
+- **Graph builder** — static import/dependency graph + LLM architecture graph
+- **Gemini analysis** — markdown report, profile, summary, and graph JSON
+- **Interactive dashboard** — report, summary, profile, graph viewer, repo tree
+- **AI Assistant** — multi-agent orchestration with RAG context
+- **Knowledge Explorer** — ChromaDB semantic search and conversation history
+- **Download endpoints** — export all intelligence artifacts
+- **Persistent memory** — artifacts saved to disk; ChromaDB vector index
+
+## Architecture
+
+```mermaid
+flowchart LR
+  subgraph Input
+    URL[GitHub URL + PAT]
+    ZIP[ZIP Upload]
+  end
+  subgraph Pipeline
+    Scan[Repository Scanner]
+    Profile[Repository Profiler]
+    Graph[Graph Builder]
+    LLM[Gemini Analyzer]
+    Mem[Memory Layer]
+    Chroma[ChromaDB Index]
+  end
+  subgraph Frontend
+    Tree[Repo Tree]
+    Dash[Dashboard]
+    GraphV[Graph Viewer]
+    Chat[AI Assistant]
+  end
+  URL --> Scan
+  ZIP --> Scan
+  Scan --> Profile
+  Profile --> Graph
+  Graph --> LLM
+  LLM --> Mem
+  LLM --> Chroma
+  Mem --> Dash
+  Scan --> Tree
+  Mem --> GraphV
+  Chroma --> Chat
+```
+
+## Project Structure
+
+```
+├── backend/           # FastAPI application
+│   ├── main.py        # API routes
+│   ├── services/      # Scanner, profiler, graph builder, LLM, memory
+│   ├── agents/        # Multi-agent orchestration
+│   ├── memory/        # ChromaDB, RAG, conversations
+│   └── tools/         # MCP-ready tool registry
+├── frontend/          # React + Vite dashboard
+├── Dockerfile         # Unified build for Hugging Face Spaces (port 7860)
+└── docker-compose.yml # Local split-stack development
+```
+
+## Installation
+
+### Prerequisites
+
+- Python 3.11+
+- Node.js 20+
+- Git (for repository cloning)
+- Gemini API key from [Google AI Studio](https://aistudio.google.com/)
+
+### Local Setup
+
+1. **Clone the repository**
+
+```bash
+git clone <your-repo-url>
+cd "Software Engineer Agent"
+```
+
+2. **Configure environment**
+
+```bash
+cp .env.example backend/.env
+# Edit backend/.env and set GEMINI_API_KEY
+```
+
+3. **Install backend dependencies**
+
+```bash
+cd backend
+pip install -r requirements.txt
+```
+
+4. **Install frontend dependencies**
+
+```bash
+cd ../frontend
+npm install
+```
+
+5. **Run locally (two terminals)**
+
+Terminal 1 — Backend:
+```bash
+cd backend
+uvicorn main:app --reload --host 127.0.0.1 --port 8000
+```
+
+Terminal 2 — Frontend:
+```bash
+cd frontend
+npm run dev
+```
+
+Open **http://localhost:5173** — the Vite dev server proxies `/api` to the backend.
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `GEMINI_API_KEY` | Yes | Google Gemini API key for analysis, chat, and embeddings |
+| `CORS_ORIGINS` | No | Comma-separated allowed origins (default: `*`) |
+| `VITE_API_URL` | No | Frontend API base URL (empty = same origin / Vite proxy) |
+| `VITE_API_PROXY` | No | Vite dev proxy target (default: `http://localhost:8000`) |
+
+## API Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/health` | Health check |
+| `POST` | `/api/analyze-url` | Clone and analyze a GitHub repository |
+| `POST` | `/api/analyze-zip` | Upload and analyze a ZIP archive |
+| `GET` | `/api/download/{repo_id}/{type}` | Download artifact (`profile`, `graph`, `summary`, `report`) |
+| `POST` | `/api/chat` | Multi-agent chat with RAG |
+| `POST` | `/api/search` | Semantic search over indexed knowledge |
+| `GET` | `/api/memory?repo_id=` | Vector index statistics |
+| `GET` | `/api/conversations?repo_id=` | List chat sessions |
+| `GET` | `/api/conversations/{session_id}` | Session message history |
+| `GET` | `/api/tools` | Tool catalog |
+
+## Docker
+
+### Unified (Hugging Face / production)
+
+```bash
+docker build -t repo-intelligence .
+docker run -p 7860:7860 -e GEMINI_API_KEY=your_key repo-intelligence
+```
+
+Open **http://localhost:7860**
+
+### Split stack (development)
+
+```bash
+export GEMINI_API_KEY=your_key
+docker compose up --build
+```
+
+- Frontend: **http://localhost:5173**
+- Backend: **http://localhost:8000**
+
+## Hugging Face Spaces Deployment
+
+This project is ready for **free deployment** on [Hugging Face Spaces](https://huggingface.co/spaces) using the Docker SDK.
+
+1. Create a new Space → select **Docker** as the SDK
+2. Push this repository (or connect GitHub)
+3. Ensure the root `Dockerfile` is used (builds frontend + serves backend on port **7860**)
+4. Add a Space secret: `GEMINI_API_KEY` = your Gemini API key
+5. Wait for the build to complete
+
+The Space will serve both the React dashboard and FastAPI backend from a single container.
+
+### HF Space Settings
+
+- **SDK:** Docker
+- **App port:** 7860
+- **Secrets:** `GEMINI_API_KEY`
+
+## Generated Artifacts
+
+After analysis, the platform produces:
+
+| File | Description |
+|------|-------------|
+| `repository_report.md` | Full markdown intelligence report |
+| `repository_profile.json` | Languages, frameworks, APIs, modules, auth |
+| `repository_summary.json` | Elevator pitch, features, workflows, risks |
+| `repository_graph.json` | Architecture nodes, edges, flows, concepts |
+
+Artifacts are stored in `backend/storage/repos/{repo_id}/` and available via the dashboard download buttons.
+
+## Security
+
+- ZIP extraction includes path-traversal protection
+- GitHub PAT tokens are redacted from error messages
+- Temporary clone/extract workspaces are cleaned up after analysis
+- Private repos require a valid GitHub Personal Access Token
+
+## License
+
+MIT

backend/.env

@@ -0,0 +1 @@
+GEMINI_API_KEY=AQ.Ab8RN6JCtHvyMAUiC4ldysHtPKp2vzTXWHjWFeke1frUha3BAA

backend/Dockerfile

@@ -0,0 +1,21 @@
+FROM python:3.11-slim
+
+# Install system dependencies (Git is required for cloning repos)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Copy requirements and install
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy backend code
+COPY . .
+
+# Expose port
+EXPOSE 8000
+
+# Start FastAPI application
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

backend/adapters/__init__.py

@@ -0,0 +1,3 @@
+from adapters.adk_adapter import GoogleADKPlatformAdapter
+from adapters.agent_adapter import ADKAgentAdapter
+from adapters.planner_adapter import ADKPlannerAdapter

backend/adapters/adk_adapter.py

@@ -0,0 +1,36 @@
+from typing import Dict, Any
+from adapters.agent_adapter import ADKAgentAdapter
+from adapters.planner_adapter import ADKPlannerAdapter
+
+class GoogleADKPlatformAdapter:
+    """
+    High-level adapter class representing a Google ADK Application context.
+    Integrates the multi-agent layers and provides entry points for task execution.
+    """
+    def __init__(self, orchestrator: Any):
+        self.orchestrator = orchestrator
+        self.planner_adapter = ADKPlannerAdapter(orchestrator.planner)
+        self.agent_adapters = {
+            name: ADKAgentAdapter(agent)
+            for name, agent in orchestrator.agents.items()
+        }
+
+    async def dispatch_query(
+        self,
+        profile: Dict[str, Any],
+        graph: Dict[str, Any],
+        summary: Dict[str, Any],
+        report: str,
+        query: str
+    ) -> Dict[str, Any]:
+        """
+        Executes queries by forwarding them to the underlying orchestrator,
+        representing a standard ADK execution cycle.
+        """
+        return await self.orchestrator.execute(
+            profile=profile,
+            graph=graph,
+            summary=summary,
+            report=report,
+            query=query
+        )

backend/adapters/agent_adapter.py

@@ -0,0 +1,26 @@
+from typing import Dict, Any
+from agents.base_agent import BaseAgent
+
+class ADKAgentAdapter:
+    """
+    Adapter wrapping existing BaseAgent specialized agents to conform to Google ADK
+    agent invocation schemas.
+    """
+    def __init__(self, agent: BaseAgent):
+        self.agent = agent
+        self.name = agent.__class__.__name__
+
+    async def execute_task(self, context: Dict[str, Any], query: str) -> Dict[str, Any]:
+        profile = context.get("profile", {})
+        graph = context.get("graph", {})
+        summary = context.get("summary", {})
+        report = context.get("report", "")
+        
+        # Call the underlying agent
+        return await self.agent.run(
+            profile=profile,
+            graph=graph,
+            summary=summary,
+            report=report,
+            query=query
+        )

backend/adapters/planner_adapter.py

@@ -0,0 +1,38 @@
+import time
+from typing import Dict, Any
+from agents.planner_agent import PlannerAgent
+
+class ADKPlannerAdapter:
+    """
+    Adapter wrapping the PlannerAgent to match ADK planner expectations.
+    """
+    def __init__(self, planner: PlannerAgent):
+        self.planner = planner
+
+    async def create_plan(self, context: Dict[str, Any], query: str) -> Dict[str, Any]:
+        profile = context.get("profile", {})
+        graph = context.get("graph", {})
+        summary = context.get("summary", {})
+        report = context.get("report", "")
+        
+        # Call planner
+        plan = await self.planner.run(
+            profile=profile,
+            graph=graph,
+            summary=summary,
+            report=report,
+            query=query
+        )
+        return {
+            "plan_id": f"plan_{int(time.time())}",
+            "steps": [
+                {
+                    "stage": idx + 1,
+                    "agents": stage,
+                    "parameters": {"query": query}
+                }
+                for idx, stage in enumerate(plan.get("execution_order", []))
+            ],
+            "reasoning": plan.get("reasoning", ""),
+            "selected_agents": plan.get("selected_agents", [])
+        }

backend/agents/__init__.py

@@ -0,0 +1,2 @@
+from agents.llm_client import LLMClient, GeminiLLMClient
+from agents.orchestrator import AgentOrchestrator

backend/agents/api_agent.py

@@ -0,0 +1,33 @@
+import json
+from typing import Dict, Any
+from agents.base_agent import BaseAgent, AgentResponseSchema
+
+class ApiAgent(BaseAgent):
+    async def run(
+        self,
+        profile: Dict[str, Any],
+        graph: Dict[str, Any],
+        summary: Dict[str, Any],
+        report: str,
+        query: str
+    ) -> Dict[str, Any]:
+        prompt = f"""
+You are the API Agent. Your responsibility is to analyze the API design of the repository, including HTTP methods, routes/endpoints, payload structures, external API dependencies, and data exchange/request-response flow.
+
+Here is the repository context:
+1. Profile:
+{json.dumps(profile, indent=2)}
+2. Graph Structure:
+{json.dumps(graph, indent=2)}
+3. Summary:
+{json.dumps(summary, indent=2)}
+4. Intelligence Report:
+{report}
+
+User Query:
+{query}
+
+Perform a rigorous analysis of the endpoints and API flow to answer this query. Your citations must specify specific routes or lines where endpoints are declared or configured.
+Return your structured answer matching the AgentResponseSchema.
+"""
+        return await self._call_llm_json(prompt, AgentResponseSchema)

backend/agents/architecture_agent.py

@@ -0,0 +1,33 @@
+import json
+from typing import Dict, Any
+from agents.base_agent import BaseAgent, AgentResponseSchema
+
+class ArchitectureAgent(BaseAgent):
+    async def run(
+        self,
+        profile: Dict[str, Any],
+        graph: Dict[str, Any],
+        summary: Dict[str, Any],
+        report: str,
+        query: str
+    ) -> Dict[str, Any]:
+        prompt = f"""
+You are the Architecture Agent. Your responsibility is to analyze the codebase structure, architectural design patterns, component relationships, data flow, business workflows, and entry points to answer the user query.
+
+Here is the repository context:
+1. Profile:
+{json.dumps(profile, indent=2)}
+2. Graph Structure:
+{json.dumps(graph, indent=2)}
+3. Summary:
+{json.dumps(summary, indent=2)}
+4. Intelligence Report:
+{report}
+
+User Query:
+{query}
+
+Perform a rigorous architectural analysis to answer this query. Your citations must specify files, code blocks, or components (e.g. "backend/main.py:L10-L40", "Graph Node: App.jsx").
+Return your structured answer matching the AgentResponseSchema.
+"""
+        return await self._call_llm_json(prompt, AgentResponseSchema)

backend/agents/base_agent.py

@@ -0,0 +1,31 @@
+from abc import ABC, abstractmethod
+from typing import Dict, Any, List
+import asyncio
+from pydantic import BaseModel, Field
+from agents.llm_client import LLMClient
+
+class AgentResponseSchema(BaseModel):
+    agent: str = Field(description="Name of the agent, e.g., SecurityAgent")
+    confidence: float = Field(description="Confidence score between 0.0 and 1.0 based on relevance and sufficiency of data")
+    answer: str = Field(description="Detailed answer or analysis regarding the user query")
+    citations: List[str] = Field(description="Source files, line numbers, or endpoints cited as reference")
+    reasoning: List[str] = Field(description="Step-by-step reasoning steps the agent took")
+
+class BaseAgent(ABC):
+    def __init__(self, llm_client: LLMClient):
+        self.llm_client = llm_client
+
+    @abstractmethod
+    async def run(
+        self,
+        profile: Dict[str, Any],
+        graph: Dict[str, Any],
+        summary: Dict[str, Any],
+        report: str,
+        query: str
+    ) -> Dict[str, Any]:
+        """Runs the agent's analysis."""
+        pass
+
+    async def _call_llm_json(self, prompt: str, schema: Any, temperature: float = 0.2) -> Dict[str, Any]:
+        return await asyncio.to_thread(self.llm_client.generate_json, prompt, schema, temperature)

backend/agents/dependency_agent.py

@@ -0,0 +1,33 @@
+import json
+from typing import Dict, Any
+from agents.base_agent import BaseAgent, AgentResponseSchema
+
+class DependencyAgent(BaseAgent):
+    async def run(
+        self,
+        profile: Dict[str, Any],
+        graph: Dict[str, Any],
+        summary: Dict[str, Any],
+        report: str,
+        query: str
+    ) -> Dict[str, Any]:
+        prompt = f"""
+You are the Dependency Agent. Your responsibility is to analyze libraries, package configurations (e.g. package.json, requirements.txt), framework selections, database integrations, cloud stack, and deployment environment setups.
+
+Here is the repository context:
+1. Profile:
+{json.dumps(profile, indent=2)}
+2. Graph Structure:
+{json.dumps(graph, indent=2)}
+3. Summary:
+{json.dumps(summary, indent=2)}
+4. Intelligence Report:
+{report}
+
+User Query:
+{query}
+
+Perform a rigorous analysis of project dependencies and frameworks to answer this query. Your citations must reference the package manifest files or configurations (e.g., "requirements.txt:L3", "docker-compose.yml:L5").
+Return your structured answer matching the AgentResponseSchema.
+"""
+        return await self._call_llm_json(prompt, AgentResponseSchema)

backend/agents/llm_client.py

@@ -0,0 +1,40 @@
+from abc import ABC, abstractmethod
+from typing import Dict, Any, Type
+from pydantic import BaseModel
+
+class LLMClient(ABC):
+    @abstractmethod
+    def generate_json(
+        self,
+        prompt: str,
+        response_schema: Type[BaseModel],
+        temperature: float = 0.2
+    ) -> Dict[str, Any]:
+        """Generates a structured JSON response matching the given response_schema."""
+        pass
+
+class GeminiLLMClient(LLMClient):
+    def __init__(self, api_key: str):
+        from google import genai
+        self._client = genai.Client(api_key=api_key)
+
+    def generate_json(
+        self,
+        prompt: str,
+        response_schema: Type[BaseModel],
+        temperature: float = 0.2
+    ) -> Dict[str, Any]:
+        import json
+        
+        response = self._client.models.generate_content(
+            model='gemini-2.5-flash',
+            contents=prompt,
+            config={
+                'response_mime_type': 'application/json',
+                'response_schema': response_schema,
+                'temperature': temperature
+            }
+        )
+        if not response.text:
+            raise ValueError("Gemini returned empty response text.")
+        return json.loads(response.text)

backend/agents/onboarding_agent.py

@@ -0,0 +1,33 @@
+import json
+from typing import Dict, Any
+from agents.base_agent import BaseAgent, AgentResponseSchema
+
+class OnboardingAgent(BaseAgent):
+    async def run(
+        self,
+        profile: Dict[str, Any],
+        graph: Dict[str, Any],
+        summary: Dict[str, Any],
+        report: str,
+        query: str
+    ) -> Dict[str, Any]:
+        prompt = f"""
+You are the Onboarding Agent. Your responsibility is to guide new developers in understanding the project execution flow, configuring local developer environments, locating entry point scripts, outlining recommended learning paths, and listing the key folders/files to read first.
+
+Here is the repository context:
+1. Profile:
+{json.dumps(profile, indent=2)}
+2. Graph Structure:
+{json.dumps(graph, indent=2)}
+3. Summary:
+{json.dumps(summary, indent=2)}
+4. Intelligence Report:
+{report}
+
+User Query:
+{query}
+
+Perform a rigorous developer-focused onboarding walkthrough to answer this query. Your citations must point out documentation, entry files, or configuration variables that speed up developer setup.
+Return your structured answer matching the AgentResponseSchema.
+"""
+        return await self._call_llm_json(prompt, AgentResponseSchema)

backend/agents/orchestrator.py

@@ -0,0 +1,351 @@
+import time
+import asyncio
+import logging
+import json
+from typing import Dict, Any, List, Optional
+from agents.llm_client import LLMClient
+from agents.planner_agent import PlannerAgent
+from agents.architecture_agent import ArchitectureAgent
+from agents.security_agent import SecurityAgent
+from agents.api_agent import ApiAgent
+from agents.dependency_agent import DependencyAgent
+from agents.quality_agent import QualityAgent
+from agents.onboarding_agent import OnboardingAgent
+from agents.response_synthesizer import ResponseSynthesizer
+from tools.tool_registry import tool_registry, setup_default_registry
+from memory.memory_cache import memory_cache
+from memory.conversation_manager import conversation_manager
+
+logger = logging.getLogger("orchestrator")
+
+class AgentOrchestrator:
+    def __init__(self, llm_client: LLMClient):
+        self.llm_client = llm_client
+        self.planner = PlannerAgent(llm_client)
+        self.synthesizer = ResponseSynthesizer(llm_client)
+        
+        # Register specialized agents
+        self.agents = {
+            "ArchitectureAgent": ArchitectureAgent(llm_client),
+            "SecurityAgent": SecurityAgent(llm_client),
+            "ApiAgent": ApiAgent(llm_client),
+            "DependencyAgent": DependencyAgent(llm_client),
+            "QualityAgent": QualityAgent(llm_client),
+            "OnboardingAgent": OnboardingAgent(llm_client)
+        }
+
+    async def execute(
+        self,
+        profile: Dict[str, Any],
+        graph: Dict[str, Any],
+        summary: Dict[str, Any],
+        report: str,
+        query: str,
+        repo_id: str,
+        session_id: Optional[str] = None,
+        vector_store: Optional[Any] = None,
+        retriever: Optional[Any] = None
+    ) -> Dict[str, Any]:
+        timeline = []
+        agents_used = []
+        start_total = time.time()
+
+        # Initialize tools registry if empty and vector dependencies are available
+        if not tool_registry.list_tools() and vector_store and retriever:
+            setup_default_registry(vector_store, retriever)
+
+        # 1. Run Planner Agent to decide execution steps
+        logger.info(f"Running PlannerAgent for query: '{query}'")
+        planner_start = time.time()
+        try:
+            planner_res = await self.planner.run(profile, graph, summary, report, query)
+            planner_latency = time.time() - planner_start
+            logger.info(f"PlannerAgent completed in {planner_latency:.2f}s. Plan: {planner_res}")
+            timeline.append({
+                "agent": "PlannerAgent",
+                "execution_time_ms": int(planner_latency * 1000),
+                "status": "success",
+                "message": f"Pipeline: memory={planner_res.get('retrieve_memory')}, search={planner_res.get('run_semantic_search')}, tools={planner_res.get('invoke_tools')}, agents={planner_res.get('selected_agents')}"
+            })
+        except Exception as e:
+            planner_latency = time.time() - planner_start
+            logger.error(f"PlannerAgent failed: {e}")
+            timeline.append({
+                "agent": "PlannerAgent",
+                "execution_time_ms": int(planner_latency * 1000),
+                "status": "failure",
+                "message": f"Planner failed: {str(e)}"
+            })
+            # Fallback plan: enable all pipeline elements and run all agents
+            planner_res = {
+                "retrieve_memory": True,
+                "run_semantic_search": True,
+                "invoke_tools": [],
+                "run_agents": True,
+                "selected_agents": list(self.agents.keys()),
+                "execution_order": [list(self.agents.keys())],
+                "synthesize_final_answer": True,
+                "reasoning": "Fallback plan due to planner failure."
+            }
+
+        retrieve_memory = planner_res.get("retrieve_memory", True)
+        run_semantic_search = planner_res.get("run_semantic_search", True)
+        invoke_tools = planner_res.get("invoke_tools", [])
+        run_agents = planner_res.get("run_agents", True)
+        selected_agents = planner_res.get("selected_agents", [])
+        execution_order = planner_res.get("execution_order", [])
+        synthesize_final_answer = planner_res.get("synthesize_final_answer", True)
+
+        # 2. Retrieve Memory if requested
+        memory_context = ""
+        if retrieve_memory and session_id:
+            logger.info(f"Retrieving conversation memory for session {session_id}")
+            mem_start = time.time()
+            session = conversation_manager.get_session(session_id)
+            if session and session.history:
+                past_turns = []
+                for msg in session.history[:-1]:  # Exclude current question which was already added
+                    past_turns.append(f"{msg.role.capitalize()}: {msg.content}")
+                memory_context = "\n".join(past_turns)
+            timeline.append({
+                "agent": "MemoryRetrieval",
+                "execution_time_ms": int((time.time() - mem_start) * 1000),
+                "status": "success",
+                "message": "Retrieved past turns" if memory_context else "No past turns found"
+            })
+
+        # 3. Run Semantic Search if requested
+        search_results = []
+        if run_semantic_search and retriever:
+            logger.info("Running semantic search retrieval")
+            search_start = time.time()
+            try:
+                search_results = retriever.retrieve(repo_id=repo_id, query=query, top_k=5)
+                timeline.append({
+                    "agent": "SemanticSearch",
+                    "execution_time_ms": int((time.time() - search_start) * 1000),
+                    "status": "success",
+                    "message": f"Found {len(search_results)} relevant chunks"
+                })
+            except Exception as e:
+                logger.error(f"Semantic search failed: {e}")
+                timeline.append({
+                    "agent": "SemanticSearch",
+                    "execution_time_ms": int((time.time() - search_start) * 1000),
+                    "status": "failure",
+                    "message": str(e)
+                })
+
+        # 4. Invoke Tools (with caching) if requested
+        tool_outputs = {}
+        if invoke_tools:
+            logger.info(f"Invoking tools: {invoke_tools}")
+            tool_start = time.time()
+            for tool_name in invoke_tools:
+                # Check memory cache first
+                cache_key = f"tool:{repo_id}:{tool_name}:{query}"
+                cached_res = memory_cache.get(cache_key)
+                if cached_res is not None:
+                    logger.info(f"Cache hit for tool '{tool_name}'")
+                    tool_outputs[tool_name] = cached_res
+                else:
+                    logger.info(f"Cache miss for tool '{tool_name}'. Executing...")
+                    res = tool_registry.execute_tool(tool_name, repo_id=repo_id, query=query)
+                    memory_cache.set(cache_key, res, ttl=300) # Cache for 5 mins
+                    tool_outputs[tool_name] = res
+            timeline.append({
+                "agent": "ToolInvocation",
+                "execution_time_ms": int((time.time() - tool_start) * 1000),
+                "status": "success",
+                "message": f"Executed {len(tool_outputs)} tools"
+            })
+
+        # 5. Run Specialized Agents if requested
+        agent_responses = []
+        if run_agents and selected_agents:
+            # Construct augmented query containing retrieved context and tool outputs
+            augmented_context_parts = []
+            if memory_context:
+                augmented_context_parts.append(f"--- Conversation History ---\n{memory_context}")
+            if search_results:
+                search_text = "\n\n".join(
+                    f"[Relevant Code Chunk | similarity={r['similarity']:.2f}]\n{r['content']}"
+                    for r in search_results
+                )
+                augmented_context_parts.append(f"--- Codebase Semantic Search Results ---\n{search_text}")
+            if tool_outputs:
+                tools_text = json.dumps(tool_outputs, indent=2)
+                augmented_context_parts.append(f"--- Direct Tool Outputs ---\n{tools_text}")
+
+            augmented_query = query
+            if augmented_context_parts:
+                augmented_query = f"{query}\n\n" + "\n\n".join(augmented_context_parts)
+
+            for stage_idx, stage in enumerate(execution_order):
+                tasks = []
+                agent_names = []
+                
+                for agent_name in stage:
+                    if agent_name in self.agents and agent_name in selected_agents:
+                        agent_names.append(agent_name)
+                        tasks.append(self._run_agent_with_retry(agent_name, profile, graph, summary, report, augmented_query))
+
+                if not tasks:
+                    continue
+
+                logger.info(f"Executing Stage {stage_idx + 1} with agents in parallel: {agent_names}")
+                stage_results = await asyncio.gather(*tasks, return_exceptions=True)
+
+                for agent_name, result in zip(agent_names, stage_results):
+                    agents_used.append(agent_name)
+                    
+                    if isinstance(result, Exception):
+                        logger.error(f"Agent {agent_name} failed execution: {result}")
+                        timeline.append({
+                            "agent": agent_name,
+                            "execution_time_ms": 0,
+                            "status": "failure",
+                            "message": str(result),
+                            "confidence": 0.0
+                        })
+                    else:
+                        agent_responses.append(result["response"])
+                        timeline.append({
+                            "agent": agent_name,
+                            "execution_time_ms": result["latency_ms"],
+                            "status": "success",
+                            "confidence": result["response"].get("confidence", 0.0),
+                            "answer": result["response"].get("answer", "")
+                        })
+
+        # 6. Run Response Synthesizer if requested
+        synth_res = {}
+        if synthesize_final_answer:
+            logger.info("Running ResponseSynthesizer...")
+            synth_start = time.time()
+            try:
+                synth_res = await self.synthesizer.synthesize(
+                    query=query,
+                    agent_responses=agent_responses,
+                    memory_context=memory_context,
+                    search_results=search_results,
+                    tool_outputs=tool_outputs
+                )
+                synth_latency = time.time() - synth_start
+                logger.info(f"ResponseSynthesizer completed in {synth_latency:.2f}s")
+                timeline.append({
+                    "agent": "ResponseSynthesizer",
+                    "execution_time_ms": int(synth_latency * 1000),
+                    "status": "success"
+                })
+            except Exception as e:
+                synth_latency = time.time() - synth_start
+                logger.error(f"ResponseSynthesizer failed: {e}")
+                timeline.append({
+                    "agent": "ResponseSynthesizer",
+                    "execution_time_ms": int(synth_latency * 1000),
+                    "status": "failure",
+                    "message": str(e)
+                })
+                # Fallback synthesis
+                fallback_answer = "\n\n".join([f"### {r.get('agent')}\n{r.get('answer')}" for r in agent_responses])
+                synth_res = {
+                    "summary": "Fallback summary compiled from individual agents.",
+                    "detailed_explanation": fallback_answer,
+                    "agent_contributions": [f"{r.get('agent')} (direct contribution)" for r in agent_responses],
+                    "confidence_score": 0.5
+                }
+        else:
+            # Synthesis bypassed, compile direct report from tools/search
+            logger.info("Bypassing ResponseSynthesizer per Planner decision")
+            direct_parts = []
+            if tool_outputs:
+                direct_parts.append("### Direct Tool Outputs")
+                for t_name, val in tool_outputs.items():
+                    direct_parts.append(f"**{t_name}**:\n```json\n{json.dumps(val, indent=2)}\n```")
+            if search_results:
+                direct_parts.append("### Codebase Search Results")
+                for r in search_results:
+                    direct_parts.append(f"- **{r['metadata'].get('path', 'unknown')}** (similarity={r['similarity']:.2f}):\n{r['content']}")
+            
+            detailed_explanation = "\n\n".join(direct_parts) if direct_parts else "No tools or search results were requested, and LLM synthesis was bypassed."
+            synth_res = {
+                "summary": "Direct result compiled from tools/search.",
+                "detailed_explanation": detailed_explanation,
+                "agent_contributions": ["Direct tool output execution."],
+                "confidence_score": 1.0
+            }
+            timeline.append({
+                "agent": "ResponseSynthesizer",
+                "execution_time_ms": 0,
+                "status": "success",
+                "message": "Bypassed synthesizer"
+            })
+
+        total_time_ms = int((time.time() - start_total) * 1000)
+
+        # Merge citations from all agent responses and search results
+        references = []
+        for r in agent_responses:
+            references.extend(r.get("citations", []))
+        for r in search_results:
+            path = r["metadata"].get("path")
+            if path and path not in references:
+                references.append(path)
+
+        unique_references = []
+        for ref in references:
+            if ref not in unique_references:
+                unique_references.append(ref)
+
+        answer = synth_res.get("detailed_explanation", "") or ""
+        if not answer:
+            logger.warning("Synthesized response was empty. Falling back to agent answers or summary.")
+            if agent_responses:
+                fallback_answer = "\n\n".join(
+                    f"### {r.get('agent', 'UnnamedAgent')}\n{r.get('answer', '') or 'No answer generated.'}"
+                    for r in agent_responses
+                ).strip()
+                answer = fallback_answer or synth_res.get("summary", "")
+            else:
+                answer = synth_res.get("summary", "No answer could be generated from the agents.")
+
+        return {
+            "answer": answer,
+            "summary": synth_res.get("summary", ""),
+            "agents_used": agents_used,
+            "confidence": synth_res.get("confidence_score", 0.0),
+            "references": unique_references,
+            "agent_contributions": synth_res.get("agent_contributions", []),
+            "planner_decision": planner_res,
+            "timeline": timeline,
+            "total_time_ms": total_time_ms,
+            "retrieved_context": search_results
+        }
+
+    async def _run_agent_with_retry(
+        self,
+        agent_name: str,
+        profile: Dict[str, Any],
+        graph: Dict[str, Any],
+        summary: Dict[str, Any],
+        report: str,
+        query: str,
+        retries: int = 2
+    ) -> Dict[str, Any]:
+        agent = self.agents[agent_name]
+        
+        for attempt in range(retries + 1):
+            start = time.time()
+            try:
+                response = await agent.run(profile, graph, summary, report, query)
+                latency_ms = int((time.time() - start) * 1000)
+                return {
+                    "response": response,
+                    "latency_ms": latency_ms
+                }
+            except Exception as e:
+                logger.warning(f"Agent {agent_name} attempt {attempt + 1} failed: {e}")
+                if attempt == retries:
+                    raise e
+                await asyncio.sleep(0.5)

backend/agents/planner_agent.py

@@ -0,0 +1,83 @@
+import json
+from typing import Dict, Any, List
+from pydantic import BaseModel, Field
+from agents.base_agent import BaseAgent
+
+class PlannerDecision(BaseModel):
+    retrieve_memory: bool = Field(
+        description="Whether to retrieve past conversation history or context for the current query."
+    )
+    run_semantic_search: bool = Field(
+        description="Whether to query the vector database for matching chunks from the codebase."
+    )
+    invoke_tools: List[str] = Field(
+        description="List of tool names to invoke, from: ['repository_search', 'graph_query', 'dependency_lookup', 'file_reader', 'architecture_lookup', 'api_lookup']."
+    )
+    run_agents: bool = Field(
+        description="Whether specialized agents should be executed."
+    )
+    selected_agents: List[str] = Field(
+        description="List of agent names selected to run if run_agents is true, from: ['ArchitectureAgent', 'SecurityAgent', 'ApiAgent', 'DependencyAgent', 'QualityAgent', 'OnboardingAgent']."
+    )
+    execution_order: List[List[str]] = Field(
+        description="Execution order for agents (e.g., [['SecurityAgent', 'ApiAgent'], ['ArchitectureAgent']]) if run_agents is true."
+    )
+    synthesize_final_answer: bool = Field(
+        description="Whether the response synthesizer should combine everything into the final answer. Set to True unless a direct tool/search result is sufficient."
+    )
+    reasoning: str = Field(
+        description="Explanation of why these pipeline decisions and agent executions were chosen."
+    )
+
+class PlannerAgent(BaseAgent):
+    async def run(
+        self,
+        profile: Dict[str, Any],
+        graph: Dict[str, Any],
+        summary: Dict[str, Any],
+        report: str,
+        query: str
+    ) -> Dict[str, Any]:
+        prompt = f"""
+You are the Agent Orchestration Planner. Your task is to analyze the user's query and decide the best execution pipeline to resolve it.
+
+The execution pipeline consists of:
+1. retrieve_memory: Fetching past chat history/turns.
+2. run_semantic_search: Finding relevant code snippets via vector embeddings.
+3. invoke_tools: Executing direct lookup/search tools.
+4. run_agents: Launching specialized agents in parallel or sequential stages.
+5. synthesize_final_answer: Combining all info into a clean final markdown explanation.
+
+Available Tools:
+- repository_search: Semantic search over indexed repo chunks.
+- graph_query: Query dependency graph, business flows, entry points.
+- dependency_lookup: Look up project languages, frameworks, packages.
+- file_reader: Retrieve specific source code file content.
+- architecture_lookup: Query high-level architecture pattern and major folders.
+- api_lookup: Look up HTTP endpoints, authentication details.
+
+Available Agents:
+1. ArchitectureAgent: Focuses on architectural patterns, component interaction, data flow, component responsibilities, and business flows.
+2. SecurityAgent: Focuses on authentication, authorization, API keys, secrets, security risks, vulnerability findings, and unsafe practices.
+3. ApiAgent: Focuses on endpoints, routes, HTTP methods, request/response models, and external APIs.
+4. DependencyAgent: Focuses on libraries, frameworks, cloud stack, dependencies, and infrastructure setup.
+5. QualityAgent: Focuses on complexity, maintainability, dead code, refactoring suggestions, and testing hints.
+6. OnboardingAgent: Focuses on developer onboarding walkthrough, where to start reading, and execution setup.
+
+Repository Profile:
+{json.dumps(profile, indent=2)}
+
+Repository Summary:
+{json.dumps(summary, indent=2)}
+
+User Query:
+{query}
+
+Determine:
+1. Which pipeline components should run (retrieve_memory, run_semantic_search, invoke_tools, run_agents, synthesize_final_answer).
+2. Which agents and tools are needed and their execution plan.
+3. The reasoning behind your plan.
+
+Return your decision in structured JSON format matching the schema.
+"""
+        return await self._call_llm_json(prompt, PlannerDecision, temperature=0.1)

backend/agents/quality_agent.py

@@ -0,0 +1,33 @@
+import json
+from typing import Dict, Any
+from agents.base_agent import BaseAgent, AgentResponseSchema
+
+class QualityAgent(BaseAgent):
+    async def run(
+        self,
+        profile: Dict[str, Any],
+        graph: Dict[str, Any],
+        summary: Dict[str, Any],
+        report: str,
+        query: str
+    ) -> Dict[str, Any]:
+        prompt = f"""
+You are the Quality Agent. Your responsibility is to analyze the codebase for code quality, maintainability, architectural complexity, indicators of dead code, large/bloated modules, potential code smells, and testing/coverage strategies.
+
+Here is the repository context:
+1. Profile:
+{json.dumps(profile, indent=2)}
+2. Graph Structure:
+{json.dumps(graph, indent=2)}
+3. Summary:
+{json.dumps(summary, indent=2)}
+4. Intelligence Report:
+{report}
+
+User Query:
+{query}
+
+Perform a rigorous analysis of the code quality and maintainability indicators to answer this query. Your citations must specify modules or files containing smells, complex blocks, or missing test configurations.
+Return your structured answer matching the AgentResponseSchema.
+"""
+        return await self._call_llm_json(prompt, AgentResponseSchema)

backend/agents/response_synthesizer.py

@@ -0,0 +1,63 @@
+import json
+from typing import Dict, Any, List, Optional
+from pydantic import BaseModel, Field
+from agents.llm_client import LLMClient
+
+class SynthesizedResponse(BaseModel):
+    summary: str = Field(description="A concise summary of all findings across agents")
+    detailed_explanation: str = Field(description="A comprehensive, detailed markdown explanation combining all insights, resolving duplicates, and directly answering the user query")
+    agent_contributions: List[str] = Field(description="List of strings explaining what each agent contributed (e.g. 'SecurityAgent: identified lack of rate limiting on the login route.')")
+    confidence_score: float = Field(description="A combined confidence score representing the quality and consensus of the generated answer (0.0 to 1.0)")
+
+class ResponseSynthesizer:
+    def __init__(self, llm_client: LLMClient):
+        self.llm_client = llm_client
+
+    async def synthesize(
+        self,
+        query: str,
+        agent_responses: List[Dict[str, Any]],
+        memory_context: Optional[str] = None,
+        search_results: Optional[List[Dict[str, Any]]] = None,
+        tool_outputs: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        import asyncio
+        responses_str = json.dumps(agent_responses, indent=2)
+        
+        context_parts = []
+        if memory_context:
+            context_parts.append(f"--- Past Conversation turns ---\n{memory_context}")
+        if search_results:
+            search_text = "\n\n".join(
+                f"[Search similarity={r['similarity']:.2f}]\n{r['content']}"
+                for r in search_results
+            )
+            context_parts.append(f"--- Semantic Search Context ---\n{search_text}")
+        if tool_outputs:
+            tools_text = json.dumps(tool_outputs, indent=2)
+            context_parts.append(f"--- Direct Tool Outputs ---\n{tools_text}")
+            
+        extra_context = "\n\n".join(context_parts)
+        
+        prompt = f"""
+You are the Principal Systems Integrator and Response Synthesizer.
+Your goal is to digest all specialized agent reports, retrieve context, tool outputs, and compile them into a single, cohesive, premium response answering the user's query.
+
+User Query:
+{query}
+
+{extra_context}
+
+Specialized Agent Responses:
+{responses_str}
+
+Tasks:
+1. Synthesize a single coherent, authoritative detailed explanation in markdown.
+2. Merge duplicate findings.
+3. Call out specific contributions or viewpoints of the agents/tools.
+4. Calculate an overall confidence score based on individual agent confidence levels, tool relevance, and consensus.
+5. Create a concise summary.
+
+Return the result matching the schema in structured JSON format.
+"""
+        return await asyncio.to_thread(self.llm_client.generate_json, prompt, SynthesizedResponse, 0.2)

backend/agents/security_agent.py

@@ -0,0 +1,33 @@
+import json
+from typing import Dict, Any
+from agents.base_agent import BaseAgent, AgentResponseSchema
+
+class SecurityAgent(BaseAgent):
+    async def run(
+        self,
+        profile: Dict[str, Any],
+        graph: Dict[str, Any],
+        summary: Dict[str, Any],
+        report: str,
+        query: str
+    ) -> Dict[str, Any]:
+        prompt = f"""
+You are the Security Agent. Your responsibility is to analyze the codebase for authentication methods, authorization mechanisms, handling of secrets/API keys, safety vulnerabilities, unsafe coding practices, and package dependencies that pose risks.
+
+Here is the repository context:
+1. Profile:
+{json.dumps(profile, indent=2)}
+2. Graph Structure:
+{json.dumps(graph, indent=2)}
+3. Summary:
+{json.dumps(summary, indent=2)}
+4. Intelligence Report:
+{report}
+
+User Query:
+{query}
+
+Perform a rigorous security analysis to answer this query. Your citations must specify files, lines, or configurations where security measures are implemented, missing, or potentially vulnerable.
+Return your structured answer matching the AgentResponseSchema.
+"""
+        return await self._call_llm_json(prompt, AgentResponseSchema)

backend/main.py

@@ -0,0 +1,561 @@
+import os
+import json
+import shutil
+import tempfile
+import uuid
+import logging
+from typing import Optional
+from fastapi import FastAPI, UploadFile, File, Form, HTTPException, Header, status
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
+from starlette.background import BackgroundTask
+from pydantic import BaseModel
+
+# Load .env variables manually if the file is present
+env_path = os.path.join(os.path.dirname(__file__), ".env")
+if os.path.exists(env_path):
+    with open(env_path, "r", encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if line and not line.startswith("#") and "=" in line:
+                key, val = line.split("=", 1)
+                os.environ[key.strip()] = val.strip()
+
+# Import services
+from services.repositoryScanner import (
+    check_repository_privacy, 
+    clone_repository, 
+    extract_zip, 
+    scan_directory,
+    handle_remove_readonly
+)
+from services.repositoryProfiler import profile_repository
+from services.graphBuilder import build_initial_graph
+from services.llmAnalyzer import analyze_repository
+from services.repositoryMemory import memory_service
+
+# Phase 3: Memory, RAG, Tools
+from memory.embedding_service import EmbeddingService
+from memory.vector_store import VectorStore
+from memory.knowledge_index import KnowledgeIndexBuilder
+from memory.retriever import KnowledgeRetriever
+from memory.conversation_manager import conversation_manager
+from memory.session_manager import session_manager
+from memory.memory_cache import memory_cache
+# Singleton memory infrastructure (initialised lazily per-request)
+_vector_store: VectorStore = None
+
+def get_vector_store() -> VectorStore:
+    global _vector_store
+    if _vector_store is None:
+        _vector_store = VectorStore()
+    return _vector_store
+
+# Setup logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger("main")
+
+app = FastAPI(
+    title="Repository Intelligence API",
+    description="Foundational Memory and Intelligence Layer for Multi-Agent AI Software Engineering",
+    version="1.0.0"
+)
+
+# Enable CORS for frontend integration (credentials disabled when using wildcard origins)
+_cors_origins = [o.strip() for o in os.environ.get("CORS_ORIGINS", "*").split(",") if o.strip()]
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=_cors_origins,
+    allow_credentials="*" not in _cors_origins,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Request schema for analyzing git repository
+class AnalyzeUrlRequest(BaseModel):
+    url: str
+    token: Optional[str] = None
+
+@app.get("/api/health")
+def health_check():
+    return {"status": "healthy"}
+
+@app.post("/api/analyze-url")
+async def analyze_git_url(
+    request: AnalyzeUrlRequest,
+    x_gemini_key: Optional[str] = Header(None)
+):
+    """
+    Clones a GitHub repository, validates access permissions, processes the pipeline,
+    calls Gemini 2.5 Flash, and returns structured intelligence outputs.
+    """
+    repo_url = request.url
+    token = request.token
+    gemini_key = x_gemini_key or os.environ.get("GEMINI_API_KEY")
+
+    if not gemini_key:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Gemini API Key is missing. Please provide it in the headers (x-gemini-key) or configure it on the server."
+        )
+
+    # 1. Validate repository privacy and access
+    logger.info(f"Validating access to repository: {repo_url}")
+    privacy_info = await check_repository_privacy(repo_url, token)
+    
+    if privacy_info["status"] in ["private_requires_auth", "private_denied"]:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail=privacy_info["message"]
+        )
+    elif privacy_info["status"] == "invalid":
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=privacy_info["message"]
+        )
+    elif privacy_info["status"] == "error":
+        raise HTTPException(
+            status_code=status.HTTP_502_BAD_GATEWAY,
+            detail=privacy_info["message"]
+        )
+
+    owner_repo = privacy_info["owner_repo"] or "cloned_repo"
+    repo_id = str(uuid.uuid4())
+
+    # Create a temporary directory in a secure, OS-agnostic manner
+    temp_dir = tempfile.mkdtemp(prefix="repo_intel_")
+    
+    try:
+        # 2. Clone the repository
+        logger.info(f"Cloning repository into temporary directory: {temp_dir}")
+        clone_repository(repo_url, temp_dir, token)
+        
+        # 3. Scan the repository file tree and text files
+        logger.info("Scanning directory structure...")
+        scan_results = scan_directory(temp_dir)
+        
+        # 4. Generate static profile and basic relationship graph
+        logger.info("Generating static profiles...")
+        static_profile = profile_repository(scan_results["files"])
+        static_graph = build_initial_graph(scan_results["files"])
+        static_profile["static_graph"] = static_graph
+        
+        # 5. Call LLM for deep reasoning and structured outputs
+        logger.info("Triggering Gemini 2.5 Flash intelligence analysis...")
+        analysis_result = await analyze_repository(
+            repo_name=owner_repo,
+            tree_structure=scan_results["tree"],
+            static_profile=static_profile,
+            flat_files=scan_results["files"],
+            api_key=gemini_key
+        )
+        
+        # 6. Save outputs inside the repositoryMemory service
+        logger.info("Storing generated artifacts in memory layer...")
+        stored = memory_service.store(
+            repo_id=repo_id,
+            profile=analysis_result["profile"],
+            graph=analysis_result["graph"],
+            summary=analysis_result["summary"],
+            report_markdown=analysis_result["report"]
+        )
+
+        # 7. Phase 3: Build semantic vector index asynchronously
+        gemini_key_for_embed = gemini_key
+        try:
+            logger.info("Building semantic knowledge index (ChromaDB)...")
+            import asyncio
+            embedder = EmbeddingService(api_key=gemini_key_for_embed)
+            vs = get_vector_store()
+            indexer = KnowledgeIndexBuilder(embedder, vs)
+            await asyncio.to_thread(
+                indexer.build_index,
+                repo_id,
+                analysis_result["profile"],
+                analysis_result["summary"],
+                analysis_result["graph"],
+                analysis_result["report"],
+                scan_results["files"]
+            )
+            logger.info(f"Knowledge index built for repo {repo_id}.")
+        except Exception as idx_e:
+            logger.warning(f"Knowledge index build failed (non-fatal): {idx_e}")
+        
+        return {
+            "success": True,
+            "repo_id": repo_id,
+            "project_name": owner_repo,
+            "tree": scan_results["tree"],
+            "data": stored
+        }
+
+    except Exception as e:
+        logger.error(f"Error during repository analysis: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Analysis failed: {str(e)}"
+        )
+    finally:
+        # Clean up temporary directory (safe rmtree for Windows/Linux read-only files)
+        logger.info(f"Cleaning up temporary workspace directory: {temp_dir}")
+        shutil.rmtree(temp_dir, onerror=handle_remove_readonly)
+
+@app.post("/api/analyze-zip")
+async def analyze_uploaded_zip(
+    file: UploadFile = File(...),
+    x_gemini_key: Optional[str] = Header(None)
+):
+    """
+    Extracts an uploaded repository ZIP file, runs structural scanning,
+    generates static/dynamic profile schemas, and runs the LLM analysis.
+    """
+    gemini_key = x_gemini_key or os.environ.get("GEMINI_API_KEY")
+
+    if not gemini_key:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Gemini API Key is missing. Please provide it in the headers (x-gemini-key) or configure it on the server."
+        )
+
+    if not file.filename.endswith(".zip"):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Invalid file format. Only ZIP archives are supported."
+        )
+
+    repo_id = str(uuid.uuid4())
+    project_name = file.filename[:-4]  # Strip .zip
+
+    # Set up temporary directory and paths
+    temp_dir = tempfile.mkdtemp(prefix="zip_intel_")
+    fd, zip_path = tempfile.mkstemp(suffix=".zip")
+    
+    try:
+        # Save ZIP upload chunk by chunk
+        with os.fdopen(fd, 'wb') as tmp_zip:
+            shutil.copyfileobj(file.file, tmp_zip)
+
+        # 1. Extract ZIP securely with path traversal protection
+        logger.info(f"Extracting zip archive: {file.filename}")
+        extract_zip(zip_path, temp_dir)
+        
+        # 2. Scan directory
+        logger.info("Scanning unzipped directory structure...")
+        scan_results = scan_directory(temp_dir)
+        
+        # 3. Generate static profiles
+        logger.info("Generating static profiles...")
+        static_profile = profile_repository(scan_results["files"])
+        static_graph = build_initial_graph(scan_results["files"])
+        static_profile["static_graph"] = static_graph
+        
+        # 4. Trigger Gemini analysis
+        logger.info("Analyzing unzipped codebase with Gemini 2.5 Flash...")
+        analysis_result = await analyze_repository(
+            repo_name=project_name,
+            tree_structure=scan_results["tree"],
+            static_profile=static_profile,
+            flat_files=scan_results["files"],
+            api_key=gemini_key
+        )
+        
+        # 5. Store generated artifacts
+        logger.info("Storing artifacts in memory service...")
+        stored = memory_service.store(
+            repo_id=repo_id,
+            profile=analysis_result["profile"],
+            graph=analysis_result["graph"],
+            summary=analysis_result["summary"],
+            report_markdown=analysis_result["report"]
+        )
+
+        # 6. Phase 3: Build semantic vector index
+        try:
+            logger.info("Building semantic knowledge index for ZIP repo...")
+            import asyncio
+            embedder = EmbeddingService(api_key=gemini_key)
+            vs = get_vector_store()
+            indexer = KnowledgeIndexBuilder(embedder, vs)
+            await asyncio.to_thread(
+                indexer.build_index,
+                repo_id,
+                analysis_result["profile"],
+                analysis_result["summary"],
+                analysis_result["graph"],
+                analysis_result["report"],
+                scan_results["files"]
+            )
+            logger.info(f"Knowledge index built for ZIP repo {repo_id}.")
+        except Exception as idx_e:
+            logger.warning(f"Knowledge index build failed (non-fatal): {idx_e}")
+        
+        return {
+            "success": True,
+            "repo_id": repo_id,
+            "project_name": project_name,
+            "tree": scan_results["tree"],
+            "data": stored
+        }
+
+    except Exception as e:
+        logger.error(f"Error processing uploaded zip file: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Analysis failed: {str(e)}"
+        )
+    finally:
+        # Cleanup
+        logger.info(f"Cleaning up temporary workspace files...")
+        if os.path.exists(zip_path):
+            os.remove(zip_path)
+        shutil.rmtree(temp_dir, onerror=handle_remove_readonly)
+
+def _cleanup_temp_dir(path: str) -> None:
+    if os.path.exists(path):
+        shutil.rmtree(path, ignore_errors=True)
+
+
+@app.get("/api/download/{repo_id}/{artifact_type}")
+async def download_intelligence_artifact(repo_id: str, artifact_type: str):
+    """
+    Downloads specific intelligence output as files (profile.json, graph.json, summary.json, report.md)
+    """
+    data = memory_service.retrieve(repo_id)
+    if not data:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Repository intelligence data not found or has expired."
+        )
+
+    artifact_map = {
+        "profile": ("repository_profile.json", "application/json", lambda d: json.dumps(d["profile"], indent=2)),
+        "graph": ("repository_graph.json", "application/json", lambda d: json.dumps(d["graph"], indent=2)),
+        "summary": ("repository_summary.json", "application/json", lambda d: json.dumps(d["summary"], indent=2)),
+        "report": ("repository_report.md", "text/markdown", lambda d: d["report"]),
+    }
+
+    if artifact_type not in artifact_map:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Invalid artifact type: {artifact_type}"
+        )
+
+    filename, media_type, content_fn = artifact_map[artifact_type]
+    temp_dir = tempfile.mkdtemp()
+    file_path = os.path.join(temp_dir, filename)
+
+    try:
+        with open(file_path, "w", encoding="utf-8") as f:
+            f.write(content_fn(data))
+        return FileResponse(
+            file_path,
+            media_type=media_type,
+            filename=filename,
+            background=BackgroundTask(_cleanup_temp_dir, temp_dir),
+        )
+    except Exception as e:
+        _cleanup_temp_dir(temp_dir)
+        logger.error(f"Error compiling download file: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to generate download file."
+        )
+
+class ChatRequest(BaseModel):
+    repo_id: str
+    question: str
+    session_id: Optional[str] = None
+
+@app.post("/api/chat")
+async def chat_with_repo(
+    request: ChatRequest,
+    x_gemini_key: Optional[str] = Header(None)
+):
+    """
+    Phase 2+3: Executes the multi-agent orchestration pipeline with RAG context
+    retrieval and conversation memory.
+    """
+    import time
+    import asyncio
+    from agents.llm_client import GeminiLLMClient
+    from agents.orchestrator import AgentOrchestrator
+
+    gemini_key = x_gemini_key or os.environ.get("GEMINI_API_KEY")
+    if not gemini_key:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Gemini API Key is missing."
+        )
+
+    repo_data = memory_service.retrieve(request.repo_id)
+    if not repo_data:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Repository intelligence data not found or has expired."
+        )
+
+    session_id = request.session_id or str(uuid.uuid4())
+
+    # Add user message to memory first
+    conversation_manager.add_message(
+        session_id=session_id,
+        repo_id=request.repo_id,
+        role="user",
+        content=request.question
+    )
+
+    try:
+        llm_client = GeminiLLMClient(api_key=gemini_key)
+        orchestrator = AgentOrchestrator(llm_client)
+        
+        embedder = EmbeddingService(api_key=gemini_key)
+        retriever = KnowledgeRetriever(embedder, get_vector_store())
+
+        logger.info(f"Orchestrating agents for repo {request.repo_id}: '{request.question}'")
+
+        # Run pipeline
+        result = await orchestrator.execute(
+            profile=repo_data["profile"],
+            graph=repo_data["graph"],
+            summary=repo_data["summary"],
+            report=repo_data["report"],
+            query=request.question,
+            repo_id=request.repo_id,
+            session_id=session_id,
+            vector_store=get_vector_store(),
+            retriever=retriever
+        )
+
+        # Attach session and RAG details
+        result["session_id"] = session_id
+        
+        # Populate retrieved context on user message
+        session = conversation_manager.get_session(session_id)
+        if session and session.history:
+            session.history[-1].retrieved_context = result.get("retrieved_context", [])
+
+        # Store assistant response in conversation memory
+        conversation_manager.add_message(
+            session_id=session_id,
+            repo_id=request.repo_id,
+            role="assistant",
+            content=result.get("answer", ""),
+            agent_decisions={
+                "agents_used": result.get("agents_used", []),
+                "confidence": result.get("confidence", 0.0),
+                "planner_decision": result.get("planner_decision", {})
+            }
+        )
+
+        # Persist conversation sessions to disk
+        session_manager.save_all()
+
+        return result
+
+    except Exception as e:
+        logger.error(f"Chat orchestration error: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Chat execution failed: {str(e)}"
+        )
+
+
+class SearchRequest(BaseModel):
+    repo_id: str
+    query: str
+    top_k: int = 5
+    category: Optional[str] = None
+
+@app.post("/api/search")
+async def semantic_search(
+    request: SearchRequest,
+    x_gemini_key: Optional[str] = Header(None)
+):
+    """Phase 3: Semantic search against the repository knowledge vector index."""
+    import time
+    gemini_key = x_gemini_key or os.environ.get("GEMINI_API_KEY")
+    if not gemini_key:
+        raise HTTPException(status_code=400, detail="Gemini API Key required for semantic search.")
+
+    repo_data = memory_service.retrieve(request.repo_id)
+    if not repo_data:
+        raise HTTPException(status_code=404, detail="Repository data not found.")
+
+    try:
+        start = time.time()
+        embedder = EmbeddingService(api_key=gemini_key)
+        retriever = KnowledgeRetriever(embedder, get_vector_store())
+        results = retriever.retrieve(
+            repo_id=request.repo_id,
+            query=request.query,
+            top_k=request.top_k,
+            category=request.category
+        )
+        latency_ms = int((time.time() - start) * 1000)
+        return {
+            "query": request.query,
+            "results": results,
+            "result_count": len(results),
+            "latency_ms": latency_ms
+        }
+    except Exception as e:
+        logger.error(f"Semantic search error: {e}")
+        raise HTTPException(status_code=500, detail=f"Search failed: {str(e)}")
+
+
+@app.get("/api/memory")
+async def get_memory_info(repo_id: str):
+    """Phase 3: Returns vector index stats for a repository."""
+    try:
+        vs = get_vector_store()
+        count = vs.count_documents(repo_id)
+        return {
+            "repo_id": repo_id,
+            "indexed_chunks": count,
+            "storage_path": vs.storage_path
+        }
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.get("/api/conversations")
+async def list_conversations(repo_id: str):
+    """Phase 3: Returns conversation sessions for a repository."""
+    sessions = conversation_manager.list_sessions_for_repo(repo_id)
+    return {"repo_id": repo_id, "sessions": sessions}
+
+
+@app.get("/api/conversations/{session_id}")
+async def get_conversation(session_id: str):
+    """Returns full message history for a conversation session."""
+    history = session_manager.get_session_history(session_id)
+    if history is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Conversation session not found."
+        )
+    return {"session_id": session_id, "history": history}
+
+
+@app.get("/api/tools")
+async def list_tools():
+    """Phase 3: Returns the registered tool catalog (MCP-ready)."""
+    tools = [
+        {"name": "repository_search",    "description": "Semantic search over indexed repo chunks."},
+        {"name": "graph_query",           "description": "Query architecture graph, entry points, and flows."},
+        {"name": "dependency_lookup",     "description": "Lookup packages, frameworks, and databases."},
+        {"name": "file_reader",           "description": "Retrieve specific source file content."},
+        {"name": "architecture_lookup",   "description": "Query architecture pattern and key modules."},
+        {"name": "api_lookup",            "description": "Lookup HTTP routes and authentication methods."}
+    ]
+    return {"tools": tools, "count": len(tools)}
+
+# Serve static frontend build if present
+frontend_dist = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "frontend", "dist"))
+if os.path.exists(frontend_dist):
+    logger.info(f"Serving static frontend files from: {frontend_dist}")
+    app.mount("/", StaticFiles(directory=frontend_dist, html=True), name="static")
+else:
+    logger.warning(f"Frontend dist folder not found at {frontend_dist}. Running in API-only mode.")
+

backend/memory/__init__.py

@@ -0,0 +1,7 @@
+from memory.embedding_service import EmbeddingService
+from memory.vector_store import VectorStore
+from memory.knowledge_index import KnowledgeIndexBuilder
+from memory.retriever import KnowledgeRetriever
+from memory.conversation_manager import conversation_manager
+from memory.session_manager import session_manager
+from memory.memory_cache import memory_cache

backend/memory/conversation_manager.py

@@ -0,0 +1,80 @@
+import time
+from typing import List, Dict, Any, Optional
+from pydantic import BaseModel, Field
+
+class MessageRecord(BaseModel):
+    role: str  # 'user' | 'assistant'
+    content: str
+    timestamp: float = Field(default_factory=time.time)
+    retrieved_context: Optional[List[Dict[str, Any]]] = None
+    agent_decisions: Optional[Dict[str, Any]] = None
+
+class ConversationSession(BaseModel):
+    session_id: str
+    repo_id: str
+    history: List[MessageRecord] = Field(default_factory=list)
+    summary: str = ""
+
+class ConversationManager:
+    """
+    Manages multi-session conversation tracking, caching history in-memory.
+    Persists context, questions, answers, and internal timeline decisions.
+    """
+    def __init__(self):
+        self._sessions: Dict[str, ConversationSession] = {}
+
+    def get_or_create_session(self, session_id: str, repo_id: str) -> ConversationSession:
+        if session_id not in self._sessions:
+            self._sessions[session_id] = ConversationSession(session_id=session_id, repo_id=repo_id)
+        return self._sessions[session_id]
+
+    def add_message(
+        self,
+        session_id: str,
+        repo_id: str,
+        role: str,
+        content: str,
+        retrieved_context: Optional[List[Dict[str, Any]]] = None,
+        agent_decisions: Optional[Dict[str, Any]] = None
+    ) -> MessageRecord:
+        session = self.get_or_create_session(session_id, repo_id)
+        record = MessageRecord(
+            role=role,
+            content=content,
+            timestamp=time.time(),
+            retrieved_context=retrieved_context,
+            agent_decisions=agent_decisions
+        )
+        session.history.append(record)
+        
+        # Keep summary updated with the last user prompt summary or simple description
+        if role == "user" and not session.summary:
+            # First query acts as session title/summary
+            session.summary = content[:40] + ("..." if len(content) > 40 else "")
+            
+        return record
+
+    def update_summary(self, session_id: str, summary: str):
+        if session_id in self._sessions:
+            self._sessions[session_id].summary = summary
+
+    def get_session(self, session_id: str) -> Optional[ConversationSession]:
+        return self._sessions.get(session_id)
+
+    def list_sessions_for_repo(self, repo_id: str) -> List[Dict[str, Any]]:
+        return [
+            {
+                "session_id": s.session_id,
+                "repo_id": s.repo_id,
+                "summary": s.summary,
+                "message_count": len(s.history),
+                "last_updated": s.history[-1].timestamp if s.history else time.time()
+            }
+            for s in self._sessions.values() if s.repo_id == repo_id
+        ]
+
+    def clear_sessions(self):
+        self._sessions.clear()
+
+# Global conversation manager singleton
+conversation_manager = ConversationManager()

backend/memory/embedding_service.py

@@ -0,0 +1,46 @@
+import os
+import logging
+from typing import List, Optional
+
+logger = logging.getLogger("embedding_service")
+
+class EmbeddingService:
+    def __init__(self, api_key: Optional[str] = None):
+        self.api_key = api_key or os.environ.get("GEMINI_API_KEY")
+        if not self.api_key:
+            raise ValueError("Gemini API key is required to generate embeddings.")
+        from google import genai
+        self.client = genai.Client(api_key=self.api_key)
+
+    def embed_text(self, text: str) -> List[float]:
+        """Generates embedding for a single text string."""
+        try:
+            response = self.client.models.embed_content(
+                model='text-embedding-004',
+                contents=text
+            )
+            if response.embeddings and len(response.embeddings) > 0:
+                return response.embeddings[0].values
+            raise ValueError("No embeddings returned from Gemini API.")
+        except Exception as e:
+            logger.error(f"Error generating embedding: {e}")
+            raise e
+
+    def embed_texts(self, texts: List[str]) -> List[List[float]]:
+        """Generates embeddings for a batch list of text strings."""
+        if not texts:
+            return []
+        try:
+            # Check length to prevent massive batch issues; text-embedding-004 supports bulk
+            response = self.client.models.embed_content(
+                model='text-embedding-004',
+                contents=texts
+            )
+            if response.embeddings and len(response.embeddings) == len(texts):
+                return [e.values for e in response.embeddings]
+            elif response.embeddings:
+                return [e.values for e in response.embeddings]
+            raise ValueError("No embeddings returned from batch API call.")
+        except Exception as e:
+            logger.error(f"Error generating batch embeddings: {e}")
+            raise e

backend/memory/knowledge_index.py

@@ -0,0 +1,185 @@
+import json
+import logging
+from typing import List, Dict, Any, Tuple
+from memory.embedding_service import EmbeddingService
+from memory.vector_store import VectorStore
+
+logger = logging.getLogger("knowledge_index")
+
+class KnowledgeIndexBuilder:
+    def __init__(self, embedding_service: EmbeddingService, vector_store: VectorStore):
+        self.embedder = embedding_service
+        self.store = vector_store
+
+    def chunk_text(self, text: str, chunk_size: int = 1000, overlap: int = 100) -> List[str]:
+        """Simple sliding window text splitter."""
+        if not text:
+            return []
+        chunks = []
+        start = 0
+        text_len = len(text)
+        
+        while start < text_len:
+            end = min(start + chunk_size, text_len)
+            chunks.append(text[start:end])
+            start += chunk_size - overlap
+            
+            # Prevent infinite loop if overlap >= chunk_size
+            if chunk_size - overlap <= 0:
+                break
+                
+        return chunks
+
+    def build_index(
+        self,
+        repo_id: str,
+        profile: Dict[str, Any],
+        summary: Dict[str, Any],
+        graph: Dict[str, Any],
+        report: str,
+        flat_files: List[Dict[str, Any]]
+    ):
+        """Builds and indexes a repository's code, structure, and profile metadata into ChromaDB."""
+        logger.info(f"Starting index build for repository: {repo_id}")
+        
+        # Clear existing collection if any
+        self.store.delete_collection(repo_id)
+        
+        documents: List[str] = []
+        metadatas: List[Dict[str, Any]] = []
+        ids: List[str] = []
+        
+        # Helper to generate unique IDs
+        def add_chunk(content: str, metadata: Dict[str, Any], prefix: str):
+            chunk_id = f"{prefix}_{len(documents)}"
+            documents.append(content)
+            metadatas.append(metadata)
+            ids.append(chunk_id)
+
+        # 1. Index the Repository Intelligence Report (Markdown)
+        report_chunks = self.chunk_text(report, chunk_size=1000, overlap=100)
+        for i, chunk in enumerate(report_chunks):
+            add_chunk(
+                content=chunk,
+                metadata={"category": "report", "chunk_index": i},
+                prefix="report"
+            )
+
+        # 2. Index the Summary details
+        elevator_pitch = summary.get("elevator_pitch", "")
+        if elevator_pitch:
+            add_chunk(
+                content=f"Project Elevator Pitch:\n{elevator_pitch}",
+                metadata={"category": "summary", "subcategory": "elevator_pitch"},
+                prefix="summary_pitch"
+            )
+            
+        for feat in summary.get("core_features", []):
+            add_chunk(
+                content=f"Core Feature: {feat}",
+                metadata={"category": "summary", "subcategory": "core_feature"},
+                prefix="summary_feat"
+            )
+            
+        for start_point in summary.get("developer_start_points", []):
+            add_chunk(
+                content=f"Developer Starting Point File: {start_point}",
+                metadata={"category": "summary", "subcategory": "developer_start_point"},
+                prefix="summary_start"
+            )
+
+        # 3. Index Profile Metadata (Architecture, APIs, Auth, Dependencies)
+        arch_pattern = profile.get("architecture_pattern", "")
+        if arch_pattern:
+            add_chunk(
+                content=f"Architecture Pattern: {arch_pattern}",
+                metadata={"category": "architecture", "pattern": arch_pattern},
+                prefix="profile_arch"
+            )
+            
+        for auth_method in profile.get("authentication_methods", []):
+            add_chunk(
+                content=f"Authentication / Security Method: {auth_method}",
+                metadata={"category": "authentication", "method": auth_method},
+                prefix="profile_auth"
+            )
+            
+        for endpoint in profile.get("api_endpoints", []):
+            add_chunk(
+                content=f"API Endpoint / Route: {endpoint}",
+                metadata={"category": "api", "endpoint": endpoint},
+                prefix="profile_api"
+            )
+            
+        for dep in profile.get("dependencies", []):
+            add_chunk(
+                content=f"Package Dependency: {dep}",
+                metadata={"category": "dependency", "dependency": dep},
+                prefix="profile_dep"
+            )
+
+        # 4. Index Business Flows & Concepts from Graph
+        for flow in graph.get("business_flows", []):
+            flow_name = flow.get("flow_name", "")
+            flow_desc = flow.get("description", "")
+            flow_steps = ", ".join(flow.get("steps", []))
+            add_chunk(
+                content=f"Business Flow: {flow_name}\nDescription: {flow_desc}\nSteps: {flow_steps}",
+                metadata={"category": "business_flow", "flow_name": flow_name},
+                prefix="graph_flow"
+            )
+            
+        for concept in graph.get("concepts", []):
+            concept_name = concept.get("name", "")
+            concept_desc = concept.get("description", "")
+            concept_files = ", ".join(concept.get("files", []))
+            add_chunk(
+                content=f"Core Concept: {concept_name}\nDescription: {concept_desc}\nFiles: {concept_files}",
+                metadata={"category": "concept", "concept_name": concept_name},
+                prefix="graph_concept"
+            )
+
+        # 5. Index Source Code Files Content
+        for f in flat_files:
+            file_path = f.get("path", "")
+            content = f.get("content", "")
+            file_size = f.get("size", 0)
+            
+            # Skip massive files to avoid cluttering vector space
+            if file_size > 100 * 1024 or not content:
+                continue
+                
+            file_chunks = self.chunk_text(content, chunk_size=1000, overlap=100)
+            for j, chunk in enumerate(file_chunks):
+                # Include path info inside the document text to maintain retrieval association
+                chunk_content = f"File: {file_path} (Chunk {j+1}/{len(file_chunks)})\n\n{chunk}"
+                add_chunk(
+                    content=chunk_content,
+                    metadata={"category": "file", "path": file_path, "chunk_index": j},
+                    prefix="file_chunk"
+                )
+
+        if not documents:
+            logger.info("No documents found to index.")
+            return
+
+        # 6. Generate Embeddings in Batches of 50 to respect API rate limits and connection pooling
+        batch_size = 50
+        logger.info(f"Generating embeddings for {len(documents)} document chunks in batches of {batch_size}...")
+        
+        all_embeddings: List[List[float]] = []
+        for start_idx in range(0, len(documents), batch_size):
+            end_idx = min(start_idx + batch_size, len(documents))
+            batch_docs = documents[start_idx:end_idx]
+            batch_embeddings = self.embedder.embed_texts(batch_docs)
+            all_embeddings.extend(batch_embeddings)
+            
+        # 7. Write to Vector Store
+        self.store.add_documents(
+            repo_id=repo_id,
+            documents=documents,
+            metadatas=metadatas,
+            ids=ids,
+            embeddings=all_embeddings
+        )
+        logger.info(f"Vector database indexing complete. Indexed {len(documents)} chunks.")

backend/memory/memory_cache.py

@@ -0,0 +1,42 @@
+import time
+from typing import Dict, Any, Optional
+
+class CacheEntry:
+    def __init__(self, value: Any, ttl: Optional[float] = None):
+        self.value = value
+        self.expires_at = time.time() + ttl if ttl is not None else None
+
+    def is_expired(self) -> bool:
+        if self.expires_at is None:
+            return False
+        return time.time() > self.expires_at
+
+class MemoryCache:
+    """
+    In-memory cache with TTL support for accelerating AI agent executions
+    and caching heavy search/graph query results.
+    """
+    def __init__(self):
+        self._cache: Dict[str, CacheEntry] = {}
+
+    def get(self, key: str) -> Optional[Any]:
+        entry = self._cache.get(key)
+        if not entry:
+            return None
+        if entry.is_expired():
+            del self._cache[key]
+            return None
+        return entry.value
+
+    def set(self, key: str, value: Any, ttl: Optional[float] = None):
+        self._cache[key] = CacheEntry(value, ttl)
+
+    def delete(self, key: str):
+        if key in self._cache:
+            del self._cache[key]
+
+    def clear(self):
+        self._cache.clear()
+
+# Global memory cache singleton
+memory_cache = MemoryCache()

backend/memory/retriever.py

@@ -0,0 +1,43 @@
+import logging
+from typing import List, Dict, Any, Optional
+from memory.embedding_service import EmbeddingService
+from memory.vector_store import VectorStore
+
+logger = logging.getLogger("retriever")
+
+class KnowledgeRetriever:
+    def __init__(self, embedding_service: EmbeddingService, vector_store: VectorStore):
+        self.embedder = embedding_service
+        self.store = vector_store
+
+    def retrieve(
+        self,
+        repo_id: str,
+        query: str,
+        top_k: int = 5,
+        category: Optional[str] = None
+    ) -> List[Dict[str, Any]]:
+        """
+        Runs semantic search on ChromaDB for the repo using the query.
+        Supports filtering by metadata 'category'.
+        """
+        logger.info(f"Retrieving context for repo {repo_id}, query: '{query}' (category filter: {category}, top_k: {top_k})")
+        
+        try:
+            # Generate query vector using embedder
+            query_embedding = self.embedder.embed_text(query)
+            
+            # Setup filter
+            where_filter = None
+            if category:
+                where_filter = {"category": category}
+                
+            return self.store.query_documents(
+                repo_id=repo_id,
+                query_embedding=query_embedding,
+                top_k=top_k,
+                where_filter=where_filter
+            )
+        except Exception as e:
+            logger.error(f"Failed to retrieve vector search results: {e}")
+            return []

backend/memory/session_manager.py

@@ -0,0 +1,65 @@
+import os
+import json
+import logging
+from typing import Dict, Any, List, Optional
+from pydantic import BaseModel
+from memory.conversation_manager import conversation_manager, ConversationSession, MessageRecord
+
+logger = logging.getLogger("session_manager")
+
+class SessionManager:
+    """
+    Manages persistence and high-level metadata for multiple repository sessions.
+    Saves and loads conversation history and repository state to/from disk.
+    """
+    def __init__(self, storage_dir: str = None):
+        if storage_dir is None:
+            storage_dir = os.path.join(os.path.dirname(os.path.dirname(__file__)), "storage")
+        self.storage_dir = storage_dir
+        os.makedirs(self.storage_dir, exist_ok=True)
+        self.conversations_file = os.path.join(self.storage_dir, "conversations.json")
+        self.load_all()
+
+    def load_all(self):
+        if os.path.exists(self.conversations_file):
+            try:
+                with open(self.conversations_file, "r", encoding="utf-8") as f:
+                    data = json.load(f)
+                    for session_id, s_data in data.items():
+                        session = ConversationSession(
+                            session_id=session_id,
+                            repo_id=s_data.get("repo_id"),
+                            summary=s_data.get("summary", ""),
+                            history=[
+                                MessageRecord(**msg) for msg in s_data.get("history", [])
+                            ]
+                        )
+                        conversation_manager._sessions[session_id] = session
+                logger.info(f"Loaded conversations from {self.conversations_file}")
+            except Exception as e:
+                logger.error(f"Error loading conversations: {e}")
+
+    def save_all(self):
+        data = {}
+        for session_id, session in conversation_manager._sessions.items():
+            data[session_id] = {
+                "session_id": session.session_id,
+                "repo_id": session.repo_id,
+                "summary": session.summary,
+                "history": [msg.model_dump() for msg in session.history]
+            }
+        try:
+            with open(self.conversations_file, "w", encoding="utf-8") as f:
+                json.dump(data, f, indent=2)
+            logger.info(f"Saved conversations to {self.conversations_file}")
+        except Exception as e:
+            logger.error(f"Error saving conversations: {e}")
+
+    def get_session_history(self, session_id: str) -> Optional[List[Dict[str, Any]]]:
+        session = conversation_manager.get_session(session_id)
+        if not session:
+            return None
+        return [msg.model_dump() for msg in session.history]
+
+# Global session manager singleton
+session_manager = SessionManager()

backend/memory/vector_store.py

@@ -0,0 +1,95 @@
+import os
+import logging
+from typing import Dict, Any, List, Optional
+import chromadb
+
+logger = logging.getLogger("vector_store")
+
+class VectorStore:
+    def __init__(self, storage_path: Optional[str] = None):
+        self.storage_path = storage_path or os.environ.get("CHROMA_DB_PATH", "./chroma_db")
+        os.makedirs(self.storage_path, exist_ok=True)
+        # Initialize persistent ChromaDB client
+        self.client = chromadb.PersistentClient(path=self.storage_path)
+
+    def get_collection(self, repo_id: str):
+        # Convert UUID repo_id to a valid Chroma collection name (alphanumeric and underscores)
+        coll_name = f"repo_{repo_id.replace('-', '_')}"
+        return self.client.get_or_create_collection(
+            name=coll_name,
+            metadata={"hnsw:space": "cosine"}
+        )
+
+    def add_documents(
+        self,
+        repo_id: str,
+        documents: List[str],
+        metadatas: List[Dict[str, Any]],
+        ids: List[str],
+        embeddings: List[List[float]]
+    ):
+        """Adds documents with their corresponding embeddings and metadata."""
+        if not documents:
+            return
+        collection = self.get_collection(repo_id)
+        collection.add(
+            documents=documents,
+            metadatas=metadatas,
+            ids=ids,
+            embeddings=embeddings
+        )
+        logger.info(f"Added {len(documents)} chunks to vector store collection for repo {repo_id}")
+
+    def query_documents(
+        self,
+        repo_id: str,
+        query_embedding: List[float],
+        top_k: int = 5,
+        where_filter: Optional[Dict[str, Any]] = None
+    ) -> List[Dict[str, Any]]:
+        """Queries ChromaDB using the query vector, returning matching chunks with similarity scores."""
+        collection = self.get_collection(repo_id)
+        
+        # Query ChromaDB
+        results = collection.query(
+            query_embeddings=[query_embedding],
+            n_results=top_k,
+            where=where_filter
+        )
+        
+        formatted = []
+        if results and "documents" in results and len(results["documents"]) > 0:
+            docs = results["documents"][0]
+            metas = results["metadatas"][0] if results.get("metadatas") else [{} for _ in range(len(docs))]
+            ids = results["ids"][0] if results.get("ids") else [str(i) for i in range(len(docs))]
+            distances = results["distances"][0] if results.get("distances") else [0.0 for _ in range(len(docs))]
+            
+            for doc, meta, doc_id, dist in zip(docs, metas, ids, distances):
+                # Cosine distance to similarity: 1 - distance
+                similarity = 1.0 - dist
+                formatted.append({
+                    "id": doc_id,
+                    "content": doc,
+                    "metadata": meta,
+                    "similarity": round(similarity, 4),
+                    "distance": round(dist, 4)
+                })
+        
+        # Sort by similarity descending
+        formatted.sort(key=lambda x: x["similarity"], reverse=True)
+        return formatted
+
+    def delete_collection(self, repo_id: str):
+        coll_name = f"repo_{repo_id.replace('-', '_')}"
+        try:
+            self.client.delete_collection(name=coll_name)
+            logger.info(f"Deleted vector store collection: {coll_name}")
+        except Exception as e:
+            logger.warning(f"Could not delete collection {coll_name}: {e}")
+
+    def count_documents(self, repo_id: str) -> int:
+        try:
+            collection = self.get_collection(repo_id)
+            return collection.count()
+        except Exception:
+            return 0

backend/requirements.txt

@@ -0,0 +1,7 @@
+fastapi==0.115.6
+uvicorn==0.34.0
+pydantic==2.10.4
+google-genai==1.14.0
+python-multipart==0.0.20
+httpx==0.28.1
+chromadb==1.5.9

backend/services/__init__.py

@@ -0,0 +1 @@
+# Services package