Samantha is a sophisticated MCP (Model Context Protocol) server that dynamically extracts and manages user memory from LLM conversations. This memory can be shared across different LLMs, allowing for consistent personalization even when switching between models.

Samantha analyzes conversations, extracting information about learning styles, topics of interest, knowledge levels, and personal preferences, creating a comprehensive user profile that LLMs can use to provide tailored responses.

• Dynamic Memory Extraction - Automatically identifies learning styles, topics, and preferences from conversations
• Learning Style Analysis - Uses the VARK model (Visual, Auditory, Reading/Writing, Kinesthetic) with detailed recommendations
• Topic Relationship Mapping - Creates connection graphs between knowledge areas
• Personal Preference Tracking - Records and ranks preferences in categories like movies, books, and music
• System Prompt Memory - Stores effective system prompts with effectiveness ratings
• Interactive Dashboard - Visualizes and manages memory profiles
• Multi-format Export/Import - Supports JSON, MentorSync, and LLM-friendly formats
• Docker Integration - Runs in isolated containers with persistent storage

• Docker and Docker Compose
• 512MB RAM minimum (recommend 1GB+)
• 1GB disk space
• For direct installation: Python 3.11+

Samantha uses a multi-layered memory architecture:

1. Identity Layer - Core user identity
2. Learning Style Layer - VARK profile with weighted representations
3. Knowledge Layer - Topics with mastery levels and relationships
4. Preference Layer - Category-based preference tracking with scoring
5. Interaction Layer - Conversation style preferences
6. System Layer - Effective system prompts with effectiveness scores

• Base Image: ~500MB
• Runtime Memory: 300-500MB (depends on number of active users)
• Storage: Minimal (~1KB per user profile)
• Total: ~1GB recommended allocation

# Clone the repository
git clone https://github.com/yourusername/samantha-mcp.git
cd samantha-mcp

# Start the services
docker-compose up -d

# Access the dashboard
open http://localhost:8501

# Clone the repository
git clone https://github.com/yourusername/samantha-mcp.git
cd samantha-mcp

# Create a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Download spaCy model
python -m spacy download en_core_web_md

# Run the server
python samantha.py

# In a separate terminal, run the dashboard
streamlit run dashboard.py

┌─────────────────────────────────────────────────────────────┐
│                      Claude Desktop                         │
└───────────────────────────┬─────────────────────────────────┘
                            │
                 ┌──────────▼─────────────┐
                 │    MCP Protocol        │
                 └──────────┬─────────────┘
                            │
┌─────────────────────────────────────────────────────────────┐
│                      Samantha Server                        │
│                                                             │
│   ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    │
│   │   Memory    │    │   Memory    │    │    MCP      │    │
│   │  Extractor  │◄───┤    Store    │◄───┤  Interface  │    │
│   └──────┬──────┘    └──────┬──────┘    └──────┬──────┘    │
│          │                  │                  │           │
│   ┌──────▼──────────────────▼──────────────────▼──────┐    │
│   │                  Data Models                       │    │
│   │   (Learning Style, Topics, Preferences, etc.)      │    │
│   └───────────────────────┬───────────────────────────┘    │
│                           │                                 │
│                     ┌─────▼────┐                            │
│                     │   JSON   │                            │
│                     │ Storage  │                            │
│                     └──────────┘                            │
└─────────────────────────────────────────────────────────────┘
                            │
                  ┌─────────▼────────┐
                  │ Streamlit        │
                  │   Dashboard      │
                  └──────────────────┘

samantha-mcp/
├── samantha.py         # Core MCP server implementation
├── dashboard.py        # Streamlit dashboard
├── Dockerfile          # Container definition
├── docker-compose.yml  # Container orchestration
├── requirements.txt    # Python dependencies
├── setup.sh            # Setup script
├── data/               # Persistent storage directory
└── docs/               # Documentation

The memory extraction process involves:

1. Conversation Analysis: Processing text for learning style indicators, topic mentions, and preferences
2. Pattern Matching: Identifying learning patterns using NLP techniques
3. Weighted Updates: Incorporating new insights with a 30/70 weighted model (new/existing)
4. Profile Construction: Building a comprehensive user profile
5. Persistent Storage: Saving memory in JSON format for retrieval

The interactive Streamlit dashboard provides:

• User Profile Overview: Summary of all memory components
• Learning Style Management: Visual editors for VARK profiles
• Topic Network Visualization: Interactive graph of knowledge areas
• System Prompt Library: Create and rate effective prompts
• Preference Management: Track and organize user likes
• Import/Export Tools: Data backup and transfer functionality

For production deployment, consider:

# Deploy to Docker Swarm
docker stack deploy -c docker-compose.yml samantha

# Or with Kubernetes
kubectl apply -f k8s-deployment.yml

# Example docker-compose.override.yml
services:
  samantha:
    deploy:
      replicas: 3
  
  nginx:
    image: nginx:latest
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
    depends_on:
      - samantha

The data directory contains all user profiles and should be backed up regularly:

# Backup data
tar -czf samantha-data-backup.tar.gz data/

# Restore data
tar -xzf samantha-data-backup.tar.gz

# View container logs
docker-compose logs -f

# Check specific container
docker logs samantha

For production deployments, add monitoring:

# With Prometheus/Grafana
docker-compose -f docker-compose.yml -f docker-compose.monitoring.yml up -d

Contributions welcome! Please see CONTRIBUTING.md for details.

Samantha is released under the MIT License. See LICENSE for details.

• The Model Context Protocol team for the MCP specification
• Streamlit for the dashboard framework
• spaCy for NLP capabilities