# Redis Setup for Mac M2 Air
## 🎯 Why Use Redis?
**Current Problem:** Your conversations aren't being saved because:
- Redis is enabled in config but not running
- System tries Redis → fails → creates new in-memory store each request
- In-memory store is recreated each time = no persistence
**With Redis:**
- ✅ Conversations persist across server restarts
- ✅ Faster than in-memory (optimized for this use case)
- ✅ Production-ready
- ✅ Easy to monitor and debug
- ✅ Works across multiple servers (when you scale)
**My Recommendation:** **YES, set it up now!** It's super easy on Mac and you'll learn a valuable skill.
---
## 📦 Installation (5 minutes)
### Step 1: Install Redis via Homebrew
```bash
# Install Redis
brew install redis
# Verify installation
redis-server --version
```
Expected output:
```
Redis server v=7.2.x sha=00000000:0 malloc=libc bits=64 build=xxxxx
```
### Step 2: Start Redis
**Option A: Start now (stops when you close terminal)**
```bash
redis-server
```
**Option B: Start as background service (recommended)**
```bash
# Start Redis and make it run on startup
brew services start redis
# Check if it's running
brew services list | grep redis
```
Expected output:
```
redis started <your-user> ~/Library/LaunchAgents/homebrew.mxcl.redis.plist
```
### Step 3: Verify Redis is Running
```bash
# Test connection
redis-cli ping
```
Expected output:
```
PONG
```
**If you see `PONG`, Redis is working!** ✅
---
## 🧪 Test Your Setup
### 1. Test Redis Directly
```bash
# Open Redis CLI
redis-cli
# Try some commands
127.0.0.1:6379> SET test "Hello Redis"
OK
127.0.0.1:6379> GET test
"Hello Redis"
127.0.0.1:6379> DEL test
(integer) 1
127.0.0.1:6379> exit
```
### 2. Test with Your MCP System
**Restart your servers** (both terminals):
```bash
# Terminal 1 - MCP Server
python3 -m src.mcp_server.server
# Terminal 2 - Web Chat
python3 -m src.web_chat.main
```
**Look for this log in Terminal 2:**
```json
{"backend": "redis", "event": "conversation_store_initialized", ...}
```
**NOT this:**
```json
{"backend": "memory", "event": "conversation_store_initialized", ...}
```
### 3. Test Conversation Memory
**First message:**
```bash
curl -X POST http://localhost:8002/chat \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 11836|UAc9YiEKc9zO9MvNHKQqY9WwdkxW7qQyw3mqyNK5" \
-d '{"message": "My name is John"}'
```
**Second message:**
```bash
curl -X POST http://localhost:8002/chat \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 11836|UAc9YiEKc9zO9MvNHKQqY9WwdkxW7qQyw3mqyNK5" \
-d '{"message": "What is my name?"}'
```
**Expected response:**
```json
{
"success": true,
"response": "Your name is John.",
...
}
```
**If it remembers your name, Redis is working!** 🎉
---
## 🔧 Configuration
Your current config should already be set correctly in `.env`:
```bash
# Redis Configuration
REDIS_ENABLED=true
REDIS_URL=redis://localhost:6379/0
REDIS_TTL_CONVERSATIONS=86400 # 24 hours
REDIS_TTL_CACHE=900 # 15 minutes
```
**No changes needed!** Just start Redis.
---
## 🛠️ Common Commands
### Start/Stop Redis
```bash
# Start Redis (background service)
brew services start redis
# Stop Redis
brew services stop redis
# Restart Redis
brew services restart redis
# Check status
brew services list | grep redis
```
### Monitor Redis
```bash
# Watch Redis in real-time
redis-cli monitor
# Check memory usage
redis-cli info memory
# See all keys
redis-cli keys "*"
# See conversation keys
redis-cli keys "conversation:*"
```
### Clear All Data
```bash
# Clear all Redis data (careful!)
redis-cli FLUSHALL
# Clear just conversation data
redis-cli --scan --pattern "conversation:*" | xargs redis-cli DEL
```
---
## 🐛 Troubleshooting
### Issue 1: "Connection refused"
**Error:**
```
Error 61 connecting to localhost:6379. Connection refused.
```
**Fix:**
```bash
# Check if Redis is running
brew services list | grep redis
# If not running, start it
brew services start redis
# Verify
redis-cli ping
```
### Issue 2: "Command not found: redis-server"
**Fix:**
```bash
# Install Redis
brew install redis
# Add to PATH (if needed)
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```
### Issue 3: Port already in use
**Error:**
```
Address already in use
```
**Fix:**
```bash
# Find what's using port 6379
lsof -i :6379
# Kill the process
kill -9 <PID>
# Or use a different port in .env
REDIS_URL=redis://localhost:6380/0
```
---
## 📊 Monitoring Your Conversations
### View Stored Conversations
```bash
# List all conversation keys
redis-cli keys "conversation:*"
# View a specific conversation
redis-cli GET "conversation:860:141"
# Pretty print JSON
redis-cli GET "conversation:860:141" | python3 -m json.tool
```
### Check Memory Usage
```bash
redis-cli info memory | grep used_memory_human
```
### See Active Connections
```bash
redis-cli client list
```
---
## 🎓 Learning Redis (Optional)
Since you're new to Redis, here are some quick concepts:
### What is Redis?
- **In-memory database** (super fast!)
- **Key-value store** (like a giant dictionary)
- **Supports TTL** (automatic expiration)
- **Persistent** (can save to disk)
### Basic Commands
```bash
# String operations
SET key value
GET key
DEL key
# With expiration (TTL in seconds)
SETEX key 3600 value # Expires in 1 hour
# Check if key exists
EXISTS key
# Get TTL
TTL key
# List all keys (careful in production!)
KEYS *
```
### How MCP Uses Redis
```
conversation:860:141 → [
{"role": "user", "content": "Hello"},
{"role": "assistant", "content": "Hi!"}
]
```
- **Key format:** `conversation:{user_id}:{org_id}`
- **Value:** JSON array of messages
- **TTL:** 24 hours (configurable)
---
## ✅ Quick Start Checklist
- [ ] Install Redis: `brew install redis`
- [ ] Start Redis: `brew services start redis`
- [ ] Verify: `redis-cli ping` → `PONG`
- [ ] Restart MCP servers
- [ ] Test conversation memory
- [ ] Check logs for "redis" backend
---
## 🚀 Next Steps
### Now (Recommended)
1. **Install Redis** (5 minutes)
2. **Test conversation memory**
3. **Keep using it!**
### Later (When Ready)
- Learn Redis data structures (lists, sets, hashes)
- Set up Redis monitoring (RedisInsight GUI)
- Configure Redis persistence
- Learn about Redis Cluster (for scaling)
---
## 💡 Why This Matters
**Without Redis:**
```
User: "My name is John"
AI: "Nice to meet you, John!"
User: "What's my name?"
AI: "I don't know your name." ← Lost the conversation!
```
**With Redis:**
```
User: "My name is John"
AI: "Nice to meet you, John!"
User: "What's my name?"
AI: "Your name is John." ← Remembers! ✅
```
---
## 🎉 Summary
**Install Redis now because:**
1. ✅ Super easy on Mac (5 minutes)
2. ✅ Fixes your conversation memory issue
3. ✅ Production-ready from day 1
4. ✅ Valuable skill to learn
5. ✅ No code changes needed!
**Just run:**
```bash
brew install redis
brew services start redis
redis-cli ping # Should return PONG
```
**Then restart your servers and test!**
---
## 📚 Resources
- **Redis Official Docs:** https://redis.io/docs/
- **Redis on Mac:** https://redis.io/docs/getting-started/installation/install-redis-on-mac-os/
- **Redis CLI Tutorial:** https://redis.io/docs/ui/cli/
- **RedisInsight (GUI):** https://redis.io/insight/
---
**Need help?** Just ask! Redis is simpler than you think. 🚀
