Code Quality

Overall Scorecard

Code Quality

Security

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

Clone the repository:

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

Set up virtual environment:

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

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

Topic Extraction: Modify _extract_topics() in ConversationMemoryServer
Search Algorithm: Enhance search_conversations() method
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

Fork the repository
Create a feature branch: git checkout -b feature-name
Commit changes: git commit -am 'Add feature'
Push to branch: git push origin feature-name
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

Code Quality

Overall Scorecard

Code Quality

Security

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

Clone the repository:

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

Set up virtual environment:

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

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

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

Topic Extraction: Modify _extract_topics() in ConversationMemoryServer
Search Algorithm: Enhance search_conversations() method
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

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

Fork the repository
Create a feature branch: git checkout -b feature-name
Commit changes: git commit -am 'Add feature'
Push to branch: git push origin feature-name
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