PiGrieco/mcp-memory-server

graph TB
    subgraph "AI Platforms"
        A[Cursor IDE] --> MCP[MCP Protocol]
        B[Claude Desktop] --> MCP
        C[GPT/OpenAI] --> MCP
        D[Windsurf IDE] --> MCP
        E[Lovable] --> MCP
        F[Replit] --> MCP
    end
    
    subgraph "MCP Memory Server"
        MCP --> G[Auto-Trigger System]
        G --> H[ML Model 99.56%]
        G --> I[Deterministic Rules]
        G --> J[Hybrid Engine]
        
        J --> K[Memory Service]
        K --> L[Semantic Search]
        K --> M[Embedding Service]
        K --> N[Database Service]
    end
    
    subgraph "Storage"
        N --> O[MongoDB Atlas]
        M --> P[Vector Embeddings]
        L --> Q[Similarity Search]
    end
    
    style H fill:#ff9999
    style J fill:#99ff99
    style L fill:#9999ff

graph TD
    A["🚀 User starts installation"] --> B["📦 Choose installation method"]
    
    B --> C1["🔧 Manual Script<br/>./scripts/main.sh install all"]
    B --> C2["🐍 Python Installer<br/>./scripts/install/install.py"]
    B --> C3["🎯 Platform Specific<br/>./scripts/main.sh platform cursor"]
    
    C1 --> D["🔍 Check System Requirements"]
    C2 --> D
    C3 --> D
    
    D --> E1["✅ Python 3.8+ available"]
    D --> E2["✅ MongoDB installed"]
    D --> E3["✅ Git available"]
    D --> E4["❌ Missing dependencies"]
    
    E4 --> F["📥 Auto-install dependencies<br/>homebrew, python packages"]
    E1 --> G
    E2 --> G
    E3 --> G
    F --> G["🏗️ Create virtual environment"]
    
    G --> H["📦 Install Python packages<br/>requirements.txt"]
    H --> I["🗄️ Setup MongoDB connection"]
    I --> J["🤖 Download ML models<br/>sentence-transformers"]
    
    J --> K["📝 Generate configuration files"]
    K --> L1["⚙️ MCP Server config<br/>main.py ready"]
    K --> L2["🌐 HTTP Proxy config<br/>proxy_server.py ready"]
    K --> L3["🐕 Watchdog config<br/>watchdog_service.py ready"]
    
    L1 --> M["🎯 Platform Integration"]
    L2 --> M
    L3 --> M
    
    M --> N1["🖱️ Cursor IDE<br/>Update settings.json"]
    M --> N2["🤖 Claude Desktop<br/>Update config.json"]
    M --> N3["💻 Other platforms<br/>Manual configuration"]
    
    N1 --> O["✅ Installation Complete"]
    N2 --> O
    N3 --> O
    
    O --> P["🚀 Ready to start servers"]
    
    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style D fill:#fff3e0
    style O fill:#e8f5e8
    style P fill:#e8f5e8

graph TD
    A["🎯 User chooses server mode"] --> B["📋 Available modes"]
    
    B --> C1["🧠 MCP Only<br/>./scripts/main.sh server mcp"]
    B --> C2["🌐 HTTP Only<br/>./scripts/main.sh server http"]
    B --> C3["🔄 Proxy Only<br/>./scripts/main.sh server proxy"]
    B --> C4["🚀 Universal<br/>./scripts/main.sh server both"]
    B --> C5["🐕 Watchdog<br/>./scripts/main.sh server watchdog"]
    
    C1 --> D1["🔧 MCP Server startup<br/>main.py"]
    C2 --> D2["🌐 HTTP Server startup<br/>servers/http_server.py"]
    C3 --> D3["🔄 Proxy Server startup<br/>servers/proxy_server.py"]
    C4 --> D4["🚀 Both MCP + Proxy<br/>Universal mode"]
    C5 --> D5["🐕 Watchdog Service<br/>Auto-restart capability"]
    
    D1 --> E1["📡 stdio MCP protocol"]
    D2 --> E2["🌐 HTTP REST API<br/>localhost:8000"]
    D3 --> E3["🔄 HTTP Proxy<br/>localhost:8080"]
    D4 --> E4["📡 stdio + 🌐 HTTP<br/>Full features"]
    D5 --> E5["👂 Keyword monitoring<br/>Auto-restart triggers"]
    
    E1 --> F["🔗 IDE Integration"]
    E2 --> G["🌐 Web/API clients"]
    E3 --> H["🤖 AI Assistant integration"]
    E4 --> I["🎯 Maximum compatibility"]
    E5 --> J["🔄 Always available"]
    
    F --> K["💾 Memory operations"]
    G --> K
    H --> K
    I --> K
    J --> K
    
    K --> L1["🔍 Deterministic triggers<br/>Keywords: ricorda, save, etc."]
    K --> L2["🤖 ML triggers<br/>Semantic analysis"]
    K --> L3["🔀 Hybrid triggers<br/>Combined approach"]
    
    L1 --> M["⚡ Auto-execute actions"]
    L2 --> M
    L3 --> M
    
    M --> N1["💾 save_memory<br/>Store important info"]
    M --> N2["🔍 search_memories<br/>Find relevant context"]
    M --> N3["📊 analyze_message<br/>Context enhancement"]
    
    N1 --> O["🗄️ MongoDB storage"]
    N2 --> O
    N3 --> O
    
    O --> P["✅ Memory system active"]
    
    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style K fill:#fff3e0
    style M fill:#e8f5e8
    style P fill:#e8f5e8

graph TD
    A["🐕 Watchdog Service Active"] --> B["👂 Monitoring input sources"]
    
    B --> C1["⌨️ stdin monitoring<br/>Terminal input"]
    B --> C2["📁 File monitoring<br/>logs/restart_triggers.txt"]
    B --> C3["🔀 Hybrid monitoring<br/>Both sources"]
    
    C1 --> D["🔍 Keyword detection"]
    C2 --> D
    C3 --> D
    
    D --> E1["🇮🇹 Italian keywords<br/>ricorda, importante, nota"]
    D --> E2["🇺🇸 English keywords<br/>remember, save, important"]
    D --> E3["⚡ Urgent commands<br/>emergency restart, force restart"]
    D --> E4["🎯 Direct commands<br/>mcp start, server start"]
    
    E1 --> F["📊 Trigger analysis"]
    E2 --> F
    E3 --> F
    E4 --> F
    
    F --> G{"⚠️ Rate limiting check"}
    
    G -->|"✅ Within limits"| H["🛑 Stop current server<br/>SIGTERM graceful shutdown"]
    G -->|"❌ Rate limited"| I["⏳ Cooldown period<br/>Log and ignore"]
    
    H --> J["⏱️ Restart delay<br/>2.0s normal, 0.5s urgent"]
    
    J --> K["🚀 Start new server<br/>python main.py"]
    
    K --> L{"✅ Server started?"}
    
    L -->|"Success"| M["📝 Log success<br/>✅ Server restart completed"]
    L -->|"Failed"| N["📝 Log error<br/>❌ Server restart failed"]
    
    M --> O["🔄 Continue monitoring"]
    N --> O
    I --> O
    
    O --> B
    
    P["🚨 Server process dies"] --> Q["📊 Status monitoring<br/>Check every 5s"]
    Q --> R{"🔍 Process alive?"}
    R -->|"No"| S["📝 Log status change<br/>❌ Server is not running"]
    R -->|"Yes"| T["📝 Log status change<br/>✅ Server is running"]
    S --> O
    T --> O
    
    style A fill:#e1f5fe
    style D fill:#f3e5f5
    style F fill:#fff3e0
    style H fill:#ffebee
    style K fill:#e8f5e8
    style M fill:#e8f5e8

# Start in different modes
./scripts/main.sh server mcp      # MCP only (IDE integration)
./scripts/main.sh server http     # HTTP only (development)
./scripts/main.sh server proxy    # Proxy only (AI interception)
./scripts/main.sh server both     # Universal (recommended)
./scripts/main.sh server watchdog # Auto-restart on keywords

# Installation commands
./scripts/main.sh install all     # Complete installation
./scripts/main.sh platform cursor # Configure Cursor IDE
./scripts/main.sh platform claude # Configure Claude Desktop

{
  "mcpServers": {
    "mcp-memory-sam": {
      "command": "/path/to/mcp-memory-server/venv/bin/python",
      "args": ["/path/to/mcp-memory-server/main.py"],
      "env": {
        "ML_MODEL_TYPE": "huggingface",
        "HUGGINGFACE_MODEL_NAME": "PiGrieco/mcp-memory-auto-trigger-model",
        "AUTO_TRIGGER_ENABLED": "true",
        "PRELOAD_ML_MODEL": "true",
        "CURSOR_MODE": "true",
        "LOG_LEVEL": "INFO",
        "ENVIRONMENT": "development",
        "SERVER_MODE": "universal",
        "ML_CONFIDENCE_THRESHOLD": "0.7",
        "TRIGGER_THRESHOLD": "0.15",
        "SIMILARITY_THRESHOLD": "0.3",
        "MEMORY_THRESHOLD": "0.7",
        "SEMANTIC_THRESHOLD": "0.8",
        "ML_TRIGGER_MODE": "hybrid",
        "ML_TRAINING_ENABLED": "true",
        "ML_RETRAIN_INTERVAL": "50",
        "FEATURE_EXTRACTION_TIMEOUT": "5.0",
        "MAX_CONVERSATION_HISTORY": "10",
        "USER_BEHAVIOR_TRACKING": "true",
        "BEHAVIOR_HISTORY_LIMIT": "1000",
        "EMBEDDING_PROVIDER": "sentence_transformers",
        "EMBEDDING_MODEL": "all-MiniLM-L6-v2",
        "MONGODB_URI": "mongodb://localhost:27017",
        "MONGODB_DATABASE": "mcp_memory_dev"
      }
    }
  }
}

# Development workflow
./scripts/main.sh server http        # Start HTTP server for testing
./scripts/main.sh server test        # Run test suite
python -m pytest tests/             # Run specific tests

# Environment management
./scripts/main.sh utils env list     # List available environments
./scripts/main.sh utils env switch development  # Switch environment

# Installation variants
./scripts/main.sh install core       # Core dependencies only
./scripts/main.sh install ml         # ML dependencies
./scripts/main.sh install dev        # Development dependencies

# Enable debug logging
export LOG_LEVEL=DEBUG
./scripts/main.sh server both

# Check logs
tail -f logs/mcp_server.log
tail -f logs/watchdog.log

# Test MongoDB connection
python3 -c "import pymongo; print(pymongo.MongoClient().admin.command('ping'))"

# Test ML model
python3 -c "from src.core.ml_trigger_system import MLTriggerSystem; print('ML model OK')"

# Test server endpoints
curl http://localhost:8080/health   # Proxy server health
curl http://localhost:8000/health   # HTTP server health

# Run all tests
pytest tests/ -v

# Run specific test categories
pytest tests/unit/ -v              # Unit tests
pytest tests/integration/ -v       # Integration tests

# Test with coverage
pytest tests/ --cov=src --cov-report=html

# Core settings
export MCP_ENVIRONMENT=production
export LOG_LEVEL=INFO
export MONGODB_URI=mongodb://localhost:27017

# ML model settings
export ML_MODEL_TYPE=huggingface
export HUGGINGFACE_MODEL_NAME=PiGrieco/mcp-memory-auto-trigger-model
export ML_CONFIDENCE_THRESHOLD=0.7

# Trigger thresholds
export TRIGGER_THRESHOLD=0.15
export SIMILARITY_THRESHOLD=0.3
export MEMORY_THRESHOLD=0.7

# Create custom environment
cp config/environments/development.yaml config/environments/custom.yaml
# Edit custom.yaml with your settings
./scripts/main.sh utils env switch custom

# Preload model for faster inference
"PRELOAD_ML_MODEL": "true"

# Adjust confidence thresholds for accuracy vs speed
"ML_CONFIDENCE_THRESHOLD": "0.7"     # Higher = more accurate, slower
"TRIGGER_THRESHOLD": "0.15"          # Lower = more sensitive

# Timeout settings
"FEATURE_EXTRACTION_TIMEOUT": "5.0"  # ML processing timeout

# MongoDB indexes for faster queries
db.memories.createIndex({"embedding": "2dsphere"})
db.memories.createIndex({"timestamp": -1})
db.memories.createIndex({"importance": -1})

# Build and run with Docker Compose
docker-compose up -d

# Scale services
docker-compose scale mcp-server=2 proxy-server=2

# Create systemd service (Linux)
sudo cp deployment/mcp-memory-server.service /etc/systemd/system/
sudo systemctl enable mcp-memory-server
sudo systemctl start mcp-memory-server

# Create launchd service (macOS)
cp deployment/com.mcp.memory-server.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.mcp.memory-server.plist