How do I use Claude Conversation Memory System?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Claude Conversation Memory System search my history for what we discussed about the project architecture" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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

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

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 |

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

Claude Conversation Memory System

Code Quality

Claude Conversation Memory System

Features

Quick Start

Prerequisites

Installation

Option 1: Install with Claude Code (Recommended)

Option 2: Manual Installation

Basic Usage

Standalone Testing

MCP Server Mode

Bulk Import

MCP Tools

`search_conversations(query, limit=5)`

`add_conversation(content, title, date)`

`generate_weekly_summary(week_offset=0)`

Architecture

Configuration

Claude Desktop Integration

Storage Location

Logging Configuration

Log Format

File Structure

Performance

Search Examples

Development

Adding New Features

Testing

Troubleshooting

Common Issues

System Requirements

Contributing

License

Acknowledgments

Resources

New MCP Servers

Latest Blog Posts

MCP directory API