claude-memory-mcp

adamkwhite/claude-memory-mcp

3.2

If you are the rightful owner of claude-memory-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Claude Conversation Memory System is a Model Context Protocol (MCP) server designed to provide searchable local storage for Claude conversation history, enabling context retrieval during current sessions.

Tools
3
Resources
0
Prompts
0

Code Quality

Overall Scorecard

Quality Gate Status Bugs Coverage Reliability Rating Security Rating Maintainability Rating

Code Quality

Lines of Code Duplicated Lines (%) Code Smells Technical Debt

Security

Vulnerabilities

Claude Conversation Memory System

A Model Context Protocol (MCP) server that provides searchable local storage for Claude conversation history, enabling context retrieval during current sessions.

Features

  • 🔍 Full-text search across conversation history
  • 🏷️ Automatic topic extraction and categorization
  • 📊 Weekly summaries with insights and patterns
  • 🗃️ Organized file storage by date and topic
  • ⚡ Fast retrieval with relevance scoring
  • 🔌 MCP integration for seamless Claude Desktop access

Quick Start

Prerequisites

  • Python 3.11+ (tested with 3.11.12)
  • Ubuntu/WSL environment recommended
  • Claude Desktop (for MCP integration)

Installation

Option 1: Install with Claude Code (Recommended)

Quick Install - Copy and paste this into Claude Code:

claude mcp add --transport stdio claude-memory -- sh -c "cd $HOME/Code/claude-memory-mcp && python3 src/server_fastmcp.py"

Important: Replace $HOME/Code/claude-memory-mcp with the actual path where you cloned this repository.

Examples for different locations:

# If cloned to ~/Code/claude-memory-mcp (default)
claude mcp add --transport stdio claude-memory -- sh -c "cd $HOME/Code/claude-memory-mcp && python3 src/server_fastmcp.py"

# If cloned to ~/projects/claude-memory-mcp
claude mcp add --transport stdio claude-memory -- sh -c "cd $HOME/projects/claude-memory-mcp && python3 src/server_fastmcp.py"

# If cloned to ~/dev/claude-memory-mcp
claude mcp add --transport stdio claude-memory -- sh -c "cd $HOME/dev/claude-memory-mcp && python3 src/server_fastmcp.py"

What this does:

  • --transport stdio: Uses standard input/output for local processes
  • claude-memory: Server identifier name
  • --: Separates Claude CLI flags from the server command
  • sh -c "cd ... && python3 ...": Changes to project directory before running server

This adds the MCP server to your Claude Desktop configuration automatically.

Documentation: https://code.claude.com/docs/en/mcp

Option 2: Manual Installation

  1. Clone the repository:

    git clone https://github.com/yourusername/claude-memory-mcp.git
cd claude-memory-mcp

  2. Set up virtual environment:

    python3 -m venv .venv
source .venv/bin/activate

  3. Install dependencies:

    pip install -e .

    This installs the package in editable mode along with all required dependencies:

    • mcp[cli]>=1.9.2 - Model Context Protocol
    • jsonschema>=4.0.0 - JSON schema validation
    • aiofiles>=24.1.0 - Async file operations

  4. Test the system:

    python3 tests/validate_system.py

Basic Usage

Standalone Testing
# Test core functionality
python3 tests/standalone_test.py
MCP Server Mode
# Run as MCP server (from project root)
python3 src/server_fastmcp.py

# Or from src directory
cd src && python3 server_fastmcp.py
Bulk Import
# Import conversations from JSON export
python3 scripts/bulk_import_enhanced.py your_conversations.json

MCP Tools

The system provides three main tools:

search_conversations(query, limit=5)

Search through stored conversations by topic or content.

Example:

search_conversations("terraform azure deployment")
search_conversations("python debugging", limit=10)

add_conversation(content, title, date)

Add a new conversation to the memory system.

Example:

add_conversation(
    content="Discussion about MCP server setup...",
    title="MCP Server Configuration", 
    date="2025-06-01T14:30:00Z"
)

generate_weekly_summary(week_offset=0)

Generate insights and patterns from conversations.

Example:

generate_weekly_summary()  # Current week
generate_weekly_summary(1)  # Last week

Architecture

~/claude-memory/
├── conversations/
│   ├── 2025/
│   │   └── 06-june/
│   │       └── 2025-06-01_topic-name.md
│   ├── index.json          # Search index
│   └── topics.json         # Topic frequency
└── summaries/
    └── weekly/
        └── week-2025-06-01.md

Configuration

Claude Desktop Integration

Add to your Claude Desktop MCP config:

{
  "mcpServers": {
    "claude-memory": {
      "command": "python",
      "args": ["/path/to/claude-memory-mcp/server_fastmcp.py"]
    }
  }
}

Storage Location

Default storage: ~/claude-memory/

Override with environment variable:

export CLAUDE_MEMORY_PATH="/custom/path"

Logging Configuration

Log Format

Switch between human-readable text logs (default) and structured JSON logs for production:

# JSON format (for production log aggregation)
export CLAUDE_MCP_LOG_FORMAT=json

# Text format (default, for development)
export CLAUDE_MCP_LOG_FORMAT=text

JSON Log Example:

{
  "timestamp": "2025-01-15T10:30:45",
  "level": "INFO",
  "logger": "claude_memory_mcp",
  "function": "add_conversation",
  "line": 145,
  "message": "Added conversation successfully",
  "context": {
    "type": "performance",
    "duration_seconds": 0.045,
    "conversation_id": "conv_abc123"
  }
}

JSON logging is ideal for:

  • Production deployments with log aggregation (Datadog, ELK, CloudWatch)
  • Automated monitoring and alerting
  • Structured log analysis and querying
  • Performance tracking and debugging

See docs/json-logging.md for detailed JSON logging documentation.

File Structure

claude-memory-mcp/
├── server_fastmcp.py           # Main MCP server
├── bulk_import_enhanced.py     # Conversation import tool
├── validate_system.py          # System validation
├── standalone_test.py          # Core functionality test
├── import_workflow.sh          # Automated import process
├── requirements.txt            # Python dependencies
├── IMPORT_GUIDE.md            # Detailed import instructions
└── README.md                  # This file

Performance

Performance validated through automated benchmarks:

  • Search Speed: 0.05s average (159 conversations)
  • Capacity: Tested with 159 conversations (7.8MB)
  • Memory Usage: 40MB peak during operations
  • Accuracy: 80%+ search relevance
  • Write Performance: 1-12MB/s throughput

Last benchmarked: June 2025 |

Note for Developers: The development team uses performance benchmarks that create a ~/claude-memory-test directory for isolated testing. Normal MCP usage does NOT create this directory - it only uses ~/claude-memory/. If you see ~/claude-memory-test, it was created by running development scripts and can be safely deleted.

Search Examples

# Technical topics
search_conversations("terraform azure")
search_conversations("mcp server setup")
search_conversations("python debugging")

# Project discussions  
search_conversations("interview preparation")
search_conversations("product management")
search_conversations("architecture decisions")

# Specific problems
search_conversations("dependency issues")
search_conversations("authentication error")
search_conversations("deployment configuration")

Development

Adding New Features

  1. Topic Extraction: Modify _extract_topics() in ConversationMemoryServer
  2. Search Algorithm: Enhance search_conversations() method
  3. Summary Generation: Improve generate_weekly_summary() logic

Testing

# Run validation suite
python3 tests/validate_system.py

# Test individual components
python3 tests/standalone_test.py

# Run full test suite with coverage
python3 -m pytest tests/ --ignore=tests/standalone_test.py --cov=src --cov-report=term

# Import test data
python3 scripts/bulk_import_enhanced.py test_data.json --dry-run

Test Data Storage (Developers Only): If you run performance benchmarks or test data generators, they create a ~/claude-memory-test directory to isolate test data from your production ~/claude-memory directory. This is only for development/testing - normal MCP usage does not create this directory.

To clean up test data after running benchmarks:

rm -rf ~/claude-memory-test

Or using the Makefile cleanup target:

make clean-test-data

Troubleshooting

Common Issues

MCP Import Errors:

pip install mcp[cli]  # Include CLI extras

Search Returns No Results:

  • Check conversation indexing: ls ~/claude-memory/conversations/index.json
  • Verify file permissions
  • Run validation: python3 tests/validate_system.py

Weekly Summary Timezone Errors:

  • Ensure all datetime objects use consistent timezone handling
  • Recent fix addresses timezone-aware vs naive comparison

System Requirements

  • Python: 3.11+ (tested with 3.11.12)
  • Disk Space: ~10MB per 100 conversations
  • Memory: <100MB RAM usage
  • OS: Ubuntu/WSL recommended, macOS/Windows compatible

Contributing

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature-name
  3. Commit changes: git commit -am 'Add feature'
  4. Push to branch: git push origin feature-name
  5. Submit a Pull Request

License

MIT License - see LICENSE file for details

Acknowledgments

Status: Production ready ✅
Last Updated: June 2025
Version: 1.0.0