# ChromaDB Memory Service

A Python microservice that provides semantic search and memory storage for the AI assistant using ChromaDB vector database.

## Features

- **Multimodal Memory**: Store and search text, images, documents, and web content
- **Semantic Search**: Find relevant information by meaning, not just keywords
- **OpenAI Integration**: Uses OpenAI embeddings and vision API
- **REST API**: Simple HTTP endpoints for easy integration
- **Persistent Storage**: Data persists between restarts

## Quick Start

### 1. Install Dependencies

```bash
cd memory-service
chmod +x install.sh
./install.sh
```

### 2. Set Environment Variables

```bash
export OPENAI_API_KEY="your-openai-api-key"
export CHROMA_PERSIST_DIR="./chroma_db"
export PORT=5050
```

### 3. Start the Service

```bash
chmod +x start.sh
./start.sh
```

The service will start on `http://localhost:5050`

## API Endpoints

### Health Check
```
GET /health
```
Returns service status and configuration.

### Embed Text
```
POST /embed
Content-Type: application/json

{
  "content": "Text to embed",
  "metadata": {
    "type": "message",
    "conv_id": "conv_123",
    "ref_id": "msg_456"
  }
}
```

### Embed Image
```
POST /embed_image
Content-Type: application/json

{
  "image_path": "/path/to/image.jpg",
  "metadata": {
    "type": "image",
    "conv_id": "conv_123"
  }
}
```

### Search
```
POST /search
Content-Type: application/json

{
  "query": "hotel booking Romania",
  "limit": 10,
  "filters": {
    "type": "message"
  }
}
```

### Batch Add
```
POST /add_batch
Content-Type: application/json

{
  "items": [
    {
      "content": "Text 1",
      "metadata": {"type": "message"}
    },
    {
      "content": "Text 2", 
      "metadata": {"type": "document"}
    }
  ]
}
```

### Delete
```
POST /delete
Content-Type: application/json

{
  "id": "embedding_id_to_delete"
}
```

### Statistics
```
GET /stats
```
Returns collection statistics.

### Clear Collection
```
POST /clear
```
⚠️ **Warning**: This deletes all data!

## Configuration

### Environment Variables

- `OPENAI_API_KEY`: Your OpenAI API key (required for embeddings and vision)
- `CHROMA_PERSIST_DIR`: Directory to store ChromaDB data (default: `./chroma_db`)
- `PORT`: Service port (default: 5050)
- `DEBUG`: Enable debug mode (default: false)

### Memory Types

The service supports these content types:

- `message`: Chat messages
- `document`: Files and documents
- `image`: Images with vision analysis
- `video`: Video frames
- `web`: Scraped web content
- `search`: Search results

## Integration with PHP

The PHP application automatically integrates with this service through the `MemoryManager` class:

```php
$memoryManager = new MemoryManager($log, 'http://localhost:5050', $openaiApiKey);

// Embed text
$id = $memoryManager->embedText("Hello world", ['type' => 'message']);

// Search
$results = $memoryManager->searchSimilar("hello", 10);

// Embed image
$id = $memoryManager->embedImage("/path/to/image.jpg", "Image description");
```

## Troubleshooting

### Service Won't Start
1. Check if Python 3.8+ is installed
2. Verify all dependencies are installed: `pip install -r requirements.txt`
3. Check if port 5050 is available
4. Ensure OpenAI API key is set

### Embeddings Fail
1. Verify OpenAI API key is valid
2. Check internet connection
3. Ensure API key has sufficient credits

### Search Returns No Results
1. Verify data was embedded successfully
2. Check if collection is empty: `GET /stats`
3. Try broader search terms

### Performance Issues
1. Check available disk space
2. Monitor memory usage
3. Consider reducing batch sizes
4. Check ChromaDB logs

## Development

### Running in Development Mode
```bash
export DEBUG=true
python3 chroma_service.py
```

### Adding New Features
1. Add new endpoints to `chroma_service.py`
2. Update the `MemoryManager` class in PHP
3. Add corresponding API endpoints in `index.php`
4. Update this README

## Cost Considerations

- **Text Embeddings**: ~$0.02 per 1M tokens (very cheap)
- **Vision API**: ~$0.15 per 1K tokens (reasonable for images)
- **Storage**: Local ChromaDB (free)

For 10,000 messages with images: ~$0.50 total cost.

## Security

- Service runs on localhost by default
- No authentication (intended for local use)
- For production, add authentication and HTTPS
- Validate all input data
- Rate limit API calls if needed


