Claude Code Memory Server

A Neo4j-based Model Context Protocol (MCP) server that provides intelligent memory capabilities for Claude Code, enabling persistent knowledge tracking, relationship mapping, and contextual development assistance.

Overview

This MCP server creates a sophisticated memory system that tracks Claude Code's activities, decisions, and learned patterns to provide contextual memory across sessions and projects. It uses Neo4j as a graph database to capture and analyze complex relationships between development concepts, solutions, and workflows.

Features

Core Memory Operations

• Persistent Memory Storage - Store development tasks, solutions, and patterns
• Intelligent Search - Find relevant memories by context, content, or relationships
• Relationship Mapping - Track how different concepts, files, and solutions relate
• Context Awareness - Project-specific and technology-specific memory retrieval

Advanced Intelligence

• Pattern Recognition - Automatically identify reusable development patterns
• Solution Effectiveness - Track and learn from successful approaches
• Workflow Memory - Remember and suggest optimal development sequences
• Error Prevention - Learn from past mistakes to prevent similar issues

Development Integration

• Task Execution Tracking - Monitor what Claude Code does and how
• Code Pattern Analysis - Identify and store successful code patterns
• Project Context Memory - Understand codebase conventions and dependencies
• Collaborative Learning - Share knowledge across development sessions

Architecture

Memory Types

• Task - Development tasks and their execution patterns
• CodePattern - Reusable code solutions and architectural decisions
• Problem - Issues encountered and their context
• Solution - How problems were resolved and their effectiveness
• Project - Codebase context and project-specific knowledge
• Technology - Framework, language, and tool-specific knowledge

Relationship Types

The system tracks seven categories of relationships:

1. Causal - `CAUSES`, `TRIGGERS`, `LEADS_TO`, `PREVENTS`, `BREAKS`

2. Solution - `SOLVES`, `ADDRESSES`, `ALTERNATIVE_TO`, `IMPROVES`, `REPLACES`

3. Context - `OCCURS_IN`, `APPLIES_TO`, `WORKS_WITH`, `REQUIRES`, `USED_IN`

4. Learning - `BUILDS_ON`, `CONTRADICTS`, `CONFIRMS`, `GENERALIZES`, `SPECIALIZES`

5. Similarity - `SIMILAR_TO`, `VARIANT_OF`, `RELATED_TO`, `ANALOGY_TO`, `OPPOSITE_OF`

6. Workflow - `FOLLOWS`, `DEPENDS_ON`, `ENABLES`, `BLOCKS`, `PARALLEL_TO`

7. Quality - `EFFECTIVE_FOR`, `INEFFECTIVE_FOR`, `PREFERRED_OVER`, `DEPRECATED_BY`, `VALIDATED_BY`

Installation

Prerequisites

• Python 3.10 or higher
• Neo4j database (local or cloud)
• Claude Code with MCP support

Setup

1. Clone the repository:

git clone https://github.com/viralvoodoo/claude-code-memory.git
cd claude-code-memory

2. Install dependencies:

pip install -e .

3. Set up Neo4j connection:

cp .env.example .env
# Edit .env with your Neo4j credentials

4. Initialize the database schema:

python -m claude_memory.setup

Configuration

Environment Variables

• `NEO4J_URI` - Neo4j database URI (default: bolt://localhost:7687)
• `NEO4J_USER` - Database username (default: neo4j)
• `NEO4J_PASSWORD` - Database password
• `MEMORY_LOG_LEVEL` - Logging level (default: INFO)

Claude Code Integration

Add to your Claude Code MCP configuration:

{
  "mcpServers": {
    "claude-memory": {
      "command": "python",
      "args": ["-m", "claude_memory.server"],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "your-password"
      }
    }
  }
}

Usage

Available MCP Tools

Core Memory Operations

• `store_memory` - Store new development memories with context
• `get_memory` - Retrieve specific memory by ID with relationships
• `search_memories` - Find memories by content, context, or relationships
• `update_memory` - Modify existing memory content
• `delete_memory` - Remove memory and cleanup relationships

Relationship Management

• `create_relationship` - Link memories with specific relationship types
• `get_related_memories` - Find memories connected to a specific memory
• `analyze_relationships` - Discover relationship patterns in memory graph

Development Intelligence

• `analyze_codebase` - Scan project and create contextual memory graph
• `track_task_execution` - Record development workflow and patterns
• `suggest_similar_solutions` - Find analogous past solutions
• `predict_solution_effectiveness` - Estimate success probability of approaches

Advanced Analytics

• `get_memory_graph` - Visualize knowledge network and relationships
• `find_memory_paths` - Discover connection chains between concepts
• `memory_effectiveness` - Track and analyze solution success rates

Development

Project Structure

claude-code-memory/
├── src/claude_memory/          # Main source code
│   ├── __init__.py
│   ├── server.py              # MCP server implementation
│   ├── models.py              # Data models and schemas
│   ├── database.py            # Neo4j database operations
│   ├── memory_store.py        # Core memory logic
│   ├── relationships.py       # Relationship management
│   ├── search.py              # Search and retrieval
│   └── intelligence.py        # Pattern recognition and analytics
├── tests/                     # Test suite
├── docs/                      # Documentation
├── scripts/                   # Utility scripts
└── pyproject.toml            # Project configuration

Development Setup

# Install development dependencies
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

# Run tests
pytest

# Format code
black src/ tests/
ruff --fix src/ tests/

# Type checking
mypy src/

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

1. Check existing GitHub Issues

2. Fork the repository and create a feature branch

3. Make changes following our coding standards

4. Add tests for new functionality

5. Submit a pull request with a clear description

License

This project is licensed under the MIT License - see the LICENSE file for details.

Roadmap

Phase 1: Foundation (Current)

• ✅ Project setup and basic MCP server
• 🔄 Core memory operations (CRUD)
• ⏳ Basic relationship management

Phase 2: Intelligence

• ⏳ Advanced relationship system
• ⏳ Pattern recognition
• ⏳ Context awareness

Phase 3: Integration

• ⏳ Claude Code workflow integration
• ⏳ Automatic memory capture
• ⏳ Proactive suggestions

Phase 4: Analytics

• ⏳ Memory effectiveness tracking
• ⏳ Knowledge graph visualization
• ⏳ Performance optimization

Support

• GitHub Issues - Bug reports and feature requests
• Discussions - Questions and community support
• Documentation - Detailed guides and API reference

Acknowledgments

• Model Context Protocol - Protocol specification and examples
• Neo4j - Graph database platform
• Claude Code - AI-powered development environment