MCP Memory Service

Features

• Semantic search using sentence transformers

• Natural language time-based recall (e.g., "last week", "yesterday morning")

• Tag-based memory retrieval system

• Persistent storage using ChromaDB

• Automatic database backups

• Memory optimization tools

• Exact match retrieval

• Debug mode for similarity analysis

• Database health monitoring

• Duplicate detection and cleanup

• Customizable embedding model

• Cross-platform compatibility (Apple Silicon, Intel, Windows, Linux)

• Hardware-aware optimizations for different environments

• Graceful fallbacks for limited hardware resources

Quick Start

Docker and Smithery Integration

Docker Usage

1. Open Docker Desktop

2. Go to Settings (Preferences)

3. Navigate to Resources -> File Sharing

4. Add any additional paths you need to share

5. Click "Apply & Restart"

Smithery Integration

1. Ensure your claude_desktop_config.json points to the correct paths:

1. The smithery.yaml configuration handles stdio communication and environment setup automatically.

Testing with Claude Desktop

1. Build the Docker image with docker build -t mcp-memory-service .

2. Create the necessary directories for persistent storage:

3. Update your Claude Desktop configuration file:

4. Restart Claude Desktop

5. When Claude starts up, you should see the memory service initialize with a message:

6. Test the memory feature:

• Check the Claude Desktop console for error messages

• Verify Docker has the necessary permissions to access the mounted directories

• Ensure the Docker container is running with the correct parameters

• Try running the container manually to see any error output

• Installation Guide - Comprehensive installation instructions for all platforms

• Troubleshooting Guide - Solutions for common issues

• Technical Documentation - Detailed technical procedures and specifications

• Scripts Documentation - Overview of available scripts and their usage

VPS Deployment Requirements

Minimum System Requirements

Key Considerations for VPS Deployment

Memory Usage Breakdown

• Sentence Transformer Model: ~400-600 MB (depends on model)

• ChromaDB: ~200-500 MB (depends on database size)

• Python Runtime + Dependencies: ~200-300 MB

• Working Memory for Embeddings: ~100-500 MB (depends on batch size)

Storage Requirements

• ChromaDB: Starts at ~100 MB, grows ~1 MB per 100 memories

• Backups: Plan for 2-3x the DB size for rotation

• Code + Dependencies: ~300-500 MB

• OS + Other: Variable based on your setup

Recommended Docker Deployment for VPS

• Limits the container to 4GB RAM and 2 CPUs

• Uses a balanced model for good performance/resource usage

• Mounts persistent volumes for data storage

• Automatically restarts the service if it crashes or on system reboot

Optimizations for Low-Resource VPS Environments

1. Use a smaller embedding model:

2. Reduce batch size:

3. Enable CPU optimization:

Configuration

Standard Configuration (Recommended)

Windows-Specific Configuration (Recommended)

1. Check if PyTorch is installed and properly configured

2. Install PyTorch with the correct index URL if needed

3. Run the memory server with the appropriate configuration

Hardware Compatibility

** Note for macOS 15 (Sequoia) users**: If you're using macOS 15 with Apple Silicon and encounter PyTorch package installation errors when using UV, you might need to:This issue happens because PyTorch wheels for macOS 15 on arm64 are still being updated. See issue #29 for more details.

Memory Operations

Core Memory Operations

1. store_memory - Store new information with optional tags

2. retrieve_memory - Perform semantic search for relevant memories

3. recall_memory - Retrieve memories using natural language time expressions

4. search_by_tag - Find memories using specific tags

5. exact_match_retrieve - Find memories with exact content match

6. debug_retrieve - Retrieve memories with similarity scores

Database Management

1. create_backup - Create database backup

2. get_stats - Get memory statistics

3. optimize_db - Optimize database performance

4. check_database_health - Get database health metrics

5. check_embedding_model - Verify model status

Memory Management

1. delete_memory - Delete specific memory by hash

2. delete_by_tag - Delete all memories with specific tag

3. cleanup_duplicates - Remove duplicate entries

Configuration Options

Getting Help

1. Check our Troubleshooting Guide

2. Review the Installation Guide

3. For Windows-specific issues, see our Windows Setup Guide

4. Contact the developer via Telegram: t.me/doobeedoo

Project Structure

Development Guidelines

• Python 3.10+ with type hints

• Use dataclasses for models

• Triple-quoted docstrings for modules and functions

• Async/await pattern for all I/O operations

• Follow PEP 8 style guidelines

• Include tests for new features

License

Acknowledgments

• ChromaDB team for the vector database

• Sentence Transformers project for embedding models

• MCP project for the protocol specification

Contact

Cloudflare Worker Implementation

• Uses Cloudflare D1 for storage (serverless SQLite)

• Uses Workers AI for embeddings generation

• Communicates via Server-Sent Events (SSE) for MCP protocol

• Requires no local installation or dependencies

• Scales automatically with usage

Benefits of the Cloudflare Implementation

• Zero local installation: No Python, dependencies, or local storage needed

• Cross-platform compatibility: Works on any device that can connect to the internet

• Automatic scaling: Handles multiple users without configuration

• Global distribution: Low latency access from anywhere

• No maintenance: Updates and maintenance handled automatically

Available Tools in the Cloudflare Implementation

Configuring Claude to Use the Cloudflare Memory Service

Deploying Your Own Cloudflare Memory Service

1. Clone the repository and navigate to the Cloudflare Worker directory:

2. Install Wrangler (Cloudflare's CLI tool):

3. Login to your Cloudflare account:

4. Create a D1 database:

5. Update the wrangler.toml file with your database ID from the previous step.

6. Initialize the database schema:Where schema.sql contains:

7. Deploy the worker:

8. Update your Claude configuration to use your new worker URL.

Testing Your Cloudflare Memory Service

1. List available tools:

2. Store a memory:

3. Retrieve memories:

Limitations

• Free tier limits on Cloudflare Workers and D1 may apply

• Workers AI embedding models may differ slightly from the local sentence-transformers models

• No direct access to the underlying database for manual operations

• Cloudflare Workers have a maximum execution time of 30 seconds on free plans

MCP Memory Service

Features

• Semantic search using sentence transformers

• Natural language time-based recall (e.g., "last week", "yesterday morning")

• Tag-based memory retrieval system

• Persistent storage using ChromaDB

• Automatic database backups

• Memory optimization tools

• Exact match retrieval

• Debug mode for similarity analysis

• Database health monitoring

• Duplicate detection and cleanup

• Customizable embedding model

• Cross-platform compatibility (Apple Silicon, Intel, Windows, Linux)

• Hardware-aware optimizations for different environments

• Graceful fallbacks for limited hardware resources

Quick Start

Docker and Smithery Integration

Docker Usage

1. Open Docker Desktop

2. Go to Settings (Preferences)

3. Navigate to Resources -> File Sharing

4. Add any additional paths you need to share

5. Click "Apply & Restart"

Smithery Integration

1. Ensure your claude_desktop_config.json points to the correct paths:

1. The smithery.yaml configuration handles stdio communication and environment setup automatically.

Testing with Claude Desktop

1. Build the Docker image with docker build -t mcp-memory-service .

2. Create the necessary directories for persistent storage:

3. Update your Claude Desktop configuration file:

4. Restart Claude Desktop

5. When Claude starts up, you should see the memory service initialize with a message:

6. Test the memory feature:

• Check the Claude Desktop console for error messages

• Verify Docker has the necessary permissions to access the mounted directories

• Ensure the Docker container is running with the correct parameters

• Try running the container manually to see any error output

• Installation Guide - Comprehensive installation instructions for all platforms

• Troubleshooting Guide - Solutions for common issues

• Technical Documentation - Detailed technical procedures and specifications

• Scripts Documentation - Overview of available scripts and their usage

VPS Deployment Requirements

Minimum System Requirements

Key Considerations for VPS Deployment

Memory Usage Breakdown

• Sentence Transformer Model: ~400-600 MB (depends on model)

• ChromaDB: ~200-500 MB (depends on database size)

• Python Runtime + Dependencies: ~200-300 MB

• Working Memory for Embeddings: ~100-500 MB (depends on batch size)

Storage Requirements

• ChromaDB: Starts at ~100 MB, grows ~1 MB per 100 memories

• Backups: Plan for 2-3x the DB size for rotation

• Code + Dependencies: ~300-500 MB

• OS + Other: Variable based on your setup

Recommended Docker Deployment for VPS

• Limits the container to 4GB RAM and 2 CPUs

• Uses a balanced model for good performance/resource usage

• Mounts persistent volumes for data storage

• Automatically restarts the service if it crashes or on system reboot

Optimizations for Low-Resource VPS Environments

1. Use a smaller embedding model:

2. Reduce batch size:

3. Enable CPU optimization:

Configuration

Standard Configuration (Recommended)

Windows-Specific Configuration (Recommended)

1. Check if PyTorch is installed and properly configured

2. Install PyTorch with the correct index URL if needed

3. Run the memory server with the appropriate configuration

Hardware Compatibility

** Note for macOS 15 (Sequoia) users**: If you're using macOS 15 with Apple Silicon and encounter PyTorch package installation errors when using UV, you might need to:This issue happens because PyTorch wheels for macOS 15 on arm64 are still being updated. See issue #29 for more details.

Memory Operations

Core Memory Operations

1. store_memory - Store new information with optional tags

2. retrieve_memory - Perform semantic search for relevant memories

3. recall_memory - Retrieve memories using natural language time expressions

4. search_by_tag - Find memories using specific tags

5. exact_match_retrieve - Find memories with exact content match

6. debug_retrieve - Retrieve memories with similarity scores

Database Management

1. create_backup - Create database backup

2. get_stats - Get memory statistics

3. optimize_db - Optimize database performance

4. check_database_health - Get database health metrics

5. check_embedding_model - Verify model status

Memory Management

1. delete_memory - Delete specific memory by hash

2. delete_by_tag - Delete all memories with specific tag

3. cleanup_duplicates - Remove duplicate entries

Configuration Options

Getting Help

1. Check our Troubleshooting Guide

2. Review the Installation Guide

3. For Windows-specific issues, see our Windows Setup Guide

4. Contact the developer via Telegram: t.me/doobeedoo

Project Structure

Development Guidelines

• Python 3.10+ with type hints

• Use dataclasses for models

• Triple-quoted docstrings for modules and functions

• Async/await pattern for all I/O operations

• Follow PEP 8 style guidelines

• Include tests for new features

License

Acknowledgments

• ChromaDB team for the vector database

• Sentence Transformers project for embedding models

• MCP project for the protocol specification

Contact

Cloudflare Worker Implementation

• Uses Cloudflare D1 for storage (serverless SQLite)

• Uses Workers AI for embeddings generation

• Communicates via Server-Sent Events (SSE) for MCP protocol

• Requires no local installation or dependencies

• Scales automatically with usage

Benefits of the Cloudflare Implementation

• Zero local installation: No Python, dependencies, or local storage needed

• Cross-platform compatibility: Works on any device that can connect to the internet

• Automatic scaling: Handles multiple users without configuration

• Global distribution: Low latency access from anywhere

• No maintenance: Updates and maintenance handled automatically

Available Tools in the Cloudflare Implementation

Configuring Claude to Use the Cloudflare Memory Service

Deploying Your Own Cloudflare Memory Service

1. Clone the repository and navigate to the Cloudflare Worker directory:

2. Install Wrangler (Cloudflare's CLI tool):

3. Login to your Cloudflare account:

4. Create a D1 database:

5. Update the wrangler.toml file with your database ID from the previous step.

6. Initialize the database schema:Where schema.sql contains:

7. Deploy the worker:

8. Update your Claude configuration to use your new worker URL.

Testing Your Cloudflare Memory Service

1. List available tools:

2. Store a memory:

3. Retrieve memories:

Limitations

• Free tier limits on Cloudflare Workers and D1 may apply

• Workers AI embedding models may differ slightly from the local sentence-transformers models

• No direct access to the underlying database for manual operations

• Cloudflare Workers have a maximum execution time of 30 seconds on free plans