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 | Detailed Report

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

• Built with Model Context Protocol (MCP)
• Designed for Claude Desktop integration
• Inspired by the need for persistent conversation context

---

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