Metadata-Version: 2.4
Name: session-mgmt-mcp
Version: 0.3.12
Summary: MCP server for Claude session management and conversation memory
Project-URL: Homepage, https://github.com/lesleslie/session-mgmt-mcp
Project-URL: Issues, https://github.com/lesleslie/session-mgmt-mcp/issues
Project-URL: Repository, https://github.com/lesleslie/session-mgmt-mcp
Author-email: Les Leslie <les@wedgwoodwebworks.com>
License: BSD 3-Clause License
        
        Copyright (c) 2025, Wedgwood Web Works
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
License-File: LICENSE
Keywords: ai-tools,anthropic,claude,conversation-memory,mcp,reflection,session-management
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: System Shells
Classifier: Topic :: Utilities
Requires-Python: >=3.13
Requires-Dist: crackerjack
Requires-Dist: duckdb>=0.9
Requires-Dist: fastmcp>=2
Requires-Dist: numpy>=1.24
Requires-Dist: onnxruntime>=1.15
Requires-Dist: psutil>=7.0.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: rich>=14.1.0
Requires-Dist: structlog>=25.4
Requires-Dist: tiktoken>=0.5
Requires-Dist: tomli>=2.2.1
Requires-Dist: transformers>=4.21
Requires-Dist: typer>=0.17.4
Provides-Extra: dev
Requires-Dist: coverage>=7; extra == 'dev'
Requires-Dist: hypothesis>=6.70; extra == 'dev'
Requires-Dist: psutil>=5.9; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest-benchmark>=4; extra == 'dev'
Requires-Dist: pytest-cov>=4; extra == 'dev'
Requires-Dist: pytest-mock>=3.10; extra == 'dev'
Requires-Dist: pytest-timeout>=2.1; extra == 'dev'
Requires-Dist: pytest-xdist>=3; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Description-Content-Type: text/markdown

# Session Management MCP Server

[![Code style: crackerjack](https://img.shields.io/badge/code%20style-crackerjack-000042)](https://github.com/lesleslie/crackerjack)
[![Python: 3.13+](https://img.shields.io/badge/python-3.13%2B-green)](https://www.python.org/downloads/)
![Coverage](https://img.shields.io/badge/coverage-12.0%25-red)

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](https://github.com/lesleslie/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
1. 🔧 **Crackerjack runs** quality checks and applies AI agent fixes to resolve issues
1. 💾 **Session-mgmt captures** successful patterns, quality improvements, and error resolutions
1. 🧠 **Next session starts** with all accumulated knowledge and learned patterns
1. 📈 **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:**

```json
{
  "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

```bash
# 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:

```json
{
  "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:

```json
{
  "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:

```bash
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):

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

**Testing Memory Features**:

```bash
# 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

1. **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

1. **Search Past Work**: `/session-mgmt:reflect_on_past`

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

1. **Store Important Insights**: `/session-mgmt:store_reflection`

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

1. **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](docs/developer/TESTING_STRATEGY.md)** - Comprehensive testing approach and implementation plan
- **[Testing Status](docs/developer/TESTING_STATUS.md)** - Current testing progress and improvements
- **[Parameter Validation](docs/developer/PARAMETER_VALIDATION.md)** - Pydantic parameter validation guide
- **[Architecture](docs/developer/ARCHITECTURE.md)** - System architecture and design patterns
- **[Integration](docs/developer/INTEGRATION.md)** - Integration patterns and best practices
- **[Advanced Search Fixes](docs/developer/ADVANCED_SEARCH_FIXES_PLAN.md)** - Search functionality improvements

### For Users

- **[Quick Start](docs/user/QUICK_START.md)** - Getting started guide
- **[Configuration](docs/user/CONFIGURATION.md)** - Setup and configuration options
- **[Deployment](docs/user/DEPLOYMENT.md)** - Deployment and production setup
- **[MCP Tools Reference](docs/user/MCP_TOOLS_REFERENCE.md)** - Complete tool documentation

### Features

- **[AI Integration Patterns](docs/features/AI_INTEGRATION_PATTERNS.md)** - AI integration strategies
- **[Token Optimization](docs/features/TOKEN_OPTIMIZATION_FEATURES.md)** - Token management features
- **[Auto Lifecycle](docs/features/AUTO_LIFECYCLE_IMPLEMENTATION.md)** - Automatic session management
- **[Crackerjack Integration](docs/features/CRACKERJACK_INTEGRATION.md)** - Code quality integration

### Reference

- **[MCP Schema Reference](docs/reference/MCP_SCHEMA_REFERENCE.md)** - MCP protocol schemas
- **[Slash Command Shortcuts](docs/reference/slash-command-shortcuts.md)** - 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

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