doobidoo/mcp-memory-service v8.23.1

v8.23.1 - Stale Virtual Environment Prevention System

on GitHub

🛡️ Stale Virtual Environment Prevention System

Critical developer experience enhancement - Comprehensive 6-layer strategy to prevent "stale venv vs source code" version mismatches that caused the v8.23.0 tag validation bug to persist despite the v8.22.2 fix.

🔍 Root Cause Solved

Problem: MCP servers load from site-packages, not source files. System restart doesn't help - it relaunches with the same stale package. This caused source code to show v8.23.0 while venv had v8.5.3, making the tag validation fix appear broken.

Solution: Multi-layer prevention system that automatically guides developers to use pip install -e . for proper editable installs.

✨ What's New

🛡️ Phase 1: Automated Detection

• New Script: scripts/validation/check_dev_setup.py - Validates source/venv version consistency, detects editable installs
• Enhanced Pre-commit Hook: Blocks commits when venv is stale, provides actionable error messages
• Documentation: Added CLAUDE.md development setup section with explicit pip install -e . guidance

⚠️ Phase 2: Runtime Warnings

• Server Checks: New check_version_consistency() function in server.py warns on startup if versions mismatch
• Developer Docs: Updated README.md developer section and docs/development/ai-agent-instructions.md with proper setup commands

🤖 Phase 3: Interactive Onboarding

• Smart Install: install.py now detects developer mode (checks for git repo) and prompts for editable install
• CI/CD Validation: New workflow .github/workflows/dev-setup-validation.yml with 5 comprehensive test jobs:
  1. Version consistency validation
  2. Pre-commit hook functionality
  3. Server startup warnings
  4. Interactive developer prompts
  5. Documentation accuracy checks

🎯 6-Layer Prevention System

📦 Installation

For Developers

# Clone repository
git clone https://github.com/doobidoo/mcp-memory-service.git
cd mcp-memory-service

# Install in editable mode (CRITICAL for development)
pip install -e .

# Verify setup
python scripts/validation/check_dev_setup.py

For Users

# Standard installation (unchanged)
python scripts/installation/install.py

🔄 Migration Notes

• For Developers: Run pip install -e . to install in editable mode (will be prompted by install.py)
• For Users: No action required - prevention system is transparent for production use
• Pre-commit Hook: Automatically installed during install.py, validates on every commit

🐛 Commits Included

• 670fb74 - Phase 1: Automated detection (check_dev_setup.py, pre-commit hook, CLAUDE.md)
• 9537259 - Phase 2: Runtime warnings (server.py) + developer documentation
• a17bcc7 - Phase 3: Interactive onboarding (install.py) + CI/CD validation

📁 Files Modified

• scripts/validation/check_dev_setup.py - NEW automated detection script
• scripts/hooks/pre-commit - Enhanced with venv validation
• CLAUDE.md - Added development setup guidance
• src/mcp_memory_service/server.py - Added runtime version check
• README.md - Updated developer section
• docs/development/ai-agent-instructions.md - Updated setup commands
• scripts/installation/install.py - Added developer detection
• .github/workflows/dev-setup-validation.yml - NEW CI/CD validation

📚 Documentation

• CHANGELOG.md - Complete changelog entry
• CLAUDE.md - Developer guidance
• README.md - Updated installation instructions

Full Changelog: v8.23.0...v8.23.1