mjnong/custom-mem0

# Development setup
git clone <your-repo>
cd custom-mem0
make dev-setup
make up-dev

# VS Code MCP Integration
# Add to settings.json:
"mcp": {
    "servers": {
        "memory-mcp": {
            "url": "http://localhost:8888/memory/mcp/sse"
        }
    }
}

Access Points:

• API: http://localhost:8888
• Health: http://localhost:8888/health
• Neo4j: http://localhost:8474

The system includes comprehensive backup functionality for production environments:

Backup Types

1. Application-Aware Backups

   • PostgreSQL: Uses pg_dump for consistent database snapshots
   • Neo4j: Database dumps using Neo4j admin tools
   • History: File-level backup of SQLite history database

2. Automated Backup Process

   make backup-automated    # Full backup with validation and cleanup
   make backup              # Manual backup
   make backup-validate     # Verify backup integrity
   make backup-monitor      # Check backup health
   

The system includes automated backup monitoring:

• Health Checks: Validates backup age, size, and integrity
• Alerting: Email and webhook notifications for backup issues
• Disk Space: Monitors available storage for backups
• Automated Cleanup: Removes backups older than 30 days

Production Backup Schedule

Set up automated backups with cron:

# Daily backup at 2 AM
0 2 * * * cd /path/to/custom-mem0 && make backup-automated >> logs/backup.log 2>&1

# Backup monitoring every 6 hours
0 */6 * * * cd /path/to/custom-mem0 && make backup-monitor >> logs/monitor.log 2>&1

Upload backups to cloud storage:

make backup-to-cloud    # Requires AWS CLI configuration

Configure AWS CLI:

aws configure
# Enter your AWS credentials and region

Backup Storage Structure

backups/
├── postgres/
│   ├── postgres_20241225_120000.sql.gz
│   └── postgres_20241225_140000.sql.gz
├── neo4j/
│   ├── neo4j_20241225_120000.tar.gz
│   └── neo4j_20241225_140000.tar.gz
└── history/
    ├── history_20241225_120000.tar.gz
    └── history_20241225_140000.tar.gz

1. Full System Recovery

   # Stop services
   make down
   
   # List available backups
   make backup-list
   
   # Restore databases
   make restore-postgres BACKUP_FILE=postgres_YYYYMMDD_HHMMSS.sql.gz
   make restore-neo4j BACKUP_FILE=neo4j_YYYYMMDD_HHMMSS.tar.gz
   
   # Start services
   make up
   make health
   

2. Point-in-Time Recovery

   • Backups are timestamped for specific recovery points
   • Choose the backup closest to your desired recovery time
   • PostgreSQL dumps include complete schema and data

Backup Best Practices

• Regular Testing: Regularly test backup restoration procedures
• Multiple Locations: Store backups in multiple locations (local + cloud)
• Monitoring: Use backup monitoring to catch issues early
• Documentation: Keep recovery procedures documented and accessible
• Security: Encrypt backups containing sensitive data

Key configuration options in .env:

# Backend Selection
BACKEND="pgvector"  # or "qdrant"

# OpenAI Configuration
OPENAI_API_KEY="your-api-key"
OPENAI_MODEL="gpt-4o-mini"
OPENAI_EMBEDDING_MODEL="text-embedding-3-small"

# Neo4j Configuration
NEO4J_IP="neo4j:7687"
NEO4J_USERNAME="neo4j"
NEO4J_PASSWORD="mem0graph"

# PostgreSQL (Vector Store)
POSTGRES_HOST="postgres"
POSTGRES_PORT=5432
POSTGRES_USER="postgres"
POSTGRES_PASSWORD="password"

# FastAPI Configuration
FASTAPI_HOST="localhost"
FASTAPI_PORT=8000
MEMORY_LOG_LEVEL="info"

PostgreSQL/pgvector Backend (Default)

• Best for: Traditional SQL with vector search, ACID transactions
• Features: Familiar SQL interface, rich ecosystem, structured data
• Vector Store: PostgreSQL with pgvector extension
• Graph Store: Neo4j (shared)

Qdrant Backend

• Best for: Purpose-built vector search, high performance
• Features: Advanced filtering, clustering, optimized for vectors
• Vector Store: Qdrant native vectors
• Graph Store: Neo4j (shared)

Choose your vector store backend with simple commands:

# Start with PostgreSQL/pgvector (default)
make up-pgvector          # Production
make up-dev-pgvector      # Development

# Start with Qdrant
make up-qdrant            # Production  
make up-dev-qdrant        # Development

Quick Setup:

# Use pre-configured environments
cp .env.pgvector .env     # For PostgreSQL backend
cp .env.qdrant .env       # For Qdrant backend
make up                   # Start with selected backend

Switching Backends:

make down                 # Stop current services
cp .env.qdrant .env       # Switch configuration
make up                   # Start with new backend

Both backends share the same Neo4j graph store and provide identical MCP tools and APIs.

• add_memory: Store new memories
• search_memories: Find memories by similarity
• update_memory: Modify existing memories
• delete_memory: Remove specific memories
• delete_all_memories: Clear all memories for a user/agent

• memories://{user_id}/{agent_id}/{limit}: Retrieve all memories

To use this MCP server with VS Code Copilot, add the following configuration to your VS Code settings.json:

"mcp": {
    "servers": {
        "memory-mcp": {
            "url": "http://localhost:8888/memory/mcp/sse"
        }
    }
}

Once configured, you can:

• Reference tools: Use # to access memory tools directly in VS Code
• Custom instructions: Write natural language instructions to efficiently interact with the memory system
• Seamless integration: The memory tools will be available alongside other Copilot features

Make sure your MCP server is running (make up-dev or make up) before using it in VS Code.

• Hot Reload: Code changes automatically restart the server
• Volume Mounting: Live code editing without rebuilds
• Debug Logging: Detailed logs for development
• MCP Inspector: Visual debugging of MCP protocol

• Use strong passwords for databases
• Set proper OpenAI API keys
• Configure appropriate resource limits
• Set up monitoring and alerting
• Regular backups with make backup

• Health endpoint: /health
• Container health checks included
• Graceful shutdown handling
• Structured logging for observability

Service won't start

make logs                # Check logs
make health              # Check health status

Database connection issues

make status              # Check container status
make db-shell            # Test database access

Memory operations failing

make mcp-inspect         # Debug MCP protocol
curl http://localhost:8888/health  # Check API health

• Check logs with make logs
• Use MCP inspector with make mcp-inspect
• Review health status with make health
• Access container shell with make shell