| Name | session-mgmt-mcp JSON |
| Version |
0.1.3
JSON |
| download |
| home_page | None |
| Summary | MCP server for Claude session management and conversation memory |
| upload_time | 2025-09-01 20:59:28 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.13 |
| 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. |
| keywords |
ai-tools
anthropic
claude
conversation-memory
mcp
reflection
session-management
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 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
## 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 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
## 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:init` - 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
### 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:init`
- 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:init` 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
## 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
```
Raw data
{
"_id": null,
"home_page": null,
"name": "session-mgmt-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.13",
"maintainer_email": null,
"keywords": "ai-tools, anthropic, claude, conversation-memory, mcp, reflection, session-management",
"author": null,
"author_email": "Les Leslie <les@wedgwoodwebworks.com>",
"download_url": "https://files.pythonhosted.org/packages/a5/22/b198ef6a2a899e24fa1ac037943abc9262b0af3aa800851413b3ae84db32/session_mgmt_mcp-0.1.3.tar.gz",
"platform": null,
"description": "# Session Management MCP Server\n\nA dedicated MCP server that provides comprehensive session management functionality for Claude Code sessions across any project.\n\n## Features\n\n- **\ud83d\ude80 Session Initialization**: Complete setup with UV dependency management, project analysis, and automation tools\n- **\ud83d\udd0d Quality Checkpoints**: Mid-session quality monitoring with workflow analysis and optimization recommendations\n- **\ud83c\udfc1 Session Cleanup**: Comprehensive cleanup with learning capture and handoff file creation\n- **\ud83d\udcca Status Monitoring**: Real-time session status and project context analysis\n\n## Available MCP Tools\n\n### Session Management\n\n- **`init`** - Comprehensive session initialization including:\n\n - Project context analysis and health monitoring\n - UV dependency synchronization\n - Session management setup with auto-checkpoints\n - Project maturity scoring and recommendations\n - Permissions management to reduce prompts\n\n- **`checkpoint`** - Mid-session quality assessment with:\n\n - Real-time quality scoring (project health, permissions, tools)\n - Workflow drift detection and optimization recommendations\n - Progress tracking and goal alignment\n - Automatic git checkpoint commits (if in git repo)\n\n- **`end`** - Complete session cleanup featuring:\n\n - Final quality checkpoint and assessment\n - Learning capture across key categories\n - Session handoff file creation for continuity\n - Workspace cleanup and optimization\n\n- **`status`** - Current session status including:\n\n - Project context analysis with health checks\n - Tool availability verification\n - Session management status\n - Available MCP tools listing with diagnostics\n\n### Memory & Reflection System\n\n- **`reflect_on_past`** - Search past conversations and insights with:\n\n - Semantic similarity search using local embeddings (all-MiniLM-L6-v2)\n - DuckDB-based conversation storage with FLOAT[384] vectors\n - Time-decay prioritization for recent conversations\n - Cross-project conversation history\n - Configurable similarity thresholds and result limits\n\n- **`store_reflection`** - Store important insights for future reference with:\n\n - Content indexing with semantic embeddings\n - Tagging system for organization\n - Project-specific context tracking\n - Automatic embedding generation (local, no external services)\n\n- **`search_nodes`** - Advanced search capabilities for stored knowledge\n\n- **`quick_search`** - Fast overview search with count and top results\n\n- **`get_more_results`** - Pagination support for large result sets\n\n### Permissions & Trust System\n\n- **`permissions`** - Manage trusted operations to reduce permission prompts:\n - View current trusted operations\n - Trust specific operations (UV sync, Git operations, file management)\n - Reset all permissions when needed\n\n## Installation\n\n### From Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/lesleslie/session-mgmt-mcp.git\ncd session-mgmt-mcp\n\n# Install dependencies\nuv sync --group dev\n\n# Or use pip\npip install -e \".[embeddings,dev]\"\n```\n\n### MCP Configuration\n\nAdd to your project's `.mcp.json` file:\n\n```json\n{\n \"mcpServers\": {\n \"session-mgmt\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"session_mgmt_mcp.server\"],\n \"cwd\": \"/path/to/session-mgmt-mcp\",\n \"env\": {\n \"PYTHONPATH\": \"/path/to/session-mgmt-mcp\"\n }\n }\n }\n}\n```\n\n### Alternative: Use Script Entry Point\n\nIf installed with pip/uv, you can use the script entry point:\n\n```json\n{\n \"mcpServers\": {\n \"session-mgmt\": {\n \"command\": \"session-mgmt-mcp\",\n \"args\": [],\n \"env\": {}\n }\n }\n}\n```\n\n### Dependencies\n\n**Required**:\n\n- Python 3.13+\n- `fastmcp>=2.0.0` - MCP server framework\n- `duckdb>=0.9.0` - Conversation storage database\n- `numpy>=1.24.0` - Numerical operations for embeddings\n\n**Optional (for semantic search)**:\n\n- `onnxruntime` - Local ONNX model inference\n- `transformers` - Tokenizer for embedding models\n\nInstall with embedding support:\n\n```bash\nuv sync --extra embeddings\n# or\npip install \"session-mgmt-mcp[embeddings]\"\n```\n\n## Usage\n\nOnce configured, the following slash commands become available in Claude Code:\n\n### Primary Session Commands\n\n- `/session-mgmt:init` - Full session initialization with workspace verification\n- `/session-mgmt:checkpoint` - Quality monitoring checkpoint with scoring\n- `/session-mgmt:end` - Complete session cleanup with learning capture\n- `/session-mgmt:status` - Current status overview with health checks\n\n### Memory & Search Commands\n\n- `/session-mgmt:reflect_on_past` - Search past conversations with semantic similarity\n- `/session-mgmt:store_reflection` - Store important insights with tagging\n- `/session-mgmt:quick_search` - Fast search with overview results\n- `/session-mgmt:permissions` - Manage trusted operations\n\n### Advanced Usage\n\n**Running Server Directly** (for development):\n\n```bash\npython -m session_mgmt_mcp.server\n# or\nsession-mgmt-mcp\n```\n\n**Testing Memory Features**:\n\n```bash\n# The memory system automatically stores conversations and provides:\n# - Semantic search across all past conversations\n# - Local embedding generation (no external API needed)\n# - Cross-project conversation history\n# - Time-decay prioritization for recent content\n```\n\n## Memory System Architecture\n\n### Built-in Conversation Memory\n\n- **Local Storage**: DuckDB database at `~/.claude/data/reflection.duckdb`\n- **Embeddings**: Local ONNX models (all-MiniLM-L6-v2) for semantic search\n- **Vector Storage**: FLOAT[384] arrays for similarity matching\n- **No External Dependencies**: Everything runs locally for privacy\n- **Cross-Project History**: Conversations tagged by project context\n\n### Search Capabilities\n\n- **Semantic Search**: Vector similarity with customizable thresholds\n- **Text Fallback**: Standard text search when embeddings unavailable\n- **Time Decay**: Recent conversations prioritized in results\n- **Project Context**: Filter searches by project or search across all\n- **Batch Operations**: Efficient bulk storage and retrieval\n\n## Data Storage\n\nThis server manages its data locally in the user's home directory:\n\n- **Memory Storage**: `~/.claude/data/reflection.duckdb`\n- **Session Logs**: `~/.claude/logs/`\n- **Configuration**: Uses pyproject.toml and environment variables\n\n## Recommended Session Workflow\n\n1. **Initialize Session**: `/session-mgmt:init`\n\n - UV dependency synchronization\n - Project context analysis and health monitoring\n - Session quality tracking setup\n - Memory system initialization\n - Permission system setup\n\n1. **Monitor Progress**: `/session-mgmt:checkpoint` (every 30-45 minutes)\n\n - Real-time quality scoring\n - Workflow optimization recommendations\n - Progress tracking and goal alignment\n - Automatic Git checkpoint commits\n\n1. **Search Past Work**: `/session-mgmt:reflect_on_past`\n\n - Semantic search through project history\n - Find relevant past conversations and solutions\n - Build on previous insights\n\n1. **Store Important Insights**: `/session-mgmt:store_reflection`\n\n - Capture key learnings and solutions\n - Tag insights for easy retrieval\n - Build project knowledge base\n\n1. **End Session**: `/session-mgmt:end`\n\n - Final quality assessment\n - Learning capture across categories\n - Session handoff file creation\n - Memory persistence and cleanup\n\n## Benefits\n\n### Comprehensive Coverage\n\n- **Session Quality**: Real-time monitoring and optimization\n- **Memory Persistence**: Cross-session conversation retention\n- **Project Structure**: Context-aware development workflows\n\n### Reduced Friction\n\n- **Single Command Setup**: One `/session-mgmt:init` sets up everything\n- **Local Dependencies**: No external API calls or services required\n- **Intelligent Permissions**: Reduces repeated permission prompts\n- **Automated Workflows**: Structured processes for common tasks\n\n### Enhanced Productivity\n\n- **Quality Scoring**: Guides session effectiveness\n- **Built-in Memory**: Enables building on past work automatically\n- **Project Templates**: Accelerates development setup\n- **Knowledge Persistence**: Maintains context across sessions\n\n## Troubleshooting\n\n### Common Issues\n\n- **Memory not working**: Install optional dependencies with `pip install \"session-mgmt-mcp[embeddings]\"`\n- **Path errors**: Ensure `cwd` and `PYTHONPATH` are set correctly in `.mcp.json`\n- **Permission issues**: Use `/session-mgmt:permissions` to trust operations\n- **Project context**: Analyze current project health and structure\n\n### Debug Mode\n\n```bash\n# Run with verbose logging\nPYTHONPATH=/path/to/session-mgmt-mcp python -m session_mgmt_mcp.server --debug\n```\n",
"bugtrack_url": null,
"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.",
"summary": "MCP server for Claude session management and conversation memory",
"version": "0.1.3",
"project_urls": {
"Homepage": "https://github.com/lesleslie/session-mgmt-mcp",
"Issues": "https://github.com/lesleslie/session-mgmt-mcp/issues",
"Repository": "https://github.com/lesleslie/session-mgmt-mcp"
},
"split_keywords": [
"ai-tools",
" anthropic",
" claude",
" conversation-memory",
" mcp",
" reflection",
" session-management"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5f4cada2cd181cf86cfae3ee474c8ac196e222a8ae6373d9a86b38968a06ad8f",
"md5": "5ef88a4f551784314cbda4eab656a4c7",
"sha256": "1db373677a90fdd8fb048f3f897646060721d1e5979553400f67bf2bb07063e1"
},
"downloads": -1,
"filename": "session_mgmt_mcp-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5ef88a4f551784314cbda4eab656a4c7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.13",
"size": 175922,
"upload_time": "2025-09-01T20:59:27",
"upload_time_iso_8601": "2025-09-01T20:59:27.166516Z",
"url": "https://files.pythonhosted.org/packages/5f/4c/ada2cd181cf86cfae3ee474c8ac196e222a8ae6373d9a86b38968a06ad8f/session_mgmt_mcp-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a522b198ef6a2a899e24fa1ac037943abc9262b0af3aa800851413b3ae84db32",
"md5": "70dfde0ad50171dbc7f605703b209eb1",
"sha256": "8c36d7e20e4d3a64cbde3b7693118ffb24114d6c660aa1d750521c8b890e7eca"
},
"downloads": -1,
"filename": "session_mgmt_mcp-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "70dfde0ad50171dbc7f605703b209eb1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.13",
"size": 1004865,
"upload_time": "2025-09-01T20:59:28",
"upload_time_iso_8601": "2025-09-01T20:59:28.719102Z",
"url": "https://files.pythonhosted.org/packages/a5/22/b198ef6a2a899e24fa1ac037943abc9262b0af3aa800851413b3ae84db32/session_mgmt_mcp-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-01 20:59:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lesleslie",
"github_project": "session-mgmt-mcp",
"github_not_found": true,
"lcname": "session-mgmt-mcp"
}
