README_SPACES.md

# 🤖 Memory Chat - Hugging Face Spaces

A conversational AI application built with Hugging Face models that records and remembers user memories. Deployed on Hugging Face Spaces with persistent storage.

## 🚀 Features

- 🤖 **Hugging Face Integration**: Uses DialoGPT for natural conversations
- 💾 **Memory System**: Automatically records important information from conversations
- 📚 **Memory Management**: View, search, and manage your memories
- 🔍 **Smart Retrieval**: AI recalls relevant memories during conversations
- ☁️ **Persistent Storage**: Memories persist between sessions on the Space

## 🎯 How It Works

1. **Conversation**: Chat naturally with the AI using Hugging Face models
2. **Memory Detection**: The system automatically detects important information using keywords and patterns
3. **Memory Storage**: Important details are stored as vector embeddings with metadata
4. **Memory Retrieval**: When relevant, the AI recalls past memories to provide context
5. **Timeline View**: View your memory timeline and statistics

## 💡 Memory Recording Examples

The system automatically remembers:
- Personal preferences: "I love pizza and hate mushrooms"
- Important facts: "My birthday is December 15th"
- Locations: "I live in New York"
- Work/Study: "I work at Google", "I study computer science"
- Favorites: "My favorite color is blue"

## 🏗️ Architecture

```
space_app.py          # Main application (optimized for HF Spaces)
├── memory_manager.py # Memory storage and retrieval
├── chat_interface.py # Hugging Face model integration
├── config.py        # Configuration settings
└── space_requirements.txt # Dependencies for HF Spaces
```

## 📦 Dependencies

- **Core**: torch, transformers, gradio
- **Memory**: faiss-cpu, sentence-transformers
- **Utilities**: numpy, pandas, python-dotenv, rich

## 🔧 Local Development

### Installation

1. Clone this repository
2. Install dependencies:
   ```bash
   pip install -r space_requirements.txt
   ```
3. Run the application:
   ```bash
   python space_app.py
   ```

### Testing

Run the test script to verify everything works:
```bash
python test_app.py
```

## ☁️ Deploying to Hugging Face Spaces

### Option 1: Direct Upload (Recommended)

1. **Go to [Hugging Face Spaces](https://huggingface.co/spaces)**
2. **Click "Create new Space"**
3. **Choose a name** for your Space
4. **Select "Gradio"** as the Space type
5. **Choose "Public"** visibility
6. **Upload the files**:
   - `space_app.py` → Rename to `app.py`
   - `memory_manager.py`
   - `chat_interface.py`
   - `config.py`
   - `space_requirements.txt` → Rename to `requirements.txt`
   - `README_SPACES.md` → Rename to `README.md`

7. **Commit and push** to create your Space!

### Option 2: Git Clone

1. **Create a new Space** on Hugging Face
2. **Clone your Space locally**:
   ```bash
   git clone https://huggingface.co/spaces/your-username/your-space-name
   cd your-space-name
   ```

3. **Copy the files**:
   ```bash
   cp /path/to/your/hf-memory-chat/space_app.py app.py
   cp /path/to/your/hf-memory-chat/memory_manager.py .
   cp /path/to/your/hf-memory-chat/chat_interface.py .
   cp /path/to/your/hf-memory-chat/config.py .
   cp /path/to/your/hf-memory-chat/space_requirements.txt requirements.txt
   cp /path/to/your/hf-memory-chat/README_SPACES.md README.md
   ```

4. **Push to HF**:
   ```bash
   git add .
   git commit -m "Initial commit: Memory Chat application"
   git push origin main
   ```

## ⚙️ Configuration

### Environment Variables

HF Spaces automatically sets up the environment, but you can customize:

- `PORT`: The port to run on (automatically set by Spaces)
- `SPACE_ID`: Space identifier (automatically set)

### Model Configuration

The application uses `microsoft/DialoGPT-small` by default, which is optimized for:
- Fast loading times
- Good conversational quality
- Lower resource usage

## 🧠 Memory System Details

### Storage
- **Location**: `/tmp/memories` on HF Spaces (persistent)
- **Format**: JSON for memories, Markdown for timeline
- **Indexing**: FAISS for fast similarity search

### Memory Types
- **General**: General information and facts
- **Conversation**: Important details from chats
- **Preferences**: Likes, dislikes, favorites
- **Important**: Critical information marked as important

### Automatic Recording
Memories are automatically recorded when:
- User explicitly requests memory recording
- Important keywords are detected
- Personal information patterns are found
- High importance score is calculated

## 🎨 UI Features

### Chat Interface
- Clean, responsive design
- Send messages with Enter key
- Clear conversation history
- Automatic memory recording indicators

### Memory Management
- View memory statistics
- See recent memories
- Clear all memories
- Refresh memory display

### About Section
- Detailed documentation
- Usage instructions
- Feature explanations

## 🚀 Performance Optimizations

### For HF Spaces
- **Model Selection**: Uses DialoGPT-small for faster loading
- **Memory Storage**: Optimized for persistent storage
- **Error Handling**: Graceful fallbacks for model loading
- **Resource Management**: Efficient memory usage

### Local Development
- **GPU Support**: Automatic GPU detection if available
- **Caching**: Model loading optimization
- **Error Recovery**: Fallback to simple text generation

## 🐛 Troubleshooting

### Common Issues

1. **Model Loading Errors**
   - Usually temporary network issues
   - Application falls back to simple text generation
   - Try refreshing the page

2. **Memory Not Persisting**
   - Ensure you're using the correct app.py file
   - Check that `/tmp/memories` directory is writable
   - Verify Space has sufficient storage

3. **Slow Responses**
   - First-time model loading can be slow
   - Subsequent requests are cached
   - Consider using smaller models for faster responses

### Getting Help

- **Hugging Face Community**: [HF Forums](https://discuss.huggingface.co/)
- **GitHub Issues**: Report bugs and feature requests
- **Documentation**: Check the About section in the app

## 📄 License

MIT License - see LICENSE file for details

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for your changes
5. Submit a pull request

## 🙏 Acknowledgments

- **Hugging Face**: For providing the amazing ecosystem and Spaces platform
- **Microsoft**: For the DialoGPT models
- **FAISS Team**: For efficient similarity search
- **Gradio Team**: For the excellent UI framework

---

**Built with ❤️ using Hugging Face, Gradio, and the power of AI memories**