Skip to content

01 Installation Guide

Jump to bottom
Henry edited this page Aug 23, 2025 · 1 revision

Installation & Setup Guide

Version: 6.3.3+
Last Updated: 2025-08-23
Supports: SQLite-vec (recommended), ChromaDB, Cloudflare backends

This guide consolidates all installation methods for MCP Memory Service across all platforms and use cases.

🚀 Quick Start (Recommended)

Universal Installer (All Platforms)

The fastest way to get started - automatically detects your system and configures everything:

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

# Run the universal installer
python install.py

What this does:

  • ✅ Detects your operating system and hardware
  • ✅ Installs optimal dependencies for your system
  • ✅ Configures the best storage backend (SQLite-vec recommended)
  • ✅ Sets up environment variables
  • ✅ Generates secure API key
  • ✅ Optionally installs as system service

📋 Prerequisites

System Requirements

  • Python: 3.10 or newer (3.11+ recommended)
  • Memory: 4GB RAM minimum (8GB+ recommended)
  • Storage: 2GB free space
  • OS: Windows 10+, macOS 10.15+, or Linux (Ubuntu 18.04+)

Hardware Optimization

🖥️ Legacy Hardware (2013-2017 Intel Macs, older systems)

python install.py --legacy-hardware
  • Uses SQLite-vec backend (lightweight)
  • CPU-only inference optimization
  • Reduced memory footprint

🚀 Modern Hardware (M1/M2/M3 Macs, GPU systems)

python install.py
  • Uses optimal backend for your system
  • GPU acceleration when available
  • Full feature set enabled

🎯 Installation by Use Case

1. Claude Desktop Integration (Most Common)

For using MCP Memory Service with Claude Desktop:

# Install with MCP protocol support
python install.py --claude-desktop

# Follow the output instructions to update your Claude Desktop config
# Typically adds this to ~/.claude/config.json:
{
  "mcpServers": {
    "memory": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-memory-service", "run", "memory", "server"],
      "env": {
        "MCP_MEMORY_STORAGE_BACKEND": "sqlite_vec"
      }
    }
  }
}

2. Claude Code Integration (Developers)

For Claude Code with memory awareness:

# Install with Claude Code hooks
python install.py --claude-code

# Install memory awareness hooks
python scripts/install_claude_hooks.py

See our Claude Code Memory Awareness Guide for complete setup.

3. HTTP API / Web Dashboard

For REST API access and web interface:

# Install with HTTP API enabled
python install.py --http-api

# Start the web server
uv run memory server --http

Access at: https://localhost:8000

4. System Service (Auto-start)

For always-on background operation:

# Install as system service
python install.py --service

# Or install manually after regular installation:
python scripts/install_service.py

🖥️ Platform-Specific Instructions

macOS

Intel Macs (2015-2020)

# For older Intel Macs - optimized for compatibility
python install.py --legacy-hardware

# If using Homebrew Python (recommended for older systems)
python install.py --legacy-hardware --homebrew-torch

Apple Silicon Macs (M1/M2/M3)

# Standard installation with MPS acceleration
python install.py

# Verify MPS acceleration is working
python -c "import torch; print('MPS available:', torch.backends.mps.is_available())"

macOS-Specific Notes:

  • Uses MPS acceleration on Apple Silicon
  • Automatically handles Homebrew PyTorch if needed
  • LaunchAgent service integration for auto-start

Windows

Windows 10/11

# Standard Windows installation
python install.py

# For service installation (requires Administrator):
python install.py --service

Windows-Specific Features:

  • Windows Service integration
  • DirectML acceleration support (where available)
  • PowerShell automation scripts included

Linux (Ubuntu/Debian)

Standard Installation

# Install dependencies first
sudo apt update
sudo apt install python3.10 python3.10-venv python3-pip git

# Run installer
python3 install.py

# For system service
sudo python3 install.py --service

Advanced Linux Setup

# For CUDA acceleration (if available)
python install.py --cuda

# For ROCm acceleration (AMD GPUs)
python install.py --rocm

Linux-Specific Features:

  • Systemd service integration
  • CUDA/ROCm GPU acceleration
  • Multi-user service configuration

🐳 Docker Installation

Quick Docker Setup

For MCP Protocol (Claude Desktop, VS Code):

docker-compose up -d

For HTTP API (REST API, Web Dashboard):

docker-compose -f docker-compose.http.yml up -d
curl http://localhost:8000/api/health

Docker Configuration

Create .env file for customization:

# Storage backend
MCP_MEMORY_STORAGE_BACKEND=sqlite_vec

# HTTP API settings  
MCP_HTTP_ENABLED=true
MCP_HTTP_PORT=8000

# Security
MCP_API_KEY=your-secure-api-key-here

📁 Storage Backend Configuration

SQLite-vec (Recommended)

  • Best for: Single-user, local development, high performance
  • Performance: ~5ms query time
  • Setup: Default in v6.3.0+
export MCP_MEMORY_STORAGE_BACKEND=sqlite_vec

ChromaDB (Multi-client)

  • Best for: Team collaboration, multiple clients
  • Performance: ~15ms query time
  • Setup:
export MCP_MEMORY_STORAGE_BACKEND=chroma

Cloudflare (Production)

  • Best for: Production deployments, global scale
  • Performance: Network dependent
  • Setup: Requires API tokens
export MCP_MEMORY_STORAGE_BACKEND=cloudflare
export CLOUDFLARE_API_TOKEN="your-token"
export CLOUDFLARE_ACCOUNT_ID="your-account"

🔧 Service Installation (Auto-Start)

Cross-Platform Service Installer

# Automatic platform detection
python scripts/install_service.py

# Service management commands
python scripts/install_service.py --status   # Check status
python scripts/install_service.py --start    # Start service
python scripts/install_service.py --stop     # Stop service  
python scripts/install_service.py --restart  # Restart service

Platform-Specific Service Management

Windows:

net start MCPMemoryService
net stop MCPMemoryService
sc query MCPMemoryService

macOS:

launchctl load ~/Library/LaunchAgents/com.mcp.memory-service.plist
launchctl unload ~/Library/LaunchAgents/com.mcp.memory-service.plist
launchctl list | grep com.mcp.memory-service

Linux:

systemctl --user start mcp-memory
systemctl --user stop mcp-memory
systemctl --user status mcp-memory

⚙️ Configuration

Environment Variables

Essential configuration options:

# Storage Backend
export MCP_MEMORY_STORAGE_BACKEND=sqlite_vec  # sqlite_vec, chroma, or cloudflare

# HTTP API
export MCP_HTTP_ENABLED=true
export MCP_HTTP_PORT=8000
export MCP_HTTPS_ENABLED=true

# Security  
export MCP_API_KEY="$(openssl rand -base64 32)"

# Service Discovery
export MCP_MDNS_ENABLED=true
export MCP_MDNS_SERVICE_NAME=memory

# Performance
export MAX_RESULTS_PER_QUERY=10
export SIMILARITY_THRESHOLD=0.7

Configuration Files

Configuration is stored in:

  • Config: ~/.mcp_memory_service/service_config.json
  • Logs: ~/.mcp_memory_service/logs/
  • Data: Platform-specific (see storage backend docs)

✅ Verification & Testing

Basic Functionality Test

# Test the installation
python scripts/verify_environment.py

# Test memory operations
uv run memory store "Test memory for installation verification"
uv run memory recall "test installation"
uv run memory health

API Testing (if HTTP enabled)

# Health check
curl -k https://localhost:8000/api/health

# Store a memory
curl -k -X POST https://localhost:8000/api/memories \
  -H "Content-Type: application/json" \
  -d '{"content": "API test memory"}'

# Search memories
curl -k -X POST https://localhost:8000/api/search \
  -H "Content-Type: application/json" \
  -d '{"query": "API test"}'

🚨 Troubleshooting

Common Issues

Installation Fails with Permission Errors:

# Use virtual environment
python -m venv venv
source venv/bin/activate  # Linux/macOS
# or
venv\Scripts\activate.bat  # Windows
python install.py

Port Already in Use:

# Change the port
export MCP_HTTP_PORT=8001

Service Won't Start:

# Check logs
tail -f ~/.mcp_memory_service/logs/mcp-memory-service.log

# Verify configuration
python scripts/verify_environment.py

Dependencies Issues:

# Reinstall dependencies
pip install --force-reinstall -e .

Platform-Specific Troubleshooting

macOS: See macOS Intel Legacy Guide for older Mac issues

Windows: Check Windows Service logs in Event Viewer

Linux: Use journalctl --user -u mcp-memory for service logs

📋 Next Steps

After successful installation:

  1. 🧠 Claude Code Integration - Complete development workflow
  2. ⚡ Quick Reference - Essential commands
  3. 🏷️ Tag Management - Organize your memories
  4. 🔧 Troubleshooting - Fix common issues
  5. 🚀 Performance Optimization - Speed improvements

🆘 Getting Help

This guide consolidates information from multiple previous installation guides for a single, comprehensive reference.

Clone this wiki locally