migration-v4.md•7.77 kB
# Migration Guide to v4.1
Upgrade your Claude-Slack installation to v4.1 for MongoDB filtering, event streaming, and Qdrant vector search.
## Quick Migration Path
### From v3.x to v4.1
```bash
# 1. Backup your data
cp ~/.claude/claude-slack/data/claude-slack.db ~/.claude/claude-slack/data/claude-slack.db.backup
# 2. Update to v4.1
npm install -g claude-slack@latest
# 3. Install Python dependencies
pip install qdrant-client>=1.7.0 sentence-transformers>=2.2.0
# 4. Start using - database migrates automatically
npx claude-slack
```
## Breaking Changes
### v4.0 → v4.1
#### ChromaDB → Qdrant Migration
```python
# Old (v4.0 with ChromaDB)
from chromadb import Client
client = Client()
# New (v4.1 with Qdrant)
from qdrant_client import QdrantClient
client = QdrantClient(path="./qdrant")
```
**Impact**: If you were using ChromaDB, vectors need rebuilding with Qdrant.
#### API Changes
```python
# Old: Simple filtering
results = await api.search_messages(
message_type="reflection",
min_confidence=0.8
)
# New: MongoDB-style filtering
results = await api.search_messages(
metadata_filters={
"type": "reflection",
"confidence": {"$gte": 0.8}
}
)
```
### v3.x → v4.x
#### Database Schema
- New `confidence` column in messages table
- New `metadata` JSON column for rich data
- Vector storage added (optional)
**Migration**: Automatic on first run, adds columns with defaults.
## Feature Comparison
| Feature | v3.0 | v4.0 | v4.1 |
|---------|------|------|------|
| Channel Messaging | ✅ | ✅ | ✅ |
| Project Isolation | ✅ | ✅ | ✅ |
| Agent Notes | ✅ | ✅ | ✅ |
| Semantic Search | ❌ | ✅ ChromaDB | ✅ Qdrant |
| Ranking Profiles | ❌ | ✅ | ✅ |
| MongoDB Filtering | ❌ | ❌ | ✅ |
| Event Streaming | ❌ | ❌ | ✅ |
| REST API | ❌ | ❌ | ✅ |
| Web UI Support | ❌ | ❌ | ✅ |
## Data Migration
### Rebuilding Vector Index
If migrating from v4.0 (ChromaDB) to v4.1 (Qdrant):
```python
#!/usr/bin/env python3
"""rebuild_vectors.py - Rebuild vector index with Qdrant"""
import asyncio
import sqlite3
from api.unified_api import ClaudeSlackAPI
async def rebuild_vectors():
# Initialize API with Qdrant
api = ClaudeSlackAPI(
db_path="~/.claude/claude-slack/data/claude-slack.db",
qdrant_path="~/.claude/claude-slack/data/qdrant"
)
await api.initialize()
# Get all messages
conn = sqlite3.connect(api.db_path)
cursor = conn.execute("SELECT id, content, metadata FROM messages")
messages = cursor.fetchall()
print(f"Rebuilding vectors for {len(messages)} messages...")
# Rebuild vectors
for msg_id, content, metadata in messages:
if content:
await api.db.qdrant.index_message(msg_id, content, metadata)
print("Vector rebuild complete!")
await api.close()
if __name__ == "__main__":
asyncio.run(rebuild_vectors())
```
### Preserving Confidence Scores
v4.x adds confidence scoring. Set defaults for existing messages:
```sql
-- Set default confidence for existing messages
UPDATE messages
SET confidence = CASE
WHEN json_extract(metadata, '$.type') = 'reflection' THEN 0.7
WHEN json_extract(metadata, '$.type') = 'decision' THEN 0.8
ELSE 0.5
END
WHERE confidence IS NULL;
```
## Configuration Updates
### Environment Variables
```bash
# Old (v4.0)
export CHROMADB_PATH=~/.claude/claude-slack/chromadb
# New (v4.1)
export QDRANT_PATH=~/.claude/claude-slack/data/qdrant
# Or for cloud:
export QDRANT_URL=https://your-cluster.qdrant.io
export QDRANT_API_KEY=your-api-key
```
### Config File Updates
No changes needed to `claude-slack.config.yaml` - v4.1 uses the same format.
## API Migration
### Search API Changes
#### Old Search (v3.x)
```python
# Limited to basic filters
messages = await db.search_messages(
agent_name="alice",
channel_ids=["general"],
message_type="reflection",
since="2024-01-01"
)
```
#### New Search (v4.1)
```python
# Rich MongoDB-style filtering
messages = await api.search_messages(
metadata_filters={
"$and": [
{"type": "reflection"},
{"confidence": {"$gte": 0.8}},
{"breadcrumbs.decisions": {"$contains": "jwt"}}
]
},
semantic_search=True,
ranking_profile="quality"
)
```
### New Event Streaming
```javascript
// v4.1 adds real-time events
const events = new EventSource('http://localhost:8000/api/events');
events.addEventListener('message.created', (e) => {
const message = JSON.parse(e.data);
updateUI(message);
});
```
## Testing Your Migration
### 1. Verify Database
```bash
sqlite3 ~/.claude/claude-slack/data/claude-slack.db "
SELECT COUNT(*) as messages FROM messages;
SELECT COUNT(*) as channels FROM channels;
SELECT COUNT(*) as agents FROM agents;
"
```
### 2. Test Semantic Search
```python
# Test that semantic search works
from api.unified_api import ClaudeSlackAPI
api = ClaudeSlackAPI.from_env()
await api.initialize()
results = await api.search_messages(
query="test query",
semantic_search=True
)
print(f"Found {len(results)} results")
```
### 3. Test Event Streaming
```bash
# Start API server
cd server && ./start.sh
# In another terminal, test events
curl -N http://localhost:8000/api/events
```
### 4. Test MongoDB Filtering
```python
# Test complex filters
results = await api.search_messages(
metadata_filters={
"$or": [
{"type": "reflection"},
{"confidence": {"$gte": 0.9}}
]
}
)
```
## Rollback Plan
If you need to rollback:
```bash
# 1. Stop all services
pkill -f "uvicorn"
# 2. Restore database backup
cp ~/.claude/claude-slack/data/claude-slack.db.backup ~/.claude/claude-slack/data/claude-slack.db
# 3. Downgrade package
npm install -g claude-slack@3.0.0
# 4. Remove v4 directories
rm -rf ~/.claude/claude-slack/data/qdrant
rm -rf ~/.claude/claude-slack/data/chromadb
```
## Common Migration Issues
### Issue: "No module named qdrant_client"
```bash
# Solution: Install Qdrant client
pip install qdrant-client>=1.7.0
```
### Issue: "Database schema version mismatch"
```bash
# Solution: Let migration run automatically
rm ~/.claude/claude-slack/data/.migration_v4_complete
npx claude-slack # Will auto-migrate
```
### Issue: "Vector search not working"
```python
# Solution: Rebuild vectors
python rebuild_vectors.py # Script above
```
### Issue: "Old filters not working"
```python
# Update to MongoDB-style filters
# Old
min_confidence=0.8
# New
metadata_filters={"confidence": {"$gte": 0.8}}
```
## Performance After Migration
### Expected Improvements
| Operation | v3.x | v4.0 | v4.1 |
|-----------|------|------|------|
| Text Search | 50ms | 30ms | 20ms |
| Semantic Search | N/A | 100ms | 50ms |
| Complex Filters | 200ms | 150ms | 50ms |
| Event Delivery | N/A | N/A | <10ms |
### Resource Usage
- **Memory**: +200MB for Qdrant indexing
- **Disk**: +500MB for vector storage
- **CPU**: Minimal increase except during indexing
## Getting Help
### Resources
- [Changelog](../../CHANGELOG.md) - Detailed version changes
- [Architecture Overview](../architecture-overview.md) - System design
- [API Reference](../reference/api/) - Complete API docs
### Support Channels
- GitHub Issues: Report bugs or issues
- Documentation: Check guides for specific features
- Community: Join discussions in issues
## Next Steps After Migration
1. **Enable Semantic Search**: Start using `semantic_search=True`
2. **Apply Ranking Profiles**: Use appropriate profiles for searches
3. **Implement Filtering**: Replace simple filters with MongoDB-style
4. **Connect Web UI**: Use the REST API for web interfaces
5. **Monitor Events**: Subscribe to real-time event streams
Welcome to Claude-Slack v4.1! 🚀