session-mgmt-mcp 0.3.5

MCP server for Claude session management and conversation memory

Session Management MCP Server

A dedicated MCP server that provides comprehensive session management functionality for Claude Code sessions across any project.

Features

• 🚀 Session Initialization: Complete setup with UV dependency management, project analysis, and automation tools
• 🔍 Quality Checkpoints: Mid-session quality monitoring with workflow analysis and optimization recommendations
• 🏁 Session Cleanup: Comprehensive cleanup with learning capture and handoff file creation
• 📊 Status Monitoring: Real-time session status and project context analysis
• ⚡ Auto-Generated Shortcuts: Automatically creates /start, /checkpoint, and /end Claude Code slash commands

🚀 Automatic Session Management (NEW!)

For Git Repositories:

• ✅ Automatic initialization when Claude Code connects
• ✅ Automatic cleanup when session ends (quit, crash, or network failure)
• ✅ Intelligent auto-compaction during checkpoints
• ✅ Zero manual intervention required

For Non-Git Projects:

• 📝 Use /start for manual initialization
• 📝 Use /end for manual cleanup
• 📝 Full session management features available on-demand

The server automatically detects git repositories and provides seamless session lifecycle management with crash resilience and network failure recovery. Non-git projects retain manual control for flexible workflow management.

Available MCP Tools

Session Management

• init - Comprehensive session initialization including:

  • Project context analysis and health monitoring
  • UV dependency synchronization
  • Session management setup with auto-checkpoints
  • Project maturity scoring and recommendations
  • Permissions management to reduce prompts

• checkpoint - Mid-session quality assessment with:

  • Real-time quality scoring (project health, permissions, tools)
  • Workflow drift detection and optimization recommendations
  • Progress tracking and goal alignment
  • Automatic context compaction when needed (NEW!)
  • Automatic git checkpoint commits (if in git repo)

• end - Complete session cleanup featuring:

  • Final quality checkpoint and assessment
  • Learning capture across key categories
  • Session handoff file creation for continuity
  • Workspace cleanup and optimization

• status - Current session status including:

  • Project context analysis with health checks
  • Tool availability verification
  • Session management status
  • Available MCP tools listing with diagnostics

Memory & Reflection System

• reflect_on_past - Search past conversations and insights with:

  • Semantic similarity search using local embeddings (all-MiniLM-L6-v2)
  • DuckDB-based conversation storage with FLOAT[384] vectors
  • Time-decay prioritization for recent conversations
  • Cross-project conversation history
  • Configurable similarity thresholds and result limits

• store_reflection - Store important insights for future reference with:

  • Content indexing with semantic embeddings
  • Tagging system for organization
  • Project-specific context tracking
  • Automatic embedding generation (local, no external services)

• search_nodes - Advanced search capabilities for stored knowledge

• quick_search - Fast overview search with count and top results

• get_more_results - Pagination support for large result sets

Permissions & Trust System

• permissions - Manage trusted operations to reduce permission prompts:
  • View current trusted operations
  • Trust specific operations (UV sync, Git operations, file management)
  • Reset all permissions when needed

🚀 Integration with Crackerjack

Session-mgmt includes deep integration with Crackerjack, the AI-driven Python development platform:

Integrated Features:

• 📊 Quality Metrics Tracking: Automatically captures and tracks Crackerjack quality scores over time
• 🧪 Test Result Monitoring: Learns from test patterns, failures, and successful fixes
• 🔍 Error Pattern Recognition: Remembers how specific errors were resolved and suggests solutions
• 📝 Command History Analysis: Tracks which Crackerjack commands are most effective for different scenarios
• 🎯 Progress Intelligence: Predicts completion times based on historical data

Why Use Both Together:

• Crackerjack: Enforces code quality, runs tests, manages releases, and provides AI auto-fixing
• Session-mgmt: Remembers what worked, tracks progress evolution, and maintains context
• Synergy: Creates an intelligent development environment that learns from every interaction

Example Integrated Workflow:

1. 🚀 Session-mgmt init - Sets up your session with accumulated context from previous work
2. 🔧 Crackerjack runs quality checks and applies AI agent fixes to resolve issues
3. 💾 Session-mgmt captures successful patterns, quality improvements, and error resolutions
4. 🧠 Next session starts with all accumulated knowledge and learned patterns
5. 📈 Continuous improvement as both systems get smarter with each interaction

Technical Integration: The crackerjack_integration.py module (50KB+) provides:

• Real-time progress tracking during Crackerjack operations
• Quality metric extraction and trend analysis
• Test result pattern detection and storage
• Error resolution pattern matching for faster fixes
• Command effectiveness scoring for workflow optimization

Configuration Example:

{
  "mcpServers": {
    "crackerjack": {
      "command": "python",
      "args": ["-m", "crackerjack", "--start-mcp-server"]
    },
    "session-mgmt": {
      "command": "python",
      "args": ["-m", "session_mgmt_mcp.server"]
    }
  }
}

The integration is automatic once both servers are configured - they coordinate through the MCP protocol without requiring additional setup.

Installation

From Source

# Clone the repository
git clone https://github.com/lesleslie/session-mgmt-mcp.git
cd session-mgmt-mcp

# Install dependencies
uv sync --group dev

# Or use pip
pip install -e ".[embeddings,dev]"

MCP Configuration

Add to your project's .mcp.json file:

{
  "mcpServers": {
    "session-mgmt": {
      "command": "python",
      "args": ["-m", "session_mgmt_mcp.server"],
      "cwd": "/path/to/session-mgmt-mcp",
      "env": {
        "PYTHONPATH": "/path/to/session-mgmt-mcp"
      }
    }
  }
}

Alternative: Use Script Entry Point

If installed with pip/uv, you can use the script entry point:

{
  "mcpServers": {
    "session-mgmt": {
      "command": "session-mgmt-mcp",
      "args": [],
      "env": {}
    }
  }
}

Dependencies

Required:

• Python 3.13+
• fastmcp>=2.0.0 - MCP server framework
• duckdb>=0.9.0 - Conversation storage database
• numpy>=1.24.0 - Numerical operations for embeddings

Optional (for semantic search):

• onnxruntime - Local ONNX model inference
• transformers - Tokenizer for embedding models

Install with embedding support:

uv sync --extra embeddings
# or
pip install "session-mgmt-mcp[embeddings]"

Usage

Once configured, the following slash commands become available in Claude Code:

Primary Session Commands

• /session-mgmt:start - Full session initialization with workspace verification
• /session-mgmt:checkpoint - Quality monitoring checkpoint with scoring
• /session-mgmt:end - Complete session cleanup with learning capture
• /session-mgmt:status - Current status overview with health checks

Auto-Generated Shortcuts

The first time you run /session-mgmt:start, convenient shortcuts are automatically created:

• /start → /session-mgmt:start - Quick session initialization
• /checkpoint [name] → /session-mgmt:checkpoint - Create named checkpoints
• /end → /session-mgmt:end - Quick session cleanup

These shortcuts are created in ~/.claude/commands/ and work across all projects

Memory & Search Commands

• /session-mgmt:reflect_on_past - Search past conversations with semantic similarity
• /session-mgmt:store_reflection - Store important insights with tagging
• /session-mgmt:quick_search - Fast search with overview results
• /session-mgmt:permissions - Manage trusted operations

Advanced Usage

Running Server Directly (for development):

python -m session_mgmt_mcp.server
# or
session-mgmt-mcp

Testing Memory Features:

# The memory system automatically stores conversations and provides:
# - Semantic search across all past conversations
# - Local embedding generation (no external API needed)
# - Cross-project conversation history
# - Time-decay prioritization for recent content

Memory System Architecture

Built-in Conversation Memory

• Local Storage: DuckDB database at ~/.claude/data/reflection.duckdb
• Embeddings: Local ONNX models (all-MiniLM-L6-v2) for semantic search
• Vector Storage: FLOAT[384] arrays for similarity matching
• No External Dependencies: Everything runs locally for privacy
• Cross-Project History: Conversations tagged by project context

Search Capabilities

• Semantic Search: Vector similarity with customizable thresholds
• Text Fallback: Standard text search when embeddings unavailable
• Time Decay: Recent conversations prioritized in results
• Project Context: Filter searches by project or search across all
• Batch Operations: Efficient bulk storage and retrieval

Data Storage

This server manages its data locally in the user's home directory:

• Memory Storage: ~/.claude/data/reflection.duckdb
• Session Logs: ~/.claude/logs/
• Configuration: Uses pyproject.toml and environment variables

Recommended Session Workflow

1. Initialize Session: /session-mgmt:start

   • UV dependency synchronization
   • Project context analysis and health monitoring
   • Session quality tracking setup
   • Memory system initialization
   • Permission system setup

2. Monitor Progress: /session-mgmt:checkpoint (every 30-45 minutes)

   • Real-time quality scoring
   • Workflow optimization recommendations
   • Progress tracking and goal alignment
   • Automatic Git checkpoint commits

3. Search Past Work: /session-mgmt:reflect_on_past

   • Semantic search through project history
   • Find relevant past conversations and solutions
   • Build on previous insights

4. Store Important Insights: /session-mgmt:store_reflection

   • Capture key learnings and solutions
   • Tag insights for easy retrieval
   • Build project knowledge base

5. End Session: /session-mgmt:end

   • Final quality assessment
   • Learning capture across categories
   • Session handoff file creation
   • Memory persistence and cleanup

Benefits

Comprehensive Coverage

• Session Quality: Real-time monitoring and optimization
• Memory Persistence: Cross-session conversation retention
• Project Structure: Context-aware development workflows

Reduced Friction

• Single Command Setup: One /session-mgmt:start sets up everything
• Local Dependencies: No external API calls or services required
• Intelligent Permissions: Reduces repeated permission prompts
• Automated Workflows: Structured processes for common tasks

Enhanced Productivity

• Quality Scoring: Guides session effectiveness
• Built-in Memory: Enables building on past work automatically
• Project Templates: Accelerates development setup
• Knowledge Persistence: Maintains context across sessions

Documentation

The project documentation is organized into the following categories:

For Developers

• Testing Strategy - Comprehensive testing approach and implementation plan
• Testing Status - Current testing progress and improvements
• Parameter Validation - Pydantic parameter validation guide
• Architecture - System architecture and design patterns
• Integration - Integration patterns and best practices
• Advanced Search Fixes - Search functionality improvements

For Users

• Quick Start - Getting started guide
• Configuration - Setup and configuration options
• Deployment - Deployment and production setup
• MCP Tools Reference - Complete tool documentation

Features

• AI Integration Patterns - AI integration strategies
• Token Optimization - Token management features
• Auto Lifecycle - Automatic session management
• Crackerjack Integration - Code quality integration

Reference

• MCP Schema Reference - MCP protocol schemas
• Slash Command Shortcuts - Command reference

Troubleshooting

Common Issues

• Memory not working: Install optional dependencies with pip install "session-mgmt-mcp[embeddings]"
• Path errors: Ensure cwd and PYTHONPATH are set correctly in .mcp.json
• Permission issues: Use /session-mgmt:permissions to trust operations
• Project context: Analyze current project health and structure

Debug Mode

# Run with verbose logging
PYTHONPATH=/path/to/session-mgmt-mcp python -m session_mgmt_mcp.server --debug