TL;DR:

MCP Memory Service: Universal AI memory service with semantic search for Claude Desktop, VS Code, and 13+ AI applications
Python venv Installation: Isolated environment setup for clean, conflict-free installation
Key Features: Semantic search, multi-client support, autonomous consolidation, SQLite-vec backend
Prerequisites: Python 3.8+, git, uv package manager

Installing MCP Memory Service with Python venv: Complete Local Setup Guide

The MCP Memory Service is a powerful universal memory service that provides semantic search and persistent storage for AI assistants. It works seamlessly with Claude Desktop, VS Code, Cursor, and over 13 other AI applications, enabling them to maintain context across conversations and access previously stored knowledge.

This comprehensive guide will walk you through installing the MCP Memory Service using Python’s virtual environment (venv) on your local machine. This approach ensures a clean, isolated installation that won’t conflict with your system Python or other projects.

What is MCP Memory Service?

Before diving into the installation, let’s understand what makes this service valuable:

Core Features

Semantic Memory Search: Uses vector embeddings for intelligent, natural language search
Multi-Client Support: Works with Claude Desktop, Claude Code, VS Code, Cursor, and more
Autonomous Consolidation: Automatically organizes and consolidates memories
Flexible Storage: Supports SQLite-vec, ChromaDB, and Cloudflare backends
Time-Based Queries: Search memories using natural language (“yesterday”, “last week”)
Tag-Based Organization: Smart categorization and tagging system

Why Use Python venv?

Isolation: Keeps dependencies separate from system Python
Reproducibility: Ensures consistent environment across different machines
Clean Uninstall: Easy to remove if needed
Version Control: Prevents conflicts with other Python projects

Prerequisites

Before starting the installation, ensure you have the following:

System Requirements

Python 3.8 or higher (Python 3.11+ recommended)
Git for cloning the repository
uv package manager (modern Python package manager)
At least 2GB free disk space (for models and data)
Supported OS: Linux, macOS, or Windows (WSL2)

Verify Prerequisites

1
# Check Python version
2
python --version
3
# Should show Python 3.8+ (preferably 3.11+)
4

5
# Check if git is installed
6
git --version
7

8
# Install uv if not present
9
curl -LsSf https://astral.sh/uv/install.sh | sh
10
# Or using pip
11
pip install uv
12

13
# Verify uv installation
14
uv --version

Step-by-Step Installation Guide

Step 1: Clone the Repository

1
# Navigate to your preferred directory
2
cd ~/projects  # or any directory you prefer
3

4
# Clone the MCP Memory Service repository
5
git clone https://github.com/doobidoo/mcp-memory-service.git
6

7
# Navigate into the project directory
8
cd mcp-memory-service

Step 2: Create Python Virtual Environment

1
# Create a virtual environment in the project directory
2
python -m venv venv
3

4
# Activate the virtual environment
5
# On Linux/macOS:
6
source venv/bin/activate
7

8
# On Windows:
9
# venv\Scripts\activate
10

11
# Verify activation (you should see (venv) in your prompt)
12
which python
13
# Should point to: /path/to/mcp-memory-service/venv/bin/python

Step 3: Install Dependencies with uv

1
# Install dependencies using uv (recommended)
2
uv pip install -e .
3

4
# Alternative: Install with pip
5
# pip install -e .

Step 4: Initialize the Service

1
# Run the installation script
2
python install.py
3

4
# Or manually initialize
5
uv run memory init

Step 5: Configure Storage Backend

The service supports multiple storage backends. For local installation, SQLite-vec is recommended:

1
# Set environment variables for SQLite-vec backend
2
export MCP_MEMORY_STORAGE_BACKEND=sqlite_vec
3

4
# Optional: Enable HTTP API for web dashboard
5
export MCP_HTTP_ENABLED=true
6
export MCP_HTTP_PORT=8000
7

8
# Optional: Set API key for security
9
export MCP_API_KEY="your-secure-api-key-here"

Step 6: Test the Installation

1
# Test basic functionality
2
uv run memory health
3

4
# Store a test memory
5
uv run memory store "Test memory: Installation completed successfully"
6

7
# Search for the memory
8
uv run memory recall "installation test"
9

10
# Check service status
11
uv run memory status

Integration with AI Applications

Claude Desktop Integration

Locate Claude Desktop Configuration:

1
# On macOS
2
~/Library/Application Support/Claude/claude_desktop_config.json
3

4
# On Windows
5
%APPDATA%\Claude\claude_desktop_config.json
6

7
# On Linux
8
~/.config/Claude/claude_desktop_config.json

Add MCP Configuration:

1
{
2
  "mcpServers": {
3
    "memory": {
4
      "command": "uv",
5
      "args": ["--directory", "/path/to/mcp-memory-service", "run", "memory", "server"],
6
      "env": {
7
        "MCP_MEMORY_STORAGE_BACKEND": "sqlite_vec"
8
      }
9
    }
10
  }
11
}

Restart Claude Desktop to load the new configuration.

VS Code Integration

Install the MCP extension for VS Code
Configure the memory service in VS Code settings
Restart VS Code to enable the integration

Cursor Integration

Open Cursor settings
Add MCP server configuration
Point to your local MCP Memory Service
Restart Cursor to activate

Advanced Configuration

Environment Variables

1
# Storage Configuration
2
export MCP_MEMORY_STORAGE_BACKEND=sqlite_vec  # or chromadb, cloudflare
3
export MCP_MEMORY_DB_PATH=./data/memory.db
4

5
# HTTP API Configuration
6
export MCP_HTTP_ENABLED=true
7
export MCP_HTTP_HOST=localhost
8
export MCP_HTTP_PORT=8000
9
export MCP_API_KEY=your-secure-key
10

11
# Performance Tuning
12
export MCP_MEMORY_MAX_WORKERS=4
13
export MCP_MEMORY_BATCH_SIZE=100
14

15
# Logging
16
export MCP_LOG_LEVEL=INFO
17
export MCP_LOG_FILE=./logs/memory.log

Custom Configuration File

Create a .env file in the project root:

1
# .env file
2
MCP_MEMORY_STORAGE_BACKEND=sqlite_vec
3
MCP_HTTP_ENABLED=true
4
MCP_HTTP_PORT=8000
5
MCP_API_KEY=your-secure-api-key
6
MCP_MEMORY_MAX_WORKERS=4

Troubleshooting Common Issues

First-Time Setup Warnings

On first run, you might see warnings that are completely normal:

1
WARNING: Failed to load from cache: No snapshots directory
2
WARNING: Using TRANSFORMERS_CACHE is deprecated

These warnings disappear after the first successful run. The service downloads a ~25MB embedding model on first use.

Python Version Issues

1
# If you have multiple Python versions
2
python3.11 -m venv venv
3
source venv/bin/activate
4
python --version  # Should show 3.11.x

Permission Issues

1
# On Linux/macOS, ensure proper permissions
2
chmod +x venv/bin/python
3
chmod +x venv/bin/uv

Port Conflicts

1
# Check if port 8000 is available
2
lsof -i :8000
3

4
# Change port if needed
5
export MCP_HTTP_PORT=8001

Memory Issues

1
# For systems with limited RAM
2
export MCP_MEMORY_MAX_WORKERS=2
3
export MCP_MEMORY_BATCH_SIZE=50

Usage Examples

Basic Memory Operations

1
# Store a memory with tags
2
uv run memory store "Fixed authentication bug by adding proper validation" --tags python,security,bugfix
3

4
# Search by natural language
5
uv run memory recall "authentication validation issues"
6

7
# Search by tags
8
uv run memory search --tags python security
9

10
# Search by time
11
uv run memory recall "yesterday afternoon"
12

13
# List all memories
14
uv run memory list --limit 10

Advanced Queries

1
# Complex search with multiple criteria
2
uv run memory recall "database optimization" --tags performance --since "2024-01-01"
3

4
# Export memories
5
uv run memory export --format json --output memories_backup.json
6

7
# Import memories
8
uv run memory import --file memories_backup.json

Performance Optimization

For Local Development

1
# Use SQLite-vec for fastest local performance
2
export MCP_MEMORY_STORAGE_BACKEND=sqlite_vec
3

4
# Optimize worker count for your CPU
5
export MCP_MEMORY_MAX_WORKERS=$(nproc)

For Production Use

1
# Enable HTTP API for web dashboard
2
export MCP_HTTP_ENABLED=true
3

4
# Set up proper logging
5
export MCP_LOG_LEVEL=WARNING
6
export MCP_LOG_FILE=/var/log/mcp-memory.log
7

8
# Configure backup
9
export MCP_BACKUP_ENABLED=true
10
export MCP_BACKUP_INTERVAL=3600  # 1 hour

Security Considerations

API Key Protection

1
# Generate a secure API key
2
openssl rand -hex 32
3

4
# Set the key
5
export MCP_API_KEY="your-generated-secure-key"

Network Security

1
# Bind to localhost only
2
export MCP_HTTP_HOST=127.0.0.1
3

4
# Use HTTPS in production
5
export MCP_SSL_CERT=/path/to/cert.pem
6
export MCP_SSL_KEY=/path/to/key.pem

Data Encryption

1
# Enable database encryption
2
export MCP_ENCRYPTION_ENABLED=true
3
export MCP_ENCRYPTION_KEY="your-encryption-key"

Maintenance and Updates

Regular Maintenance

1
# Check service health
2
uv run memory health
3

4
# Clean up old memories (optional)
5
uv run memory cleanup --older-than 90days
6

7
# Optimize database
8
uv run memory optimize

Updating the Service

1
# Pull latest changes
2
git pull origin main
3

4
# Update dependencies
5
uv pip install -e . --upgrade
6

7
# Restart the service
8
# If running as service, restart it
9
# If running manually, stop and restart

Backup and Restore

1
# Create backup
2
uv run memory backup --output backup_$(date +%Y%m%d).tar.gz
3

4
# Restore from backup
5
uv run memory restore --input backup_20240908.tar.gz

Integration Examples

With Claude Code

1
# Claude Code integration
2
export MCP_CLAUDE_CODE_ENABLED=true
3
export MCP_CLAUDE_CODE_HOOKS_DIR=./claude-hooks

With Development Workflows

1
# Git integration
2
uv run memory store "Merged feature branch with conflict resolution" --tags git,merge,conflict
3

4
# Code review notes
5
uv run memory store "Code review: Add input validation to API endpoints" --tags review,api,security

Monitoring and Analytics

Service Metrics

1
# View service statistics
2
uv run memory stats
3

4
# Monitor memory usage
5
uv run memory usage
6

7
# Check query performance
8
uv run memory performance

Logging Configuration

1
# Detailed logging
2
export MCP_LOG_LEVEL=DEBUG
3
export MCP_LOG_FORMAT=json
4

5
# Log rotation
6
export MCP_LOG_MAX_SIZE=100MB
7
export MCP_LOG_BACKUP_COUNT=5

Conclusion

Installing MCP Memory Service with Python venv provides a clean, isolated environment for running this powerful AI memory service locally. The virtual environment approach ensures that dependencies are managed separately from your system Python, preventing conflicts and making maintenance easier.

Key Benefits of This Installation Method

Isolation: Dependencies don’t conflict with system Python
Reproducibility: Same environment across different machines
Easy Updates: Simple to upgrade or modify
Clean Removal: Easy to uninstall if needed
Development Friendly: Great for testing and development

Next Steps

Explore the Web Dashboard: Access http://localhost:8000 for the web interface
Integrate with Your AI Tools: Connect Claude Desktop, VS Code, or other supported applications
Customize Configuration: Adjust settings for your specific use case
Set Up Backups: Configure regular backups for important memories
Monitor Performance: Use the built-in monitoring tools to optimize usage

The MCP Memory Service transforms how AI assistants work by providing persistent, searchable memory across conversations and sessions. With semantic search capabilities and multi-client support, it significantly enhances productivity for developers, researchers, and anyone working with AI tools.