Session Buddy

# Session Buddy - MCP Tools Reference Complete reference guide for all Session Management MCP tools. Use these slash commands directly in Claude Code for comprehensive session management and intelligent conversation memory. ## 🚀 Core Session Management ### `/session-buddy:start` - Session Initialization **Purpose**: Complete session setup with project analysis and dependency management **Usage**: ``` /session-buddy:start ``` **What it does**: - ✅ **Project Analysis**: Scans and analyzes your project structure, health, and maturity - ✅ **Dependency Management**: Syncs UV, npm, pip, and other package managers automatically - ✅ **Memory System**: Initializes conversation storage with semantic search capabilities - ✅ **Permission Setup**: Configures trusted operations to reduce future prompts - ✅ **Quality Baseline**: Establishes project health metrics for monitoring **Returns**: - Project context analysis with health score (0-100) - Dependencies synchronization status - Memory system initialization confirmation - Personalized recommendations based on project type **💡 Best Practice**: Run this at the start of every Claude Code session ______________________________________________________________________ ### `/session-buddy:checkpoint` - Quality Monitoring **Purpose**: Mid-session quality assessment with workflow optimization **Usage**: ``` /session-buddy:checkpoint ``` **What it does**: - 📊 **Quality Scoring**: Real-time analysis of project health, permissions, and tool availability - 🔄 **Workflow Analysis**: Detects drift from optimal development patterns - 📝 **Git Checkpoints**: Automatically creates meaningful commit with progress metadata - 🎯 **Optimization Tips**: Provides specific recommendations for workflow improvements - ⏱️ **Progress Tracking**: Monitors development velocity and goal alignment **Returns**: - Multi-dimensional quality score breakdown - Workflow optimization recommendations - Git checkpoint confirmation (if in repository) - Personalized productivity insights **💡 Best Practice**: Run every 30-45 minutes during active development ______________________________________________________________________ ### `/session-buddy:end` - Session Cleanup **Purpose**: Comprehensive session termination with learning capture **Usage**: ``` /session-buddy:end ``` **What it does**: - 📋 **Handoff Documentation**: Creates detailed session summary for continuity - 🎓 **Learning Extraction**: Captures key insights, solutions, and patterns discovered - 🧹 **Workspace Cleanup**: Optimizes temporary files and session artifacts - 💾 **Memory Persistence**: Ensures all conversations are properly stored and indexed - 📈 **Final Assessment**: Provides comprehensive session quality report **Returns**: - Final quality assessment and session metrics - Handoff file path for future reference - Learning insights categorized by type - Memory persistence confirmation **💡 Best Practice**: Always run at the end of development sessions ______________________________________________________________________ ### `/session-buddy:status` - Session Overview **Purpose**: Current session status with comprehensive health checks **Usage**: ``` /session-buddy:status ``` **What it does**: - 🔍 **Session State**: Reports current session status and active features - 🏗️ **Project Context**: Analyzes current project structure and health - 🛠️ **Tool Availability**: Lists available MCP tools and their status - 🧠 **Memory Status**: Shows conversation storage and embedding system health - 🔐 **Permissions**: Displays trusted operations and security settings **Returns**: - Complete session state overview - Project health diagnostics - Available tools inventory - Memory system statistics - Permission and security status **💡 Best Practice**: Use when resuming sessions or troubleshooting issues ## 🧠 Memory & Search System Start with `/session-buddy:quick_search` or `/session-buddy:search_summary` to get fast signal, then pivot to more focused tools like `/session-buddy:search_by_concept` or `/session-buddy:search_by_file` for deeper retrieval. ______________________________________________________________________ ### `/session-buddy:store_reflection` - Save Insights **Purpose**: Store important insights and solutions for future reference **Usage**: ``` /session-buddy:store_reflection [content] [--tags=tag1,tag2,tag3] ``` **Parameters**: - `content` (required): The insight, solution, or important information to store - `tags` (optional): Comma-separated tags for organization and retrieval **Examples**: ``` /session-buddy:store_reflection "JWT refresh token rotation pattern: use sliding window expiration with Redis storage for optimal security/UX balance" --tags=auth,jwt,security,redis /session-buddy:store_reflection "Database migration best practice: always include rollback scripts and test on production-like data volumes" /session-buddy:store_reflection "React state management: use Zustand for simple cases, Redux Toolkit for complex state with time-travel debugging" --tags=react,state,frontend ``` **What it does**: - 💾 **Persistent Storage**: Saves insights to searchable knowledge base - 🏷️ **Smart Tagging**: Automatically extracts relevant tags from content - 🔍 **Searchable**: Instantly findable via semantic search - 📊 **Cross-Reference**: Links to related conversations and contexts - 🧠 **AI-Enhanced**: Generates embeddings for precise retrieval **Returns**: - Confirmation of storage with unique reflection ID - Applied tags (automatic + manual) - Embedding generation status - Storage timestamp and metadata **💡 Best Practice**: Use immediately after solving complex problems or gaining important insights ______________________________________________________________________ ### `/session-buddy:quick_search` - Fast Overview Search **Purpose**: Quick search with count and top result for rapid context assessment **Usage**: ``` /session-buddy:quick_search [query] [--project=current] [--similarity=0.7] ``` **Examples**: ``` /session-buddy:quick_search Docker deployment strategies /session-buddy:quick_search testing patterns --project=current ``` **What it does**: - ⚡ **Fast Results**: Returns immediately with count and best match - 📊 **Overview Mode**: Gives you the lay of the land without detail - 🎯 **Relevance Check**: Tells you if deeper search is worth it - 🔄 **Progressive Discovery**: Sets up for detailed search if needed **Returns**: - Total count of relevant conversations - Single best matching result - Indication if more results are available - Cache key for retrieving additional results **💡 Best Practice**: Use first to gauge available context before deeper searches ______________________________________________________________________ ### `/session-buddy:get_more_results` - Pagination **Purpose**: Retrieve additional results after initial searches **Usage**: ``` /session-buddy:get_more_results [query] [--offset=3] [--limit=5] ``` **What it does**: - 📄 **Pagination**: Efficiently retrieves additional search results - 🎯 **Consistent Ranking**: Maintains same relevance ordering - ⚡ **Performance**: Uses cached search state for speed - 📊 **Progressive Loading**: Load results as needed ## 🔍 Specialized Search Tools ### `/session-buddy:search_by_file` - File-Specific Search **Purpose**: Find all conversations that discussed specific files **Usage**: ``` /session-buddy:search_by_file [file_path] [--limit=10] [--project=current] ``` **Examples**: ``` /session-buddy:search_by_file src/auth/middleware.py /session-buddy:search_by_file package.json --limit=5 /session-buddy:search_by_file components/UserDashboard.tsx --project=current ``` **What it does**: - 📁 **File-Centric**: Finds conversations where specific files were discussed - 🔍 **Change History**: Shows evolution of file-related decisions - 🏗️ **Context Reconstruction**: Rebuilds the story of how files developed - 🔗 **Relationship Mapping**: Shows connections between related files **💡 Best Practice**: Use before modifying existing files to understand previous decisions ______________________________________________________________________ ### `/session-buddy:search_by_concept` - Concept Search **Purpose**: Explore conversations about development concepts and patterns **Usage**: ``` /session-buddy:search_by_concept [concept] [--include_files] [--limit=10] [--project=current] ``` **Examples**: ``` /session-buddy:search_by_concept "error handling patterns" /session-buddy:search_by_concept authentication --include_files --limit=15 /session-buddy:search_by_concept "state management" --project=current ``` **What it does**: - 🎯 **Concept-Focused**: Searches for abstract development concepts - 📚 **Pattern Discovery**: Finds how concepts were implemented across projects - 🔗 **Cross-Reference**: Shows related files and implementations when requested - 🧠 **Knowledge Mining**: Extracts architectural decisions and reasoning **💡 Best Practice**: Use when exploring how to implement new concepts or patterns ## 📊 Analytics & Insights ### `/session-buddy:search_summary` - Aggregated Insights **Purpose**: Get high-level insights without individual result details **Usage**: ``` /session-buddy:search_summary [query] [--project=current] [--similarity=0.7] ``` **What it does**: - 📈 **Aggregated View**: Provides summary statistics and insights - 🎯 **Pattern Recognition**: Identifies common themes and approaches - 📊 **Trend Analysis**: Shows evolution of techniques over time - 🧠 **Knowledge Synthesis**: Combines insights from multiple conversations **💡 Best Practice**: Use for high-level understanding of how topics have been handled ______________________________________________________________________ ### `/session-buddy:reflection_stats` - Knowledge Base Statistics **Purpose**: Get comprehensive statistics about your stored knowledge **Usage**: ``` /session-buddy:reflection_stats ``` **What it does**: - 📊 **Storage Overview**: Total conversations, reflections, and projects tracked - 🧠 **Memory Health**: Embedding coverage and system performance - 📅 **Timeline**: Oldest to most recent conversation spans - 💾 **Usage Metrics**: Storage utilization and optimization opportunities **Returns**: - Total conversations and reflections stored - Number of projects tracked - Embedding system coverage percentage - Storage size and health metrics - Timeline of stored knowledge **💡 Best Practice**: Use periodically to understand the scope of your knowledge base ## 🔧 Advanced Features ### Smart Permission System The MCP server learns your permission preferences over time: - ✅ **UV sync operations** - Automatically trusted after first approval - ✅ **Git operations** - Checkpoint commits become seamless - ✅ **File operations** - Reading project files for analysis - ✅ **Quality tools** - Running linters and formatters ### Cross-Project Intelligence Your knowledge base spans all projects: - 🔗 **Related Projects**: Automatically identifies connections between repositories - 📊 **Pattern Mining**: Finds common solutions across different codebases - 🎯 **Context Bridging**: Applies insights from one project to another - 🧠 **Cumulative Learning**: Builds expertise that compounds over time ### Token Optimization Large responses are automatically managed: - 📄 **Auto-Chunking**: Responses >4000 tokens split into manageable pieces - 🔄 **Progressive Loading**: Retrieve additional chunks as needed - 📊 **Smart Summarization**: Important information prioritized - ⚡ **Performance**: Optimized for Claude Code's context window ## 🚨 Troubleshooting ### Common Issues #### "Memory system not available" ```bash # Ensure all dependencies are installed (embeddings are included by default) uv sync # or pip install session-buddy ``` #### "No conversations found" - Ensure you've run `/session-buddy:start` to initialize the database - Check that `~/.claude/data/` directory exists and is writable #### "Project not detected" - Make sure you're in a project directory - Use the `working_directory` parameter in init if needed - Verify git repository status if using git features #### "Permission errors" - Check file permissions on `~/.claude/` directory - Verify MCP server configuration in `.mcp.json` - Use `/session-buddy:status` to diagnose permission issues ### Performance Tips - Use `/session-buddy:quick_search` before full searches to check relevance - Higher similarity thresholds (0.8-0.9) for more precise results - Lower thresholds (0.6-0.7) for broader exploration - Use project filtering for large knowledge bases - Regular checkpoints improve quality scoring accuracy ## 📊 Advanced Integration Tools ### Crackerjack Quality Integration (11 tools) **Code Quality & Testing Integration** - Deep integration with the Crackerjack development platform: - **`/session-buddy:crackerjack_run`** - Execute crackerjack commands with real-time analytics - **`/session-buddy:execute_crackerjack_command`** - Run with enhanced AI integration - **`/session-buddy:crackerjack_help`** - Comprehensive command selection help - **`/session-buddy:crackerjack_metrics`** - Quality metrics trends over time - **`/session-buddy:crackerjack_quality_trends`** - Trend analysis with insights - **`/session-buddy:crackerjack_patterns`** - Test failure pattern analysis - **`/session-buddy:crackerjack_history`** - Command execution history - **`/session-buddy:crackerjack_health_check`** - Integration health diagnostics ### LLM Provider Management (5 tools) - **`/session-buddy:list_llm_providers`** - List available providers and models - **`/session-buddy:test_llm_providers`** - Test provider availability - **`/session-buddy:generate_with_llm`** - Generate text using any provider - **`/session-buddy:chat_with_llm`** - Have conversations with LLMs - **`/session-buddy:configure_llm_provider`** - Configure credentials and settings ### Serverless Session Management (8 tools) **External Storage Integration** - Redis, S3, or local storage: - **`/session-buddy:create_serverless_session`** - Create with external storage - **`/session-buddy:get_serverless_session`** - Retrieve session state - **`/session-buddy:update_serverless_session`** - Update session data - **`/session-buddy:delete_serverless_session`** - Remove session - **`/session-buddy:list_serverless_sessions`** - List by user/project - **`/session-buddy:test_serverless_storage`** - Test storage backend - **`/session-buddy:cleanup_serverless_sessions`** - Remove expired sessions - **`/session-buddy:configure_serverless_storage`** - Configure backends ### Team Collaboration (4 tools) - **`/session-buddy:create_team`** - Create team for knowledge sharing - **`/session-buddy:search_team_knowledge`** - Search with access control - **`/session-buddy:get_team_statistics`** - Team activity metrics - **`/session-buddy:vote_on_reflection`** - Vote on insights (upvote/downvote) ### Multi-Project Coordination (4 tools) - **`/session-buddy:create_project_group`** - Group related projects - **`/session-buddy:add_project_dependency`** - Define dependencies - **`/session-buddy:search_across_projects`** - Cross-project search - **`/session-buddy:get_project_insights`** - Cross-project insights ### Activity Monitoring (5 tools) - **`/session-buddy:start_app_monitoring`** - Track IDE/browser activity - **`/session-buddy:stop_app_monitoring`** - Stop monitoring - **`/session-buddy:get_activity_summary`** - Activity summary - **`/session-buddy:get_context_insights`** - Behavior insights - **`/session-buddy:get_active_files`** - Recently active files ### Interruption Management (7 tools) - **`/session-buddy:start_interruption_monitoring`** - Smart detection - **`/session-buddy:stop_interruption_monitoring`** - Disable monitoring - **`/session-buddy:create_session_context`** - Create snapshot - **`/session-buddy:preserve_current_context`** - Force preservation - **`/session-buddy:restore_session_context`** - Restore context - **`/session-buddy:get_interruption_history`** - Interruption history - **`/session-buddy:get_interruption_statistics`** - Analytics ### Natural Language Scheduling (5 tools) - **`/session-buddy:create_natural_reminder`** - Create from natural language - **`/session-buddy:list_user_reminders`** - List pending reminders - **`/session-buddy:cancel_user_reminder`** - Cancel reminder - **`/session-buddy:start_reminder_service`** - Start service - **`/session-buddy:stop_reminder_service`** - Stop service ### Git Worktree Management (3 tools) - **`/session-buddy:git_worktree_add`** - Create new worktree - **`/session-buddy:git_worktree_remove`** - Remove worktree - **`/session-buddy:git_worktree_switch`** - Switch with context preservation ## 📚 Related Documentation ## 🧱 Migration & Schema Tools ### `/session-buddy:migration_status` Inspect schema version (v1/v2), migration history, and counts. ### `/session-buddy:trigger_migration` Run v1 → v2 migration (supports `--create_backup_first` and `--dry_run`). ### `/session-buddy:rollback_migration` Restore the database from a previous backup path. ## 📥 Extraction & Persistence ### `/session-buddy:extract_and_store_memory` Multi-provider extraction (OpenAI→Anthropic→Gemini→pattern) and persistence into v2 tables. Parameters include `activity_score` (0–1) to blend with LLM importance (70/30). ## 🧠 Conscious Agent ### `/session-buddy:start_conscious_agent` / `/session-buddy:stop_conscious_agent` Start/stop background optimization (analysis, promotions/demotions). ### `/session-buddy:force_conscious_analysis` Run one-time analysis; returns promoted/demoted counts. ## 📊 Access Metrics ### `/session-buddy:access_log_stats` Inspect recent access activity with breakdowns `by_type` and `by_provider` and top memory candidates. ## 🧩 Feature Flags & Rollout ### `/session-buddy:feature_flags_status` Show current feature flags for schema_v2, extraction, providers, agent, and filesystem integration. ### `/session-buddy:rollout_plan` Staged enablement plan with daily steps and rollback guidance. ## 📎 Appendix: Registered Tools (Canonical) Alphabetical list of all tools currently registered by the server: Note: `*_validated` tools are internal validation wrappers used by the server and are not intended for direct user invocation. - `access_log_stats` - `add_observation` - `batch_create_entities` - `chat_with_llm` - `checkpoint` - `cleanup_serverless_sessions` - `configure_llm_provider` - `configure_serverless_storage` - `create_entity` - `create_relation` - `create_serverless_session` - `create_session_context` - `create_team` - `delete_serverless_session` - `end` - `extract_and_store_memory` - `extract_entities_from_context` - `feature_flags_status` - `find_path` - `force_conscious_analysis` - `generate_with_llm` - `get_active_files` - `get_activity_summary` - `get_context_insights` - `get_entity_relationships` - `get_interruption_history` - `get_knowledge_graph_stats` - `get_more_results` - `get_serverless_session` - `get_team_statistics` - `health_check` - `list_llm_providers` - `list_serverless_sessions` - `migration_status` - `ping` - `preserve_current_context` - `quick_search` - `quick_search_validated` - `reflection_stats` - `reset_reflection_database` - `restore_session_context` - `rollback_migration` - `rollout_plan` - `search_by_concept` - `search_by_concept_validated` - `search_by_file` - `search_by_file_validated` - `search_code` - `search_entities` - `search_errors` - `search_summary` - `search_team_knowledge` - `search_temporal` - `server_info` - `start` - `start_app_monitoring` - `start_conscious_agent` - `start_interruption_monitoring` - `status` - `stop_app_monitoring` - `stop_conscious_agent` - `stop_interruption_monitoring` - `store_reflection` - `store_reflection_validated` - `test_llm_providers` - `test_serverless_storage` - `trigger_migration` - `update_serverless_session` - `vote_on_reflection` - **[README.md](../../README.md)** - Project overview with complete tool inventory (70+ tools) - **[Quick Start Guide](QUICK_START.md)** - Get up and running in 5 minutes - **[MCP Schema Reference](../reference/MCP_SCHEMA_REFERENCE.md)** - Complete API reference - **[AI Integration Patterns](../features/AI_INTEGRATION.md)** - Advanced patterns - **[CLAUDE.md](../../CLAUDE.md)** - Development guide for contributors - **[Configuration Reference](CONFIGURATION.md)** - Advanced setup options ______________________________________________________________________ *This reference lists all registered MCP tools provided by session-buddy. For implementation details, see the codebase.* **Need help?** Use `/session-buddy:status` to diagnose issues or check [GitHub Issues](https://github.com/lesleslie/session-buddy/issues) for support.