claude-mpm 4.1.1__tar.gz → 4.1.2__tar.gz

claude_mpm-4.1.2/BUILD_NUMBER

@@ -0,0 +1 @@
+298

claude_mpm-4.1.2/CLAUDE.md

@@ -0,0 +1,295 @@
+# Claude MPM Development Guidelines
+
+This document provides development guidelines for the claude-mpm project codebase.
+
+## Project Overview
+
+Claude MPM (Multi-Agent Project Manager) is a framework that extends Claude Code with multi-agent orchestration capabilities, featuring a modern service-oriented architecture with interface-based contracts and dependency injection.
+
+## Architecture (v4.0.25+)
+
+Following the TSK-0053 refactoring, Claude MPM features:
+
+- **Service-Oriented Architecture**: Five specialized service domains
+- **Interface-Based Contracts**: All services implement explicit interfaces  
+- **Dependency Injection**: Service container with automatic resolution
+- **Performance Optimizations**: Lazy loading, multi-level caching, connection pooling
+- **Security Framework**: Input validation, path traversal prevention, secure operations
+- **Backward Compatibility**: Lazy imports maintain existing import paths
+
+## Key Documentation
+
+### 📚 **Primary Entry Point**
+- **[Documentation Index](docs/README.md)** - Start here! Complete navigation guide to all documentation
+
+### Architecture and Development
+- 🏗️ **Architecture Overview**: See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for service-oriented architecture
+- 📁 **Project Structure**: See [docs/STRUCTURE.md](docs/STRUCTURE.md) for file organization
+- 🔧 **Service Layer Guide**: See [docs/developer/SERVICES.md](docs/developer/SERVICES.md) for service development
+- ⚡ **Performance Guide**: See [docs/PERFORMANCE.md](docs/PERFORMANCE.md) for optimization patterns
+- 🔒 **Security Guide**: See [docs/SECURITY.md](docs/SECURITY.md) for security framework
+- 🧪 **Testing Guide**: See [docs/TESTING.md](docs/TESTING.md) for testing strategies
+- 📚 **Migration Guide**: See [docs/MIGRATION.md](docs/MIGRATION.md) for upgrade instructions
+
+### Operations and Quality
+- 🧪 **Quality Assurance**: See [docs/QA.md](docs/QA.md) for testing guidelines
+- 🚀 **Deployment**: See [docs/DEPLOY.md](docs/DEPLOY.md) for versioning and deployment
+- 📊 **Response Logging**: See [docs/archive/RESPONSE_LOGGING_CONFIG.md](docs/archive/RESPONSE_LOGGING_CONFIG.md) for response logging configuration
+- 🔢 **Versioning**: See [docs/VERSIONING.md](docs/VERSIONING.md) for version management
+- 🧠 **Memory System**: See [docs/MEMORY.md](docs/MEMORY.md) for agent memory management
+- 🎨 **Output Style**: See [docs/OUTPUT_STYLE.md](docs/OUTPUT_STYLE.md) for agent response formatting standards
+
+## Development Guidelines
+
+### Development Environment
+
+Claude MPM now supports both Mamba (recommended) and traditional Python venv environments:
+
+- **Automatic detection**: `./scripts/claude-mpm` auto-detects and uses the best available environment
+- **Mamba setup**: See [docs/DEVELOPMENT_SETUP.md](docs/DEVELOPMENT_SETUP.md) for Mamba installation and benefits
+- **Force venv**: Use `./scripts/claude-mpm --use-venv` to use traditional venv even if Mamba is available
+- **Benefits of Mamba**: 50-80% faster dependency resolution, optimized binaries, better reproducibility
+
+### Critical Principles
+
+**🔴 NEVER ASSUME - ALWAYS VERIFY**
+- **NEVER assume** file locations, configurations, or implementations
+- **ALWAYS verify** by reading actual files and checking current state
+- **ALWAYS check** existing code patterns before implementing
+- **NEVER guess** at directory structures or file contents
+- **ALWAYS confirm** dependencies and imports exist before using them
+
+### Project Structure Requirements
+
+1. **File Organization**: Always refer to `docs/STRUCTURE.md` when creating new files
+   - **Scripts**: ALL scripts go in `/scripts/`, NEVER in project root
+   - **Tests**: ALL tests go in `/tests/`, NEVER in project root
+   - **Python modules**: Always under `/src/claude_mpm/`
+   
+2. **Import Conventions**: 
+   - Use full package names: `from claude_mpm.module import ...`
+   - Never use relative imports in main code
+   - Check existing patterns before adding new imports
+
+### Testing Requirements
+
+**After significant changes, always run:**
+```bash
+# Quick E2E tests
+./scripts/run_e2e_tests.sh
+
+# Full test suite
+./scripts/run_all_tests.sh
+
+# Lint and type checks (catches duplicate imports!)
+./scripts/run_lint.sh
+```
+
+See [docs/QA.md](docs/QA.md) for detailed testing procedures.
+See [docs/LINTING.md](docs/LINTING.md) for linting configuration and duplicate import detection.
+
+### Key System Components
+
+When modifying the codebase, understand these core systems:
+
+1. **Framework Loader** (`src/claude_mpm/core/framework_loader.py`)
+   - Loads PM instructions from `src/claude_mpm/agents/INSTRUCTIONS.md`
+   - Manages agent discovery and capabilities
+   - DO NOT duplicate CLAUDE.md content here
+
+2. **Hook System** (`src/claude_mpm/hooks/`)
+   - Extensibility through pre/post hooks
+   - Response logging via `SubagentStop` and `Stop` events
+   - Structured JSON responses for proper logging
+
+3. **Services Layer** (`src/claude_mpm/services/`)
+   - **Core Services**: Foundation interfaces and base classes
+   - **Agent Services**: Agent lifecycle, deployment, and management
+   - **Communication Services**: Real-time WebSocket and SocketIO
+   - **Project Services**: Project analysis and workspace management
+   - **Infrastructure Services**: Logging, monitoring, and error handling
+   - **Legacy Structure**: Maintained for backward compatibility
+
+4. **CLI System** (`src/claude_mpm/cli/`)
+   - Modular command structure
+   - See [CLI Architecture](src/claude_mpm/cli/README.md) for adding new commands
+
+### Common Development Tasks
+
+#### Adding a New Service
+1. **Create Interface**: Define service contract in `src/claude_mpm/services/core/interfaces.py`
+2. **Implement Service**: Create implementation in appropriate service domain
+3. **Register Service**: Add to service container if using dependency injection
+4. **Add Tests**: Create unit, integration, and interface compliance tests
+5. **Update Documentation**: Document service in [docs/developer/SERVICES.md](docs/developer/SERVICES.md)
+
+#### Service Development Patterns
+```python
+# 1. Define interface
+class IMyService(ABC):
+    @abstractmethod
+    def my_operation(self, param: str) -> bool:
+        pass
+
+# 2. Implement service
+class MyService(BaseService, IMyService):
+    def __init__(self, dependency: IDependency):
+        super().__init__("MyService")
+        self.dependency = dependency
+    
+    async def initialize(self) -> bool:
+        # Initialize service
+        return True
+    
+    def my_operation(self, param: str) -> bool:
+        # Implementation
+        return True
+
+# 3. Register in container
+container.register(IMyService, MyService, singleton=True)
+
+# 4. Test interface compliance
+def test_service_implements_interface():
+    service = MyService(mock_dependency)
+    assert isinstance(service, IMyService)
+```
+
+#### Modifying PM Instructions
+1. Edit `src/claude_mpm/agents/INSTRUCTIONS.md` for PM behavior
+2. Edit `src/claude_mpm/agents/BASE_PM.md` for framework requirements
+3. Test with `./claude-mpm run` in interactive mode
+4. Update tests for PM behavior changes
+
+#### Adding CLI Commands
+1. Create command module in `src/claude_mpm/cli/commands/`
+2. Register in `src/claude_mpm/cli/parser.py`
+3. Follow existing command patterns
+4. Use dependency injection for service access
+5. Add comprehensive tests and documentation
+
+#### Performance Optimization
+1. **Identify Bottlenecks**: Use profiling tools and performance tests
+2. **Implement Caching**: Add appropriate caching layers
+3. **Lazy Loading**: Defer expensive operations until needed
+4. **Connection Pooling**: Reuse expensive connections
+5. **Monitor Metrics**: Track performance over time
+
+## Common Issues and Solutions
+
+### Architecture-Related Issues
+1. **Service Resolution Errors**: Ensure services are registered in container before resolving
+2. **Interface Compliance**: Verify services implement all required interface methods
+3. **Circular Dependencies**: Use dependency injection and avoid circular imports
+4. **Cache Performance**: Monitor cache hit rates and adjust TTL settings
+
+### Legacy Compatibility Issues
+1. **Import Errors**: Use new service paths or rely on lazy import compatibility
+2. **Service Instantiation**: Use service container instead of direct instantiation
+3. **Configuration Schema**: Update config files to new structure
+
+### Performance Issues
+1. **Slow Startup**: Check lazy loading implementation and cache warming
+2. **Memory Usage**: Monitor service memory consumption and optimization
+3. **Cache Misses**: Verify cache configuration and invalidation strategies
+
+### Traditional Issues
+1. **Import Errors**: Ensure virtual environment is activated and PYTHONPATH includes `src/`
+2. **Hook Service Errors**: Check port availability (8765-8785)
+3. **Version Errors**: Run `pip install -e .` to ensure proper installation
+4. **Agent Deployment**: All agents now deploy to project-level `.claude/agents/` directory (changed in v4.0.32+)
+
+## Contributing
+
+### Code Quality Standards
+1. **Follow Architecture**: Use service-oriented patterns and interface-based design
+2. **Structure Compliance**: Follow the structure in `docs/STRUCTURE.md`
+3. **Interface Design**: Define clear contracts for all services
+4. **Dependency Injection**: Use service container for loose coupling
+5. **Performance**: Implement caching and lazy loading where appropriate
+6. **Security**: Follow security guidelines in `docs/SECURITY.md`
+
+### Testing Requirements
+1. **Unit Tests**: Test individual services and components (85%+ coverage)
+2. **Integration Tests**: Test service interactions and interfaces
+3. **Performance Tests**: Verify caching and optimization features
+4. **Security Tests**: Validate input validation and security measures
+5. **E2E Tests**: Test complete user workflows
+
+### Documentation Standards
+1. **Service Documentation**: Document all interfaces and implementations
+2. **Architecture Updates**: Keep architecture docs current
+3. **Migration Guides**: Document breaking changes and upgrade paths
+4. **Performance Metrics**: Document performance expectations and benchmarks
+
+### Version Management
+
+Claude MPM uses a dual tracking system as of v4.0.25:
+- **VERSION file**: Contains semantic version only (e.g., "3.9.5")
+- **BUILD_NUMBER file**: Contains serial build number only (e.g., "275")
+- **Combined display**: Three formats for different contexts:
+  - Development: `3.9.5+build.275` (PEP 440 compliant)
+  - UI/Logging: `v3.9.5-build.275` (user-friendly)
+  - PyPI Release: `3.9.5` (clean semantic version)
+
+Use [Conventional Commits](https://www.conventionalcommits.org/) for automatic versioning:
+- `feat:` for new features (minor version bump)
+- `fix:` for bug fixes (patch version bump)
+- `feat!:` or `BREAKING CHANGE:` for breaking changes (major version bump)
+- `perf:` for performance improvements
+- `refactor:` for code refactoring
+- `docs:` for documentation updates
+
+Build numbers increment automatically with every substantial code change via git hooks.
+
+## Deployment Process
+
+See [docs/DEPLOY.md](docs/DEPLOY.md) for the complete deployment process:
+- Version management with `./scripts/manage_version.py`
+- Building and publishing to PyPI
+- Creating GitHub releases
+- Post-deployment verification
+
+## TSK-0053 Refactoring Achievements
+
+The service layer architecture refactoring delivered:
+
+### Technical Achievements
+- **Service-Oriented Architecture**: Complete redesign with five specialized service domains
+- **Interface-Based Contracts**: All major services implement explicit interfaces
+- **Dependency Injection**: Service container with automatic dependency resolution
+- **50-80% Performance Improvement**: Through lazy loading and intelligent caching
+- **Enhanced Security**: Comprehensive input validation and sanitization framework
+- **Backward Compatibility**: Lazy imports maintain existing import paths
+
+### Quality Improvements
+- **Better Testability**: Interface-based architecture enables easy mocking and testing
+- **Improved Maintainability**: Clear separation of concerns and service boundaries
+- **Enhanced Reliability**: Comprehensive testing with 85%+ coverage target
+- **Developer Experience**: Rich documentation and migration guides
+
+### Future-Proofing
+- **Scalability**: Service-oriented design supports future growth
+- **Extensibility**: Plugin architecture through interfaces and hooks
+- **Modularity**: Clear service boundaries enable independent development
+- **Performance**: Intelligent caching and resource optimization foundations
+
+## v4.0.25 Updates
+
+### Version Tracking System Enhancement
+- **BUILD_NUMBER file**: Replaces BUILDVERSION for cleaner naming
+- **Dual tracking**: VERSION (semantic) + BUILD_NUMBER (serial)
+- **Three display formats**: Development, UI/Logging, and PyPI Release
+- **Automatic incrementing**: Git hooks increment build numbers for code changes
+
+### New Features
+- **cleanup-memory command**: New CLI command to manage Claude conversation history
+- **Memory management**: Addresses 2GB+ memory usage from large .claude.json files
+- **Archive system**: Safely archive old conversations while keeping recent ones active
+
+## Important Notes
+
+- This file (CLAUDE.md) contains ONLY development guidelines for this project
+- Framework features and usage are documented in the framework itself
+- Claude Code automatically reads this file - keep it focused on development tasks
+- Do not include end-user documentation or framework features here
+- The refactored architecture enables faster development and better code quality

claude_mpm-4.1.2/PKG-INFO

@@ -0,0 +1,323 @@
+Metadata-Version: 2.4
+Name: claude-mpm
+Version: 4.1.2
+Summary: Claude Multi-Agent Project Manager - Orchestrate Claude with agent delegation and ticket tracking
+Author-email: Bob Matsuoka <bob@matsuoka.com>
+Maintainer: Claude MPM Team
+License: MIT
+Project-URL: Homepage, https://github.com/bobmatnyc/claude-mpm
+Project-URL: Repository, https://github.com/bobmatnyc/claude-mpm.git
+Project-URL: Issues, https://github.com/bobmatnyc/claude-mpm/issues
+Project-URL: Documentation, https://github.com/bobmatnyc/claude-mpm/blob/main/README.md
+Keywords: claude,orchestration,multi-agent,ticket-management
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ai-trackdown-pytools>=1.4.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: python-dotenv>=0.19.0
+Requires-Dist: click>=8.0.0
+Requires-Dist: pexpect>=4.8.0
+Requires-Dist: psutil>=5.9.0
+Requires-Dist: requests>=2.25.0
+Requires-Dist: flask>=3.0.0
+Requires-Dist: flask-cors>=4.0.0
+Requires-Dist: watchdog>=3.0.0
+Requires-Dist: python-socketio>=5.11.0
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: aiohttp-cors<0.8.0,>=0.7.0
+Requires-Dist: python-engineio>=4.8.0
+Requires-Dist: aiofiles>=23.0.0
+Requires-Dist: websockets>=12.0
+Requires-Dist: python-frontmatter>=1.0.0
+Requires-Dist: mistune>=3.0.0
+Requires-Dist: tree-sitter>=0.21.0
+Requires-Dist: ijson>=3.2.0
+Requires-Dist: mcp>=0.1.0
+Requires-Dist: toml>=0.10.2
+Requires-Dist: packaging>=21.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: pyee>=13.0.0
+Requires-Dist: importlib-resources>=5.0; python_version < "3.9"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: flake8-import-order; extra == "dev"
+Requires-Dist: flake8-tidy-imports; extra == "dev"
+Requires-Dist: flake8-bugbear; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: pylint>=3.0.0; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0.0; extra == "dev"
+Requires-Dist: types-requests>=2.25.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.2.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=1.3.0; extra == "docs"
+Requires-Dist: sphinx-autobuild>=2021.3.14; extra == "docs"
+Provides-Extra: monitor
+Provides-Extra: agents
+Requires-Dist: bandit>=1.7.5; extra == "agents"
+Requires-Dist: black>=23.0.0; extra == "agents"
+Requires-Dist: commitizen>=3.13.0; extra == "agents"
+Requires-Dist: dask>=2023.12.0; extra == "agents"
+Requires-Dist: detect-secrets>=1.4.0; extra == "agents"
+Requires-Dist: diagrams>=0.23.0; extra == "agents"
+Requires-Dist: docstring-parser>=0.15.0; extra == "agents"
+Requires-Dist: faker>=20.0.0; extra == "agents"
+Requires-Dist: gitlint>=0.19.0; extra == "agents"
+Requires-Dist: gitpython>=3.1.40; extra == "agents"
+Requires-Dist: hypothesis>=6.92.0; extra == "agents"
+Requires-Dist: isort>=5.12.0; extra == "agents"
+Requires-Dist: lizard>=1.17.0; extra == "agents"
+Requires-Dist: mermaid-py>=0.2.0; extra == "agents"
+Requires-Dist: mkdocs>=1.5.0; extra == "agents"
+Requires-Dist: mutmut>=2.4.0; extra == "agents"
+Requires-Dist: mypy>=1.8.0; extra == "agents"
+Requires-Dist: pandas>=2.1.0; extra == "agents"
+Requires-Dist: pre-commit>=3.5.0; extra == "agents"
+Requires-Dist: prometheus-client>=0.19.0; extra == "agents"
+Requires-Dist: pydoc-markdown>=4.8.0; extra == "agents"
+Requires-Dist: pydriller>=2.5.0; extra == "agents"
+Requires-Dist: pygments>=2.17.0; extra == "agents"
+Requires-Dist: pytest>=7.4.0; extra == "agents"
+Requires-Dist: pytest-benchmark>=4.0.0; extra == "agents"
+Requires-Dist: pytest-cov>=4.1.0; extra == "agents"
+Requires-Dist: radon>=6.0.0; extra == "agents"
+Requires-Dist: rope>=1.11.0; extra == "agents"
+Requires-Dist: sphinx>=7.2.0; extra == "agents"
+Requires-Dist: sqlalchemy>=2.0.0; extra == "agents"
+Requires-Dist: sqlparse>=0.4.4; extra == "agents"
+Requires-Dist: tree-sitter>=0.21.0; extra == "agents"
+Requires-Dist: tree-sitter-python>=0.21.0; extra == "agents"
+Requires-Dist: tree-sitter-javascript>=0.21.0; extra == "agents"
+Requires-Dist: tree-sitter-typescript>=0.21.0; extra == "agents"
+Requires-Dist: tree-sitter-go>=0.21.0; extra == "agents"
+Requires-Dist: tree-sitter-rust>=0.21.0; extra == "agents"
+Requires-Dist: tree-sitter-java>=0.21.0; extra == "agents"
+Requires-Dist: tree-sitter-cpp>=0.21.0; extra == "agents"
+Requires-Dist: tree-sitter-c>=0.21.0; extra == "agents"
+Requires-Dist: tree-sitter-ruby>=0.21.0; extra == "agents"
+Requires-Dist: tree-sitter-php>=0.21.0; extra == "agents"
+Dynamic: license-file
+
+# Claude MPM - Multi-Agent Project Manager
+
+A powerful orchestration framework for Claude Code that enables multi-agent workflows, session management, and real-time monitoring through an intuitive interface.
+
+> **Quick Start**: See [QUICKSTART.md](QUICKSTART.md) to get running in 5 minutes!
+
+## Features
+
+- 🤖 **Multi-Agent System**: 15 specialized agents for comprehensive project management
+- 🧠 **Agent Memory System**: Simple list-based persistent learning with JSON response field updates
+- 🔄 **Session Management**: Resume previous sessions with `--resume` 
+- 📊 **Real-Time Monitoring**: Live dashboard with `--monitor` flag
+- 🔌 **MCP Gateway**: Model Context Protocol integration for extensible tool capabilities
+- 📁 **Multi-Project Support**: Per-session working directories
+- 🔍 **Git Integration**: View diffs and track changes across projects
+- 🎯 **Smart Task Orchestration**: PM agent intelligently routes work to specialists
+- ⚡ **50-80% Performance Improvement**: Through intelligent caching and lazy loading
+- 🔒 **Enhanced Security**: Comprehensive input validation and sanitization framework
+
+## Quick Installation
+
+```bash
+pip install claude-mpm
+```
+
+Or with pipx (recommended for isolated installation):
+```bash
+pipx install claude-mpm
+# Configure MCP for pipx users:
+claude-mpm mcp-pipx-config
+```
+
+**That's it!** See [QUICKSTART.md](QUICKSTART.md) for immediate usage or [docs/user/installation.md](docs/user/installation.md) for advanced options.
+
+## Quick Usage
+
+```bash
+# Start interactive mode (recommended)
+claude-mpm
+
+# Start with monitoring dashboard
+claude-mpm run --monitor
+
+# Use MCP Gateway for external tool integration
+claude-mpm mcp
+
+# Run health diagnostics  
+claude-mpm doctor
+
+# Manage memory for large conversation histories
+claude-mpm cleanup-memory
+```
+
+See [QUICKSTART.md](QUICKSTART.md) for complete usage examples.
+
+
+## Architecture (v4.1.0+)
+
+Following continuous improvements through v4.1.0, Claude MPM features:
+
+- **Service-Oriented Architecture**: Five specialized service domains with Socket.IO stability improvements
+- **Interface-Based Contracts**: All services implement explicit interfaces
+- **Dependency Injection**: Service container with automatic resolution
+- **50-80% Performance Improvement**: Through lazy loading and intelligent caching
+- **Enhanced Security**: Comprehensive input validation and sanitization framework
+- **Improved Monitoring**: Enhanced dashboard with hierarchical agent display
+- **Socket.IO Stability**: Major reliability improvements for real-time communication
+
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for detailed architecture information.
+
+## Key Capabilities
+
+### Multi-Agent Orchestration
+
+Claude MPM includes 15 specialized agents:
+
+#### Core Development
+- **Engineer** - Software development and implementation
+- **Research** - Code analysis and research  
+- **Documentation** - Documentation creation and maintenance
+- **QA** - Testing and quality assurance
+- **Security** - Security analysis and implementation
+
+#### Operations & Infrastructure
+- **Ops** - Operations and deployment
+- **Version Control** - Git and version management
+- **Data Engineer** - Data pipeline and ETL development
+
+#### Web Development
+- **Web UI** - Frontend and UI development
+- **Web QA** - Web testing and E2E validation
+
+#### Project Management
+- **Ticketing** - Issue tracking and management
+- **Project Organizer** - File organization and structure
+- **Memory Manager** - Project memory and context management
+
+#### Code Quality
+- **Refactoring Engineer** - Code refactoring and optimization
+- **Code Analyzer** - Static code analysis with AST and tree-sitter
+
+### Agent Memory System
+Agents learn project-specific patterns using a simple list format and can update memories via JSON response fields (`remember` for incremental updates, `MEMORIES` for complete replacement). Initialize with `claude-mpm memory init`.
+
+### MCP Gateway (Model Context Protocol)
+
+Claude MPM includes a powerful MCP Gateway that enables:
+- Integration with external tools and services
+- Custom tool development
+- Protocol-based communication
+- Extensible architecture
+
+See [MCP Gateway Documentation](docs/developer/13-mcp-gateway/README.md) for details.
+
+### Memory Management
+
+Large conversation histories can consume 2GB+ of memory. Use the `cleanup-memory` command to manage Claude conversation history:
+
+```bash
+# Clean up old conversation history
+claude-mpm cleanup-memory
+
+# Keep only recent conversations
+claude-mpm cleanup-memory --days 7
+```
+
+### Real-Time Monitoring
+The `--monitor` flag opens a web dashboard showing live agent activity, file operations, and session management.
+
+See [docs/MEMORY.md](docs/MEMORY.md) and [docs/developer/11-dashboard/README.md](docs/developer/11-dashboard/README.md) for details.
+
+
+## Documentation
+
+### User Documentation
+- **[Quick Start Guide](QUICKSTART.md)** - Get running in 5 minutes
+- **[Installation Guide](docs/user/installation.md)** - Complete installation options
+- **[User Guide](docs/user/)** - Detailed usage documentation
+- **[Memory System](docs/MEMORY.md)** - Agent memory documentation
+- **[Troubleshooting](docs/user/troubleshooting.md)** - Common issues and solutions
+
+### Developer Documentation
+- **[Architecture Overview](docs/ARCHITECTURE.md)** - Service-oriented architecture and design
+- **[API Reference](docs/api/)** - Complete API documentation with Sphinx
+- **[Service Layer Guide](docs/developer/SERVICES.md)** - Service interfaces and implementations
+- **[MCP Gateway Guide](docs/developer/13-mcp-gateway/README.md)** - Model Context Protocol integration
+- **[Performance Guide](docs/PERFORMANCE.md)** - Optimization and caching strategies
+- **[Security Guide](docs/SECURITY.md)** - Security framework and best practices
+- **[Testing Guide](docs/TESTING.md)** - Testing patterns and strategies
+- **[Migration Guide](docs/MIGRATION.md)** - Upgrading from previous versions
+- **[Developer Guide](docs/developer/)** - Comprehensive development documentation
+
+### API Documentation
+Comprehensive API documentation is available at [docs/api/](docs/api/) - build with `make html` in that directory.
+
+## Recent Updates (v4.1.0)
+
+**Socket.IO Stability Improvements**: Major reliability enhancements for real-time communication with improved error handling and connection management.
+
+**Project Organization**: Comprehensive cleanup and reorganization with structured script directories for better maintainability.
+
+**Documentation Consolidation**: Streamlined documentation structure with consolidated guides and improved navigation.
+
+**Agent Hierarchy Display**: Enhanced dashboard with hierarchical agent display showing PM at top level with visual distinction for implied vs explicit nodes.
+
+See [CHANGELOG.md](CHANGELOG.md) for full history and [docs/MIGRATION.md](docs/MIGRATION.md) for upgrade instructions.
+
+## Development
+
+### Quick Development Setup
+```bash
+# Complete development setup with code formatting and quality tools
+make dev-complete
+
+# Or step by step:
+make setup-dev          # Install in development mode
+make setup-pre-commit    # Set up automated code formatting
+```
+
+### Code Quality & Formatting
+The project uses automated code formatting and quality checks:
+- **Black** for code formatting
+- **isort** for import sorting
+- **flake8** for linting
+- **mypy** for type checking
+- **Pre-commit hooks** for automatic enforcement
+
+See [docs/developer/CODE_FORMATTING.md](docs/developer/CODE_FORMATTING.md) for details.
+
+### Contributing
+Contributions are welcome! Please see our [project structure guide](docs/STRUCTURE.md) and follow the established patterns.
+
+**Development Workflow**:
+1. Run `make dev-complete` to set up your environment
+2. Code formatting happens automatically on commit
+3. All code must pass quality checks before merging
+
+### Project Structure
+See [docs/STRUCTURE.md](docs/STRUCTURE.md) for codebase organization.
+
+### License
+MIT License - see [LICENSE](LICENSE) file.
+
+## Credits
+
+- Based on [claude-multiagent-pm](https://github.com/kfsone/claude-multiagent-pm)
+- Enhanced for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) integration
+- Built with ❤️ by the Claude MPM community

claude_mpm-4.1.2/VERSION

@@ -0,0 +1 @@
+4.1.2