# Session Buddy - Quick Start Guide
Get up and running with the Session Management MCP server in under 5 minutes.
## What You'll Get
- **🚀 One-command session initialization** with project analysis and dependency management
- **🧠 Cross-session memory** with semantic search through all your conversations
- **📊 Quality monitoring** with automatic checkpoints and workflow optimization
- **🔧 Zero-configuration setup** that works with any project structure
## Installation
### Option 1: From Source (Recommended)
```bash
# Clone and install
git clone https://github.com/lesleslie/session-buddy.git
cd session-buddy
uv sync
# Or install with development/testing tools
uv sync --group dev
# Verify installation
python -c "from session_buddy.server import mcp; print('✅ Ready to go!')"
```
### Option 2: With pip
```bash
# Install from PyPI
pip install session-buddy
```
## Search Capabilities
Session Buddy includes two search modes for finding past conversations:
**Text Search (Default ✅)**
- Fast keyword-based search using DuckDB FTS5
- Works out of the box with no additional setup
- Highly effective for most use cases
**Semantic Search (Optional ✅)**
- Concept-based search using AI embeddings
- **No PyTorch required** - uses pre-converted ONNX models
- Enhanced for finding conceptually similar content
**Setup for Semantic Search:**
```bash
python scripts/download_embedding_model.py
```
This downloads the Xenova/all-MiniLM-L6-v2 model (~100MB) for semantic search.
**Note**: Text search is the default and works excellently. Semantic search is an optional enhancement that provides conceptual understanding beyond keywords.
## Configure Claude Code
Add to your `.mcp.json` configuration:
```json
{
"mcpServers": {
"session-buddy": {
"command": "python",
"args": ["-m", "session_buddy.server"],
"cwd": "/path/to/session-buddy",
"env": {
"PYTHONPATH": "/path/to/session-buddy"
}
}
}
}
```
> **💡 Pro Tip**: Use absolute paths to avoid configuration issues
## First Session
### 1. Initialize Your Session
```
/session-buddy:start
```
This single command:
- ✅ Analyzes your project structure and health
- ✅ Syncs all dependencies (UV, npm, etc.)
- ✅ Sets up conversation memory system
- ✅ Configures automated quality checkpoints
### 2. Work Normally
Code, debug, and develop as usual. The MCP server silently:
- 🧠 **Remembers everything** - All conversations are stored with semantic search
- 📊 **Monitors quality** - Tracks project health and workflow efficiency
- 🔧 **Reduces friction** - Learns your permissions to minimize prompts
### 3. Get Smart Recommendations
```
/session-buddy:checkpoint
```
Every 30-45 minutes, get:
- Real-time quality scoring and optimization tips
- Workflow drift detection and corrections
- Automatic git checkpoints with progress tracking
### 4. Search Your History
```
/session-buddy:quick_search how did I implement authentication last week?
```
Instantly find:
- 🎯 **Relevant conversations** using semantic similarity (not just keywords)
- 📅 **Recent context** with time-decay prioritization
- 🔗 **Cross-project insights** from related work
### 5. End Gracefully
```
/session-buddy:end
```
Automatic cleanup with:
- 📋 **Handoff documentation** for session continuity
- 🎓 **Learning capture** across key insight categories
- 🧹 **Workspace optimization** and memory persistence
## Essential Commands
| Command | Purpose | When to Use |
|---------|---------|-------------|
| `/session-buddy:start` | Full session setup | Start of every session |
| `/session-buddy:checkpoint` | Quality monitoring | Every 30-45 minutes |
| `/session-buddy:quick_search` | Search conversations | When you need past context |
| `/session-buddy:store_reflection` | Save important insights | After solving tough problems |
| `/session-buddy:end` | Session cleanup | End of every session |
## Power User Features
### Smart Memory System
- **Local embeddings** - No external API calls, complete privacy
- **Vector search** - Semantic similarity, not just text matching
- **Cross-project history** - Find insights across all your repositories
- **Automatic tagging** - Content is intelligently organized
### Workflow Intelligence
- **Quality scoring** - Real-time project health monitoring
- **Permission learning** - Reduces repetitive permission prompts
- **Context preservation** - Maintains state across interruptions
- **Git integration** - Automatic checkpoints with meaningful commit messages
### Advanced Search
```
/session-buddy:quick_search Redis caching strategies
/session-buddy:search_by_file src/auth/middleware.py
/session-buddy:search_by_concept "error handling patterns"
```
## Troubleshooting
### Memory/Embeddings Not Working
```bash
# Ensure all dependencies are installed (embeddings are included by default)
uv sync
# Or reinstall with pip
pip install session-buddy
```
### Server Won't Start
```bash
# Check imports
python -c "import session_buddy; print('Import successful')"
# Verify path in .mcp.json
ls /path/to/session-buddy/session_buddy/server.py
```
### No Conversations Found
- Run `/session-buddy:start` first to initialize the database
- Check `~/.claude/data/` directory exists and is writable
## What's Next?
- 📚 **[MCP Tools Reference](MCP_TOOLS_REFERENCE.md)** - Complete guide to all available commands
- 🏗️ **[Architecture Guide](../developer/ARCHITECTURE.md)** - Deep dive into how it all works
- 🔧 **[Configuration Reference](CONFIGURATION.md)** - Advanced setup options
- 🤝 **[Integration Guide](../developer/INTEGRATION.md)** - Connect with your existing tools
## Support
- 🐛 **Issues**: [GitHub Issues](https://github.com/lesleslie/session-buddy/issues)
- 💬 **Discussions**: [GitHub Discussions](https://github.com/lesleslie/session-buddy/discussions)
- 📖 **Documentation**: [Full Documentation](../../README.md)
______________________________________________________________________
**Ready to supercharge your Claude Code sessions?** Run `/session-buddy:start` and experience the difference! 🚀
