y# 🐕 PomPom-AI: Intelligent Memory System for Qodo AI

**PomPom-AI** (PomPom Artificial Intelligence) - A smart MCP (Model Context Protocol) server that provides persistent memory capabilities for Qodo AI. Just like Pompompurin's friendly and reliable nature, PomPom-AI remembers everything important and helps your AI assistant provide personalized, intelligent responses across all conversations.

## 🎯 **Personal Setup for Qodo AI Integration**

This repository is configured for personal use with Qodo AI, providing long-term memory storage and retrieval capabilities.

### **Qodo AI MCP Configuration**
```json
{
  "pompom-ai": {
    "url": "http://localhost:8051/sse"
  }
}
```

## 🚀 **Quick Start Guide**

### **Prerequisites**
- Python 3.12+
- OpenRouter API key (for Claude 3.7 Sonnet)
- Supabase PostgreSQL database (configured)

### **Installation**
1. **Clone and setup:**
   ```bash
   git clone <your-repo-url>
   cd pompom-ai
   pip install -e .
   ```

2. **Configure environment:**
   Copy `.env.example` to `.env` and update with your credentials:
   ```env
   TRANSPORT=sse
   HOST=0.0.0.0
   PORT=8051
   LLM_PROVIDER=openrouter
   LLM_BASE_URL=https://openrouter.ai/api/v1
   LLM_API_KEY=your-openrouter-api-key
   LLM_CHOICE=anthropic/claude-3.7-sonnet
   DATABASE_URL=your-supabase-postgresql-url
   ```

3. **Start the server:**
   ```bash
   python src/main.py
   ```

4. **Test connectivity:**
   ```powershell
   .\test_server.ps1
   ```

## 🧠 **How It Works - Detailed Explanation**

### **Architecture Overview**
```
Qodo AI ←→ MCP Protocol ←→ PomPom-AI Server ←→ Mem0 ←→ ChromaDB + PostgreSQL
```

### **Component Breakdown**

#### **1. MCP Server (`src/main.py`)**
- **FastMCP Framework**: Handles MCP protocol communication
- **SSE Transport**: Server-Sent Events for real-time communication on port 8051
- **Lifespan Management**: Initializes and manages Mem0 client connection
- **Three Core Tools**: Exposes memory operations to Qodo AI

#### **2. Memory Tools Available to Qodo AI**

**`save_memory(text: str)`**
- **Purpose**: Store any information in long-term memory
- **Usage**: When you tell Qodo AI something important to remember
- **Process**: 
  1. Receives text from Qodo AI
  2. Processes through Claude 3.7 Sonnet for fact extraction
  3. Generates embeddings using ChromaDB's built-in model
  4. Stores in both ChromaDB (vectors) and PostgreSQL (metadata)

**`get_all_memories()`**
- **Purpose**: Retrieve all stored memories for context
- **Usage**: When Qodo AI needs complete memory context
- **Process**:
  1. Queries Mem0 for all memories associated with default user
  2. Returns paginated results (50 items default)
  3. Provides full context for conversation continuity

**`search_memories(query: str, limit: int = 3)`**
- **Purpose**: Find relevant memories using semantic search
- **Usage**: When Qodo AI needs specific information
- **Process**:
  1. Converts query to embeddings
  2. Performs vector similarity search in ChromaDB
  3. Returns most relevant memories ranked by relevance

#### **3. Memory Configuration (`src/utils.py`)**

**LLM Configuration (OpenRouter + Claude)**
```python
llm_config = {
    "provider": "openai",  # OpenRouter uses OpenAI-compatible API
    "config": {
        "model": "anthropic/claude-3.7-sonnet",
        "temperature": 0.2,  # Low temperature for consistent memory processing
        "max_tokens": 1500
    }
}
```

**Embedding Configuration (ChromaDB Built-in)**
- **No external API calls**: Uses ChromaDB's default embedding function
- **Local processing**: Embeddings generated locally for privacy
- **No additional costs**: No embedding API fees

**Vector Store Configuration (ChromaDB)**
```python
vector_store_config = {
    "provider": "chroma",
    "config": {
        "collection_name": "mem0_memories",
        "path": "./chroma_db"  # Local SQLite database
    }
}
```

### **4. Data Flow When You Use Qodo AI**

**Saving a Memory:**
```
You: "Remember that I prefer PowerShell for automation tasks"
↓
Qodo AI → MCP Protocol → PomPom-AI → save_memory("I prefer PowerShell for automation tasks")
↓
Claude 3.7 Sonnet processes and extracts key facts
↓
ChromaDB generates embeddings locally
↓
Stored in: ChromaDB (vectors) + PostgreSQL (metadata)
↓
PomPom-AI Response: "Successfully saved memory: I prefer PowerShell for automation tasks"
```

**Retrieving Memories:**
```
You: "What do you know about my preferences?"
↓
Qodo AI → MCP Protocol → PomPom-AI → search_memories("preferences", limit=5)
↓
ChromaDB performs vector similarity search
↓
PomPom-AI returns relevant memories about your preferences
↓
Qodo AI uses this context to provide personalized responses
```

### **5. Storage Architecture**

**ChromaDB (Local - `./chroma_db/`)**
- **Vector embeddings**: Semantic representations of memories
- **Fast similarity search**: Sub-second query responses
- **Local SQLite**: No external dependencies
- **Collection**: `mem0_memories`

**PostgreSQL (Supabase)**
- **Metadata storage**: User associations, timestamps
- **Structured data**: Relationships and memory organization
- **Cloud backup**: Persistent storage across devices
- **Scalability**: Handles large memory datasets

## 🔧 **Memory Management Tools**

### **View Current Memories**
```bash
# Python script
python show_current_memories.py

# PowerShell script
.\show_memories.ps1
```

### **Visual Dashboard**
```bash
# Streamlit dashboard
streamlit run chroma_viewer.py

# HTML dashboard with live data
python dashboard_server.py
```

### **Server Testing**
```powershell
# Test server connectivity
.\test_server.ps1
```

## 📊 **Memory Analytics**

The system tracks:
- **Total memories stored**
- **Memory categories/collections**
- **Average memory length**
- **Search frequency patterns**
- **Memory creation timestamps**

## 🔒 **Privacy & Security**

- **Local embeddings**: No data sent to external embedding APIs
- **Encrypted storage**: PostgreSQL with SSL
- **Local processing**: ChromaDB runs entirely on your machine
- **API key security**: Environment variables only

## 🎛️ **Configuration Options**

### **Memory Processing**
- **Temperature**: 0.2 (consistent fact extraction)
- **Max tokens**: 1500 (detailed memory processing)
- **Model**: Claude 3.7 Sonnet (high-quality reasoning)

### **Search Parameters**
- **Default limit**: 3 memories per search
- **Similarity threshold**: Automatic (ChromaDB optimized)
- **Collection scope**: Single user (isolated memories)

## 🚀 **Usage Patterns with Qodo AI**

### **Personal Information**
```
"Remember that I work as a software engineer and prefer Python and PowerShell"
"I live in timezone UTC+3"
"My favorite IDE is VS Code"
```

### **Project Context**
```
"I'm working on a MCP server project using FastMCP and Mem0"
"The project uses OpenRouter for LLM and ChromaDB for vectors"
"Port 8051 is used for the SSE transport"
```

### **Preferences & Settings**
```
"I prefer detailed explanations with code examples"
"Always use PowerShell for Windows automation tasks"
"Format code blocks with syntax highlighting"
```

## 🔄 **Maintenance**

### **Regular Tasks**
- Monitor ChromaDB size (`./chroma_db/`)
- Check PostgreSQL connection health
- Review memory quality and relevance
- Update API keys as needed

### **Troubleshooting**
- **Server won't start**: Check `.env` configuration
- **Memory not saving**: Verify PostgreSQL connection
- **Search not working**: Restart server to refresh ChromaDB
- **Qodo AI can't connect**: Confirm port 8051 is open

## 📈 **Performance Optimization**

- **ChromaDB**: Optimized for <1000 memories per collection
- **PostgreSQL**: Indexed for fast metadata queries  
- **Memory size**: Optimal range 50-500 characters per memory
- **Search speed**: Sub-100ms for typical queries

## 🎯 **Best Practices**

1. **Memory Quality**: Store specific, actionable information
2. **Regular Cleanup**: Remove outdated or irrelevant memories
3. **Categorization**: Use consistent language for similar topics
4. **Testing**: Regularly test memory retrieval accuracy
5. **Backup**: PostgreSQL provides automatic cloud backup

This system transforms Qodo AI into a truly personalized assistant that remembers your preferences, project context, and important information across all conversations.

## 🐕 **Why "PomPom-AI"?**

Just like Pompompurin is known for being:
- **🤗 Friendly & Reliable** - PomPom-AI is always there to help remember what's important
- **🧠 Smart & Attentive** - Intelligently processes and organizes your memories
- **💛 Loyal Companion** - Grows smarter about your preferences over time
- **🎯 Focused & Efficient** - Quickly finds exactly what you need when you need it

**PomPom-AI** = **PomPom** (friendly like Pompompurin) + **AI** (Artificial Intelligence)