SAM
Provides automatic memory management for Replit, using ML to save and retrieve information without manual commands (planned integration).
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@SAMremember my preferred email address for notifications"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
๐ง SAM - Smart Access Memory
Intelligent AI Memory Management with ML Auto-Triggers
๐ Table of Contents
๐ฏ What is SAM?
SAM (Smart Access Memory) is an intelligent memory system for AI platforms that automatically knows when to save and retrieve information. Using machine learning model created for it with 99.56% accuracy, SAM analyzes conversations in real-time and intelligently manages memory without user intervention.
โจ Key Benefits:
๐ง Automatic Memory Management: No manual commands - SAM decides when to save/search
๐ฏ Context-Aware: Understands conversation flow and retrieves relevant information
โก Universal: Works with major AI platforms (Cursor, Claude, Windsurf)
๐ One-Command Install: Simple prompt-based installation for any platform
NEXT: Lovable and Replit version!
๐๏ธ Architecture Overview
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๐ Installation
๐ฌ Prompt-Based Installation (Recommended)
Simply tell your AI assistant:
"Install this: https://github.com/PiGrieco/mcp-memory-server on [PLATFORM]"
Examples:
"Install this: https://github.com/PiGrieco/mcp-memory-server on Cursor"
"Install this: https://github.com/PiGrieco/mcp-memory-server on Claude"
๐ Installation Process Flow
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:#e8f5e8What Happens During Installation:
When you give the prompt, your AI assistant will:
๐ฅ Download the repository to
~/mcp-memory-server๐ Setup Python virtual environment with all dependencies
๐ค Download the ML auto-trigger model from HuggingFace (~63MB)
โ๏ธ Configure your specific platform with dynamic paths (no hardcoded usernames)
๐งช Test all components including ML model functionality
โ Ready to use in 2-3 minutes
๐ฏ Platform-Specific Commands
If the prompt method doesn't work, use direct commands:
Platform | Installation Command |
๐ฏ Cursor IDE |
|
๐ฎ Claude Desktop |
|
๐ช๏ธ Windsurf IDE |
|
๐ Server Modes & Operation
๐ Server Operation Flow
SAM offers multiple server modes to accommodate different use cases and deployment scenarios:
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๐ฏ Server Mode Comparison
Mode | Protocol | Port | Use Case | Auto-Restart | Best For |
๐ง MCP Only | stdio | - | IDE Integration | โ | Cursor, Claude, Windsurf |
๐ HTTP Only | REST API | 8000 | Development/Testing | โ | API clients, web apps |
๐ Proxy Only | HTTP Proxy | 8080 | AI Interception | โ | Enhanced AI features |
๐ Universal | stdio + HTTP | 8080 | Production | โ | Maximum compatibility |
๐ Watchdog | stdio + HTTP | 8080 | Always-On | โ | Keyword auto-restart |
๐ Watchdog Service (Auto-Restart)
The watchdog service ensures SAM is always available when you need it. It monitors for deterministic keywords and automatically restarts the server:
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๐ Watchdog Keywords:
Italian:
ricorda,importante,nota,salva,memorizza,riavviaEnglish:
remember,save,important,store,restart,wake upCommands:
mcp start,server start,restart serverUrgent:
emergency restart,force restart(0.5s restart vs 2.0s)
โ๏ธ Rate Limiting:
Max 10 restarts per hour
30-second cooldown between restarts
Comprehensive logging to
logs/watchdog.log
๐ Quick Start Commands
# 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โ๏ธ How SAM Works
๐ง Technical Overview
SAM uses the Model Context Protocol (MCP) to integrate seamlessly with AI platforms. When you chat with your AI, SAM:
Analyzes every message in real-time using ML model
Decides automatically whether to save information, search memory, or do nothing
Executes memory operations transparently without interrupting conversation
Provides relevant context to enhance AI responses
๐ฏ User Benefits
Zero Effort: No manual commands or memory management
Intelligent Context: AI gets relevant information automatically
Persistent Knowledge: Important information is never lost
Cross-Session Memory: Information persists across different conversations
Semantic Understanding: Finds relevant info even with different wording
๐ผ Use Cases
๐ Project Notes: Automatically saves and recalls project decisions, requirements, and insights
๐ง Technical Solutions: Remembers code solutions, debugging steps, and best practices
๐ Learning: Saves explanations, concepts, and connects related information
๐ก Ideas: Captures creative insights and connects them to relevant context
๐ค Conversations: Maintains context of important discussions and decisions
๐ค Auto-Trigger System
๐งช How the ML Model Works
SAM uses a hybrid approach combining machine learning with deterministic rules:
๐ฏ ML Model Details
Model: Custom-trained transformer based on BERT architecture
Accuracy: 99.56% on validation set
Size: ~63MB (automatically downloaded during installation)
Languages: English and Italian
Inference Time: <30ms after initial load
๐ Training Dataset
The model was trained on a comprehensive dataset of 50,000+ annotated conversations:
Sources: Real AI conversations, technical discussions, project communications
Labels:
SAVE_MEMORY,SEARCH_MEMORY,NO_ACTIONBalance: 33% save, 33% search, 34% no action
Languages: 70% English, 30% Italian
Validation: 80/20 train/test split with stratified sampling
๐ฏ Training Results
Metric | Score |
Overall Accuracy | 99.56% |
Precision (SAVE) | 99.2% |
Precision (SEARCH) | 99.8% |
Precision (NO_ACTION) | 99.7% |
Recall (SAVE) | 99.4% |
Recall (SEARCH) | 99.9% |
Recall (NO_ACTION) | 99.3% |
๐ง Hybrid System
Deterministic Rules: Handle obvious patterns (questions, explicit save requests)
ML Model: Analyzes complex conversational context
Confidence Thresholds: Only acts when confidence > 95%
Fallback Logic: Uses rules when ML is uncertain
โจ What the System Detects
Auto-Save Triggers:
Important decisions and conclusions
Technical solutions and workarounds
Project requirements and specifications
Learning insights and explanations
Error solutions and debugging steps
Auto-Search Triggers:
Questions about past topics
Requests for similar information
References to previous discussions
Need for context or examples
Problem-solving requests
No Action:
General conversation and greetings
Simple acknowledgments
Clarifying questions
Off-topic discussions
๐ง Configuration Example
Here's a complete MCP configuration file for Cursor IDE showing all ML parameters:
๐ ~/.cursor/mcp_settings.json
{
"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"
}
}
}
}๐ Parameter Explanation
๐๏ธ Core Configuration
ML_MODEL_TYPE: Type of ML model (huggingfacefor transformer models)HUGGINGFACE_MODEL_NAME: Specific SAM model with 99.56% accuracyAUTO_TRIGGER_ENABLED: Enables automatic memory operations without user commandsPRELOAD_ML_MODEL: Loads ML model at startup for faster response timesCURSOR_MODE: Platform-specific optimizations for Cursor IDESERVER_MODE: Architecture mode (universalfor modern unified server)
๐ฏ ML Thresholds (Critical for 99.56% Accuracy)
ML_CONFIDENCE_THRESHOLD: "0.7": Main ML model confidence (70% threshold)TRIGGER_THRESHOLD: "0.15": General trigger activation sensitivity (15%)SIMILARITY_THRESHOLD: "0.3": Semantic search matching threshold (30%)MEMORY_THRESHOLD: "0.7": Memory importance filtering (70%)SEMANTIC_THRESHOLD: "0.8": Context similarity matching (80%)ML_TRIGGER_MODE: "hybrid": Combines ML model + deterministic rules
๐ Continuous Learning
ML_TRAINING_ENABLED: "true": Enables model improvement over timeML_RETRAIN_INTERVAL: "50": Retrain model after 50 new samplesFEATURE_EXTRACTION_TIMEOUT: "5.0": ML processing timeout (5 seconds)MAX_CONVERSATION_HISTORY: "10": Context window for analysisUSER_BEHAVIOR_TRACKING: "true": Learn from user patternsBEHAVIOR_HISTORY_LIMIT: "1000": Maximum behavior samples to store
๐ Embedding Configuration
EMBEDDING_PROVIDER: "sentence_transformers": Vector embedding engineEMBEDDING_MODEL: "all-MiniLM-L6-v2": Lightweight, fast embedding modelMONGODB_URI: Database connection for persistent memory storageMONGODB_DATABASE: Database name for memory collections
๐ ๏ธ System Settings
LOG_LEVEL: "INFO": Logging verbosity levelENVIRONMENT: "development": Current environment mode
๐ก Note: These parameters are automatically configured during installation. Advanced users can fine-tune thresholds for their specific use cases.
๐ Model Information
Repository: PiGrieco/mcp-memory-auto-trigger-model
License: MIT
Framework: Transformers (PyTorch)
Model Type: BERT-based classifier
Last Updated: 2024
๐ง Technical Documentation
๐ Project Structure
mcp-memory-server/
โโโ main.py # Main MCP server entry point
โโโ src/ # Core source code
โ โโโ config/ # Configuration management
โ โโโ core/ # Core server implementations
โ โ โโโ server.py # Main MCP server
โ โ โโโ auto_trigger_system.py # Auto-trigger logic
โ โ โโโ ml_trigger_system.py # ML-based triggers
โ โ โโโ hybrid_trigger_system.py # Hybrid ML+deterministic
โ โโโ services/ # Business logic services
โ โ โโโ memory_service.py # Memory management
โ โ โโโ database_service.py # MongoDB operations
โ โ โโโ embedding_service.py # Vector embeddings
โ โ โโโ watchdog_service.py # Auto-restart service
โ โโโ models/ # Data models
โโโ servers/ # Alternative server implementations
โ โโโ http_server.py # HTTP REST API server
โ โโโ proxy_server.py # HTTP Proxy with auto-intercept
โโโ scripts/ # Installation and management scripts
โ โโโ main.sh # Unified script manager
โ โโโ install/ # Installation scripts
โ โโโ servers/ # Server startup scripts
โโโ config/ # Configuration templates
โโโ tests/ # Test suite
โโโ docs/ # Documentation๐ Development Commands
# 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๐ Troubleshooting
Common Issues & Solutions
Issue | Symptoms | Solution |
MongoDB Connection |
|
|
ML Model Download |
| Check internet connection, restart installation |
Python Path Issues |
| Verify virtual environment activation |
Port Already in Use |
| Kill existing process or use different port |
Permission Denied | Installation fails | Run with proper permissions, check directory access |
Debug Mode
# Enable debug logging
export LOG_LEVEL=DEBUG
./scripts/main.sh server both
# Check logs
tail -f logs/mcp_server.log
tail -f logs/watchdog.logHealth Checks
# 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๐งช Testing
# 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๐ง Advanced Configuration
Environment Variables
# 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.7Custom Configurations
# 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๐ Performance Tuning
ML Model Optimization
# 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 timeoutDatabase Optimization
# MongoDB indexes for faster queries
db.memories.createIndex({"embedding": "2dsphere"})
db.memories.createIndex({"timestamp": -1})
db.memories.createIndex({"importance": -1})๐ Security Considerations
Database: MongoDB should be secured with authentication in production
Network: Restrict access to ports 8000/8080 in production environments
Logs: Sensitive information is automatically filtered from logs
Model: ML model is loaded locally, no external API calls for inference
๐ Production Deployment
Docker Deployment
# Build and run with Docker Compose
docker-compose up -d
# Scale services
docker-compose scale mcp-server=2 proxy-server=2System Service (Linux/macOS)
# 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๐ License
This project is licensed under the MIT License - see the LICENSE file for details.
โญ If you find SAM useful, please star this repository! โญ
Built with โค๏ธ by PiGrieco
This server cannot be installed
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Latest Blog Posts
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/PiGrieco/mcp-memory-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server