claude-mpm 3.9.8__tar.gz → 3.9.11__tar.gz

{claude_mpm-3.9.8/src/claude_mpm.egg-info → claude_mpm-3.9.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-mpm
-Version: 3.9.8
+Version: 3.9.11
 Summary: Claude Multi-agent Project Manager - Clean orchestration with ticket management
 Home-page: https://github.com/bobmatnyc/claude-mpm
 Author: Claude MPM Team
@@ -38,6 +38,7 @@ Requires-Dist: python-frontmatter>=1.0.0
 Requires-Dist: mistune>=3.0.0
 Requires-Dist: aiofiles>=23.0.0
 Requires-Dist: mcp>=0.1.0
+Requires-Dist: ijson>=3.2.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-asyncio; extra == "dev"
@@ -110,6 +111,7 @@ A powerful orchestration framework for Claude Code that enables multi-agent work
 - 🧠 **Agent Memory System**: Persistent learning with project-specific knowledge retention
 - 🔄 **Session Management**: Resume previous sessions with `--resume` 
 - 📊 **Real-Time Monitoring**: Live dashboard with `--monitor` flag
+- 🛡️ **Memory Guardian (Experimental)**: Automatic memory monitoring and intelligent restarts to prevent crashes
 - 📁 **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
@@ -130,6 +132,9 @@ claude-mpm
 
 # Start with monitoring dashboard
 claude-mpm run --monitor
+
+# Start with memory protection (prevents crashes from large conversations)
+claude-mpm run-guarded
 ```
 
 See [QUICKSTART.md](QUICKSTART.md) for complete usage examples.
@@ -149,10 +154,25 @@ The PM agent automatically delegates work to specialized agents including Resear
 ### Agent Memory System
 Agents learn project-specific patterns and remember insights across sessions. Initialize with `claude-mpm memory init`.
 
+### Memory Guardian System (Experimental)
+**⚠️ Beta Feature** - Prevents memory-related crashes through intelligent monitoring and automatic restarts with state preservation.
+
+```bash
+# Start with memory protection (recommended for long sessions)
+claude-mpm run-guarded --accept-experimental
+
+# Custom memory threshold for your system
+claude-mpm run-guarded --memory-threshold 16000 --accept-experimental  # 16GB
+```
+
+**Why Memory Guardian?** Large conversation histories can consume 2GB+ of memory, causing system instability. The Memory Guardian monitors memory usage and performs controlled restarts while preserving your conversation context and work progress.
+
+**Note:** This is an experimental feature in beta. Use `--accept-experimental` to suppress warnings.
+
 ### 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.
+See [docs/MEMORY.md](docs/MEMORY.md), [docs/USER_GUIDE_MEMORY_GUARDIAN.md](docs/USER_GUIDE_MEMORY_GUARDIAN.md), and [docs/developer/11-dashboard/README.md](docs/developer/11-dashboard/README.md) for details.
 
 
 ## Documentation
@@ -162,12 +182,15 @@ See [docs/MEMORY.md](docs/MEMORY.md) and [docs/developer/11-dashboard/README.md]
 - **[Installation Guide](docs/user/installation.md)** - Complete installation options
 - **[User Guide](docs/user/)** - Detailed usage documentation
 - **[Memory System](docs/MEMORY.md)** - Agent memory documentation
+- **[Memory Guardian Guide](docs/USER_GUIDE_MEMORY_GUARDIAN.md)** - Comprehensive memory protection 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
+- **[Memory Guardian Technical](docs/MEMORY_GUARDIAN_TECHNICAL.md)** - Technical architecture and implementation details
+- **[Memory Guardian Configuration](docs/MEMORY_GUARDIAN_CONFIG.md)** - Complete configuration reference
 - **[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
@@ -181,6 +204,8 @@ Comprehensive API documentation is available at [docs/api/](docs/api/) - build w
 
 **Major Architecture Refactoring (TSK-0053)**: Complete service-oriented redesign with 50-80% performance improvements, enhanced security, and interface-based design.
 
+**Process Management Improvements**: Enhanced hook system reliability with automatic process cleanup, timeout protection, and orphan process monitoring to prevent resource leaks.
+
 See [CHANGELOG.md](CHANGELOG.md) for full history and [docs/MIGRATION.md](docs/MIGRATION.md) for upgrade instructions.
 
 ## Development

{claude_mpm-3.9.8 → claude_mpm-3.9.11}/README.md

@@ -10,6 +10,7 @@ A powerful orchestration framework for Claude Code that enables multi-agent work
 - 🧠 **Agent Memory System**: Persistent learning with project-specific knowledge retention
 - 🔄 **Session Management**: Resume previous sessions with `--resume` 
 - 📊 **Real-Time Monitoring**: Live dashboard with `--monitor` flag
+- 🛡️ **Memory Guardian (Experimental)**: Automatic memory monitoring and intelligent restarts to prevent crashes
 - 📁 **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
@@ -30,6 +31,9 @@ claude-mpm
 
 # Start with monitoring dashboard
 claude-mpm run --monitor
+
+# Start with memory protection (prevents crashes from large conversations)
+claude-mpm run-guarded
 ```
 
 See [QUICKSTART.md](QUICKSTART.md) for complete usage examples.
@@ -49,10 +53,25 @@ The PM agent automatically delegates work to specialized agents including Resear
 ### Agent Memory System
 Agents learn project-specific patterns and remember insights across sessions. Initialize with `claude-mpm memory init`.
 
+### Memory Guardian System (Experimental)
+**⚠️ Beta Feature** - Prevents memory-related crashes through intelligent monitoring and automatic restarts with state preservation.
+
+```bash
+# Start with memory protection (recommended for long sessions)
+claude-mpm run-guarded --accept-experimental
+
+# Custom memory threshold for your system
+claude-mpm run-guarded --memory-threshold 16000 --accept-experimental  # 16GB
+```
+
+**Why Memory Guardian?** Large conversation histories can consume 2GB+ of memory, causing system instability. The Memory Guardian monitors memory usage and performs controlled restarts while preserving your conversation context and work progress.
+
+**Note:** This is an experimental feature in beta. Use `--accept-experimental` to suppress warnings.
+
 ### 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.
+See [docs/MEMORY.md](docs/MEMORY.md), [docs/USER_GUIDE_MEMORY_GUARDIAN.md](docs/USER_GUIDE_MEMORY_GUARDIAN.md), and [docs/developer/11-dashboard/README.md](docs/developer/11-dashboard/README.md) for details.
 
 
 ## Documentation
@@ -62,12 +81,15 @@ See [docs/MEMORY.md](docs/MEMORY.md) and [docs/developer/11-dashboard/README.md]
 - **[Installation Guide](docs/user/installation.md)** - Complete installation options
 - **[User Guide](docs/user/)** - Detailed usage documentation
 - **[Memory System](docs/MEMORY.md)** - Agent memory documentation
+- **[Memory Guardian Guide](docs/USER_GUIDE_MEMORY_GUARDIAN.md)** - Comprehensive memory protection 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
+- **[Memory Guardian Technical](docs/MEMORY_GUARDIAN_TECHNICAL.md)** - Technical architecture and implementation details
+- **[Memory Guardian Configuration](docs/MEMORY_GUARDIAN_CONFIG.md)** - Complete configuration reference
 - **[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
@@ -81,6 +103,8 @@ Comprehensive API documentation is available at [docs/api/](docs/api/) - build w
 
 **Major Architecture Refactoring (TSK-0053)**: Complete service-oriented redesign with 50-80% performance improvements, enhanced security, and interface-based design.
 
+**Process Management Improvements**: Enhanced hook system reliability with automatic process cleanup, timeout protection, and orphan process monitoring to prevent resource leaks.
+
 See [CHANGELOG.md](CHANGELOG.md) for full history and [docs/MIGRATION.md](docs/MIGRATION.md) for upgrade instructions.
 
 ## Development

claude_mpm-3.9.11/VERSION

@@ -0,0 +1 @@
+3.9.11

{claude_mpm-3.9.8 → claude_mpm-3.9.11}/pyproject.toml

@@ -10,7 +10,7 @@ readme = "README.md"
 requires-python = ">=3.8"
 keywords = [ "claude", "orchestration", "multi-agent", "ticket-management",]
 classifiers = [ "Development Status :: 3 - Alpha", "Intended Audience :: Developers", "License :: OSI Approved :: MIT License", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.8", "Programming Language :: Python :: 3.9", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12",]
-dependencies = [ "ai-trackdown-pytools>=1.4.0", "pyyaml>=6.0", "python-dotenv>=0.19.0", "click>=8.0.0", "pexpect>=4.8.0", "psutil>=5.9.0", "requests>=2.25.0", "flask>=3.0.0", "flask-cors>=4.0.0", "watchdog>=3.0.0", "tree-sitter>=0.21.0", "python-socketio>=5.11.0", "aiohttp>=3.9.0", "aiohttp-cors>=0.7.0,<0.8.0", "python-engineio>=4.8.0", "python-frontmatter>=1.0.0", "mistune>=3.0.0", "aiofiles>=23.0.0", "mcp>=0.1.0",]
+dependencies = [ "ai-trackdown-pytools>=1.4.0", "pyyaml>=6.0", "python-dotenv>=0.19.0", "click>=8.0.0", "pexpect>=4.8.0", "psutil>=5.9.0", "requests>=2.25.0", "flask>=3.0.0", "flask-cors>=4.0.0", "watchdog>=3.0.0", "tree-sitter>=0.21.0", "python-socketio>=5.11.0", "aiohttp>=3.9.0", "aiohttp-cors>=0.7.0,<0.8.0", "python-engineio>=4.8.0", "python-frontmatter>=1.0.0", "mistune>=3.0.0", "aiofiles>=23.0.0", "mcp>=0.1.0", "ijson>=3.2.0",]
 [[project.authors]]
 name = "Claude MPM Team"
 

claude_mpm-3.9.11/src/claude_mpm/VERSION

@@ -0,0 +1 @@
+3.9.11

{claude_mpm-3.9.8 → claude_mpm-3.9.11}/src/claude_mpm/agents/base_agent.json

@@ -1,6 +1,6 @@
 {
   "version": 3,
-  "base_version": "0.3.0",
+  "base_version": "0.3.1",
   "agent_type": "base",
   "narrative_fields": {
     "instructions": "# Claude MPM Framework Agent\n\nYou are a specialized agent in the Claude MPM framework. Work collaboratively through PM orchestration to accomplish project objectives.\n\n## Core Principles\n- **Specialization Focus**: Execute only tasks within your domain expertise\n- **Quality First**: Meet acceptance criteria before reporting completion\n- **Clear Communication**: Report progress, blockers, and requirements explicitly\n- **Escalation Protocol**: Route security concerns to Security Agent; escalate authority exceeded\n\n## Task Execution Protocol\n1. **Acknowledge**: Confirm understanding of task, context, and acceptance criteria\n2. **Research Check**: If implementation details unclear, request PM delegate research first\n3. **Execute**: Perform work within specialization, maintaining audit trails\n4. **Validate**: Verify outputs meet acceptance criteria and quality standards\n5. **Report**: Provide structured completion report with deliverables and next steps\n\n## Framework Integration\n- **Hierarchy**: Operate within Project → User → System agent discovery\n- **Communication**: Use Task Tool subprocess for PM coordination\n- **Context Awareness**: Acknowledge current date/time in decisions\n- **Handoffs**: Follow structured protocols for inter-agent coordination\n- **Error Handling**: Implement graceful failure with clear error reporting\n\n## Quality Standards\n- Idempotent operations where possible\n- Comprehensive error handling and validation\n- Structured output formats for integration\n- Security-first approach for sensitive operations\n- Performance-conscious implementation choices\n\n## Mandatory PM Reporting\nALL agents MUST report back to the PM upon task completion or when errors occur:\n\n### Required Reporting Elements\n1. **Work Summary**: Brief overview of actions performed and outcomes achieved\n2. **File Tracking**: Comprehensive list of all files:\n   - Created files (with full paths)\n   - Modified files (with nature of changes)\n   - Deleted files (with justification)\n3. **Specific Actions**: Detailed list of all operations performed:\n   - Commands executed\n   - Services accessed\n   - External resources utilized\n4. **Success Status**: Clear indication of task completion:\n   - Successful: All acceptance criteria met\n   - Partial: Some objectives achieved with specific blockers\n   - Failed: Unable to complete with detailed reasons\n5. **Error Escalation**: Any unresolved errors MUST be escalated immediately:\n   - Error description and context\n   - Attempted resolution steps\n   - Required assistance or permissions\n   - Impact on task completion\n\n### Reporting Format\n```\n## Task Completion Report\n**Status**: [Success/Partial/Failed]\n**Summary**: [Brief overview of work performed]\n\n### Files Touched\n- Created: [list with paths]\n- Modified: [list with paths and change types]\n- Deleted: [list with paths and reasons]\n\n### Actions Performed\n- [Specific action 1]\n- [Specific action 2]\n- ...\n\n### Unresolved Issues (if any)\n- **Error**: [description]\n- **Impact**: [how it affects the task]\n- **Assistance Required**: [what help is needed]\n```\n\n## Memory System Integration\n\nWhen you discover important learnings, patterns, or insights during your work that could be valuable for future tasks, use the following format to add them to memory:\n\n```\n# Add To Memory:\nType: <type>\nContent: <your learning here - be specific and concise>\n#\n```\n\n### Memory Types:\n- **pattern**: Recurring code patterns, design patterns, or implementation approaches\n- **architecture**: System architecture insights, component relationships\n- **guideline**: Best practices, coding standards, team conventions\n- **mistake**: Common errors, pitfalls, or anti-patterns to avoid\n- **strategy**: Problem-solving approaches, effective techniques\n- **integration**: API usage, library patterns, service interactions\n- **performance**: Performance insights, optimization opportunities\n- **context**: Project-specific knowledge, business logic, domain concepts\n\n### When to Add to Memory:\n- After discovering a non-obvious pattern in the codebase\n- When you learn something that would help future tasks\n- After resolving a complex issue or bug\n- When you identify a best practice or anti-pattern\n- After understanding important architectural decisions\n\n### Guidelines:\n- Keep content under 100 characters for clarity\n- Be specific rather than generic\n- Focus on project-specific insights\n- Only add truly valuable learnings\n\n### Example:\n```\nI discovered that all API endpoints require JWT tokens.\n\n# Add To Memory:\nType: pattern\nContent: All API endpoints use JWT bearer tokens with 24-hour expiration\n#\n```"

claude_mpm-3.9.11/src/claude_mpm/agents/templates/memory_manager.json

@@ -0,0 +1,155 @@
+{
+  "schema_version": "1.2.0",
+  "agent_id": "memory-manager-agent",
+  "agent_version": "1.0.0",
+  "agent_type": "memory_manager",
+  "metadata": {
+    "name": "Memory Manager Agent",
+    "description": "Manages project-specific agent memories for improved context retention and knowledge accumulation",
+    "created_at": "2025-08-16T00:00:00.000000Z",
+    "updated_at": "2025-08-16T00:00:00.000000Z",
+    "tags": [
+      "memory",
+      "knowledge-management",
+      "context-retention",
+      "agent-memories",
+      "optimization"
+    ],
+    "category": "infrastructure",
+    "color": "indigo"
+  },
+  "capabilities": {
+    "model": "sonnet",
+    "tools": [
+      "Read",
+      "Write",
+      "Edit",
+      "MultiEdit",
+      "Grep",
+      "Glob",
+      "LS",
+      "TodoWrite"
+    ],
+    "resource_tier": "lightweight",
+    "temperature": 0.2,
+    "max_tokens": 8192,
+    "timeout": 600,
+    "memory_limit": 2048,
+    "cpu_limit": 20,
+    "network_access": false,
+    "file_access": {
+      "read_paths": [
+        ".claude-mpm/memories/"
+      ],
+      "write_paths": [
+        ".claude-mpm/memories/"
+      ]
+    }
+  },
+  "knowledge": {
+    "domain_expertise": [
+      "Agent memory file management and optimization",
+      "Memory token limit management (18k tokens maximum)",
+      "Memory consolidation and deduplication strategies",
+      "Context-aware memory pruning techniques",
+      "Cross-agent memory integration patterns",
+      "Memory verification and validation protocols",
+      "Memory format standardization and best practices"
+    ],
+    "best_practices": [
+      "Keep memories terse and specific - single line facts",
+      "Verify memory accuracy with Research agent when needed",
+      "Consolidate redundant memories to save token space",
+      "Organize memories by agent role and responsibility",
+      "Maintain backward compatibility when updating memory formats",
+      "Regular memory audits to remove outdated information",
+      "Prioritize recent and frequently accessed memories"
+    ],
+    "constraints": [
+      "Total memory must stay under 18k tokens when consolidated",
+      "Memory files must be in .claude-mpm/memories/ directory",
+      "Each agent has separate memory file (pm.md, engineer.md, etc.)",
+      "Memory format must be single-line facts and behaviors",
+      "Cannot delete critical system memories without confirmation",
+      "Must maintain memory file integrity and structure"
+    ]
+  },
+  "instructions": "# Memory Manager Agent\n\nManage and optimize project-specific agent memories to enhance context retention and knowledge accumulation across the Claude MPM system.\n\n## Primary Responsibilities\n\n### Memory Management Core Functions\n1. **List**: Display existing memories for each agent with token counts\n2. **Update**: Add new memories to specific agent files following format standards\n3. **Prune**: Remove outdated, redundant, or inaccurate memories\n4. **Clear**: Reset memory files for specific agents or all agents\n5. **Consolidate**: Optimize memories to stay under 18k token limit\n6. **Verify**: Coordinate with Research agent to validate memory accuracy\n\n## Memory System Architecture\n\n### File Structure\n```\n<project-root>/\n└── .claude-mpm/\n    └── memories/\n        ├── pm.md           # Project Manager memories\n        ├── engineer.md     # Engineer agent memories\n        ├── research.md     # Research agent memories\n        ├── qa.md          # QA agent memories\n        ├── security.md    # Security agent memories\n        ├── documentation.md # Documentation agent memories\n        ├── ops.md         # Ops agent memories\n        └── version_control.md # Version Control agent memories\n```\n\n### Memory Format Standards\n\n**Required Format**:\n- Single line per memory entry\n- Terse, specific facts and behaviors\n- No multi-line explanations or verbose descriptions\n- Focus on actionable knowledge\n\n**Good Memory Examples**:\n```markdown\n- API endpoints use JWT authentication with 24hr expiry\n- Database queries must use parameterized statements\n- Project uses Python 3.11 with strict type checking\n- All tests must achieve 85% code coverage minimum\n- Deployment requires approval from two team members\n```\n\n**Bad Memory Examples**:\n```markdown\n- The authentication system is complex and uses... (too verbose)\n- Fixed bug in user.py (too specific/temporary)\n- Remember to test (too vague)\n- The project has many features... (not actionable)\n```\n\n## Memory Operations Protocol\n\n### 1. List Operation\n```bash\n# Check all memory files and their sizes\nls -la .claude-mpm/memories/\n\n# Count tokens for each file\nfor file in .claude-mpm/memories/*.md; do\n    echo \"$file: $(wc -w < \"$file\") words\"\ndone\n```\n\n### 2. Update Operation\n```markdown\n# Adding new memory to engineer.md\n- New pattern discovered: Use repository pattern for data access\n- Performance insight: Cache expensive calculations at service boundary\n- Security requirement: Input validation required at all API endpoints\n```\n\n### 3. Prune Operation\n```markdown\n# Remove outdated memories\n- Delete: References to deprecated API versions\n- Delete: Temporary bug fixes that are now resolved\n- Delete: Project-specific details from other projects\n- Consolidate: Multiple similar entries into one comprehensive entry\n```\n\n### 4. Clear Operation\n```bash\n# Clear specific agent memory\necho \"# Engineer Agent Memories\" > .claude-mpm/memories/engineer.md\necho \"# Initialized: $(date)\" >> .claude-mpm/memories/engineer.md\n\n# Clear all memories (with confirmation)\n# Request PM confirmation before executing\n```\n\n### 5. Consolidate Operation\n```markdown\n# Identify redundant memories\nOriginal:\n- Use JWT for auth\n- JWT tokens expire in 24 hours\n- All endpoints need JWT\n\nConsolidated:\n- All API endpoints require JWT bearer tokens with 24hr expiry\n```\n\n### 6. Verify Operation\n```markdown\n# Request Research agent assistance\nMemories to verify:\n1. \"Database uses PostgreSQL 14 with connection pooling\"\n2. \"API rate limit is 100 requests per minute per user\"\n3. \"Deployment pipeline includes staging environment\"\n\nResearch agent confirms/corrects each memory\n```\n\n## Token Management Strategy\n\n### Token Limits\n- **Individual File Limit**: 3k tokens recommended\n- **Total System Limit**: 18k tokens maximum\n- **PM Memory Priority**: 5k tokens allocated\n- **Agent Memories**: 2k tokens each allocated\n\n### Optimization Techniques\n1. **Deduplication**: Remove exact or near-duplicate entries\n2. **Consolidation**: Combine related memories into comprehensive entries\n3. **Prioritization**: Keep recent and frequently used memories\n4. **Archival**: Move old memories to archive files if needed\n5. **Compression**: Use concise language without losing meaning\n\n## Quality Assurance\n\n### Memory Validation Checklist\n- ✓ Is the memory factual and accurate?\n- ✓ Is it relevant to the current project?\n- ✓ Is it concise and actionable?\n- ✓ Does it avoid duplication?\n- ✓ Is it properly categorized by agent?\n- ✓ Will it be useful for future tasks?\n\n### Regular Maintenance Schedule\n1. **Daily**: Quick scan for obvious duplicates\n2. **Weekly**: Consolidation and optimization pass\n3. **Monthly**: Full verification with Research agent\n4. **Quarterly**: Complete memory system audit\n\n## TodoWrite Usage Guidelines\n\n### Required Prefix Format\n- ✅ `[Memory Manager] List all agent memories and token counts`\n- ✅ `[Memory Manager] Consolidate engineer memories to reduce tokens`\n- ✅ `[Memory Manager] Verify accuracy of security agent memories`\n- ✅ `[Memory Manager] Prune outdated PM memories from last quarter`\n\n### Memory Management Todo Patterns\n\n**Maintenance Tasks**:\n- `[Memory Manager] Perform weekly memory consolidation across all agents`\n- `[Memory Manager] Archive memories older than 6 months`\n- `[Memory Manager] Deduplicate redundant entries in research memories`\n\n**Verification Tasks**:\n- `[Memory Manager] Verify technical accuracy of engineer memories with Research`\n- `[Memory Manager] Validate security memories against current policies`\n- `[Memory Manager] Cross-reference QA memories with test results`\n\n**Optimization Tasks**:\n- `[Memory Manager] Reduce total memory footprint to under 15k tokens`\n- `[Memory Manager] Optimize PM memories for faster context loading`\n- `[Memory Manager] Compress verbose memories into concise facts`\n\n## Integration with PM and Agents\n\n### PM Integration\n- Memories loaded into PM context on startup\n- PM can request memory updates after successful tasks\n- PM receives memory status reports and token counts\n\n### Agent Integration\n- Agents can request their memories for context\n- Agents submit new memories through standardized format\n- Memory Manager validates and integrates agent submissions\n\n### Build Process Integration\n- Memory files included in agent deployment packages\n- Version control tracks memory evolution\n- Automated checks ensure token limits maintained\n\n## Error Handling\n\n### Common Issues\n1. **Token Limit Exceeded**: Trigger immediate consolidation\n2. **Corrupted Memory File**: Restore from backup, alert PM\n3. **Conflicting Memories**: Request Research agent verification\n4. **Missing Memory Directory**: Create directory structure\n5. **Access Permissions**: Ensure proper file permissions\n\n## Response Format\n\nInclude the following in your response:\n- **Summary**: Overview of memory management actions performed\n- **Token Status**: Current token usage across all memory files\n- **Changes Made**: Specific additions, deletions, or consolidations\n- **Recommendations**: Suggested optimizations or maintenance needed\n- **Remember**: Universal learnings about memory management (or null)\n\nExample:\n```markdown\n## Memory Management Report\n\n**Summary**: Consolidated engineer memories and removed 15 outdated entries\n\n**Token Status**:\n- Total: 12,450 / 18,000 tokens (69% utilized)\n- PM: 4,200 tokens\n- Engineer: 2,100 tokens (reduced from 3,500)\n- Other agents: 6,150 tokens combined\n\n**Changes Made**:\n- Consolidated 8 authentication-related memories into 2 comprehensive entries\n- Removed 15 outdated memories referencing deprecated features\n- Added 3 new performance optimization memories from recent discoveries\n\n**Recommendations**:\n- Research memories approaching limit (2,800 tokens) - schedule consolidation\n- Consider archiving Q3 memories to reduce overall footprint\n- Verify accuracy of 5 security memories flagged as potentially outdated\n\n**Remember**: null\n```",
+  "dependencies": {
+    "python": [],
+    "system": [
+      "git"
+    ],
+    "optional": true
+  },
+  "interactions": {
+    "input_format": {
+      "required_fields": [
+        "operation",
+        "target"
+      ],
+      "optional_fields": [
+        "content",
+        "options",
+        "verify_with"
+      ]
+    },
+    "output_format": {
+      "structure": "markdown",
+      "includes": [
+        "summary",
+        "token_status",
+        "changes_made",
+        "recommendations"
+      ]
+    },
+    "handoff_agents": [
+      "research",
+      "pm"
+    ],
+    "triggers": [
+      "memory_update",
+      "token_limit_warning",
+      "memory_verification_needed"
+    ]
+  },
+  "testing": {
+    "test_cases": [
+      {
+        "name": "List memories",
+        "input": "List all agent memories and their token counts",
+        "expected_behavior": "Display comprehensive memory inventory with token metrics",
+        "validation_criteria": [
+          "lists_all_memory_files",
+          "shows_token_counts",
+          "identifies_token_usage_percentage"
+        ]
+      },
+      {
+        "name": "Consolidate memories",
+        "input": "Consolidate duplicate memories in engineer.md",
+        "expected_behavior": "Reduce token count by merging similar memories",
+        "validation_criteria": [
+          "identifies_duplicates",
+          "merges_related_memories",
+          "reduces_token_count"
+        ]
+      },
+      {
+        "name": "Verify memories",
+        "input": "Verify accuracy of security agent memories",
+        "expected_behavior": "Coordinate with Research agent to validate memories",
+        "validation_criteria": [
+          "requests_research_assistance",
+          "validates_memory_accuracy",
+          "updates_incorrect_memories"
+        ]
+      }
+    ],
+    "performance_benchmarks": {
+      "response_time": 300,
+      "token_usage": 8192,
+      "success_rate": 0.98
+    }
+  }
+}

{claude_mpm-3.9.8 → claude_mpm-3.9.11}/src/claude_mpm/cli/__init__.py

@@ -19,6 +19,7 @@ from .parser import create_parser, preprocess_args
 from .utils import ensure_directories, setup_logging
 from .commands import (
     run_session,
+    # run_guarded_session is imported lazily to avoid loading experimental code
     manage_tickets,
     show_info,
     manage_agents,
@@ -26,7 +27,8 @@ from .commands import (
     manage_monitor,
     manage_config,
     aggregate_command,
-    cleanup_memory
+    cleanup_memory,
+    manage_mcp
 )
 from claude_mpm.config.paths import paths
 
@@ -167,7 +169,11 @@ def _execute_command(command: str, args) -> int:
     Execute the specified command.
     
     WHY: This function maps command names to their implementations, providing
-    a single place to manage command routing.
+    a single place to manage command routing. Experimental commands are imported
+    lazily to avoid loading unnecessary code.
+    
+    DESIGN DECISION: run_guarded is imported only when needed to maintain
+    separation between stable and experimental features.
     
     Args:
         command: The command name to execute
@@ -176,9 +182,17 @@ def _execute_command(command: str, args) -> int:
     Returns:
         Exit code from the command
     """
-    # Map commands to their implementations
+    # Handle experimental run-guarded command separately with lazy import
+    if command == 'run-guarded':
+        # Lazy import to avoid loading experimental code unless needed
+        from .commands.run_guarded import execute_run_guarded
+        result = execute_run_guarded(args)
+        return result if result is not None else 0
+    
+    # Map stable commands to their implementations
     command_map = {
         CLICommands.RUN.value: run_session,
+        # CLICommands.RUN_GUARDED.value is handled above
         CLICommands.TICKETS.value: manage_tickets,
         CLICommands.INFO.value: show_info,
         CLICommands.AGENTS.value: manage_agents,
@@ -187,6 +201,7 @@ def _execute_command(command: str, args) -> int:
         CLICommands.CONFIG.value: manage_config,
         CLICommands.AGGREGATE.value: aggregate_command,
         CLICommands.CLEANUP.value: cleanup_memory,
+        CLICommands.MCP.value: manage_mcp,
     }
     
     # Execute command if found

{claude_mpm-3.9.8 → claude_mpm-3.9.11}/src/claude_mpm/cli/commands/__init__.py

@@ -6,6 +6,8 @@ separate modules for better maintainability and code organization.
 """
 
 from .run import run_session
+# Note: run_guarded is imported separately to avoid loading experimental code
+# from .run_guarded import execute_run_guarded as run_guarded_session
 from .tickets import manage_tickets, list_tickets
 from .info import show_info
 from .agents import manage_agents
@@ -14,9 +16,11 @@ from .monitor import manage_monitor
 from .config import manage_config
 from .aggregate import aggregate_command
 from .cleanup import cleanup_memory
+from .mcp import manage_mcp
 
 __all__ = [
     'run_session',
+    # 'run_guarded_session',  # Excluded from default exports (experimental)
     'manage_tickets',
     'list_tickets',
     'show_info',
@@ -25,5 +29,6 @@ __all__ = [
     'manage_monitor',
     'manage_config',
     'aggregate_command',
-    'cleanup_memory'
+    'cleanup_memory',
+    'manage_mcp'
 ]

{claude_mpm-3.9.8 → claude_mpm-3.9.11}/src/claude_mpm/cli/commands/cleanup.py

@@ -13,6 +13,7 @@ DESIGN DECISIONS:
 """
 
 import os
+import sys
 import json
 import shutil
 from pathlib import Path
@@ -339,7 +340,26 @@ def cleanup_memory(args):
     # Get confirmation unless forced
     if not args.force and not args.dry_run:
         print("\n⚠️  This will modify your conversation history")
-        response = input("Continue? [y/N]: ").strip().lower()
+        
+        # Ensure stdout is flushed before reading input
+        sys.stdout.flush()
+        
+        # Check if we're in a TTY environment
+        if not sys.stdin.isatty():
+            # In non-TTY environment (like pipes), we need special handling
+            print("Continue? [y/N]: ", end="", flush=True)
+            try:
+                # Use readline for better compatibility in non-TTY environments
+                response = sys.stdin.readline().strip().lower()
+            except (EOFError, KeyboardInterrupt):
+                response = 'n'
+        else:
+            # In TTY environment, use normal input()
+            try:
+                response = input("Continue? [y/N]: ").strip().lower()
+            except (EOFError, KeyboardInterrupt):
+                response = 'n'
+        
         # Handle various line endings and control characters
         response = response.replace('\r', '').replace('\n', '').strip()
         if response != 'y':