Contributing to MCP Memory Service

September 15, 2025 · View on GitHub

Thank you for your interest in contributing to MCP Memory Service! 🎉

This project provides semantic memory and persistent storage for AI assistants through the Model Context Protocol. We welcome contributions of all kinds - from bug fixes and features to documentation and testing.

Code of Conduct
Ways to Contribute
Getting Started
Development Process
Coding Standards
Testing Requirements
Documentation
Submitting Changes
Reporting Issues
Community & Support
Recognition

Code of Conduct

We are committed to providing a welcoming and inclusive environment for all contributors. Please:

Be respectful and considerate in all interactions
Welcome newcomers and help them get started
Focus on constructive criticism and collaborative problem-solving
Respect differing viewpoints and experiences
Avoid harassment, discrimination, or inappropriate behavior

Ways to Contribute

🐛 Bug Reports

Help us identify and fix issues by reporting bugs with detailed information.

✨ Feature Requests

Suggest new features or improvements to existing functionality.

📝 Documentation

Improve README, Wiki pages, code comments, or API documentation.

🧪 Testing

Write tests, improve test coverage, or help with manual testing.

💻 Code Contributions

Fix bugs, implement features, or improve performance.

🌍 Translations

Help make the project accessible to more users (future goal).

💬 Community Support

Answer questions in Issues, Discussions, or help other users.

Getting Started

Prerequisites

Python 3.10 or higher
Git
Platform-specific requirements:
- macOS: Homebrew Python recommended for SQLite extension support
- Windows: Visual Studio Build Tools for some dependencies
- Linux: Build essentials package

Setting Up Your Development Environment

Fork the repository on GitHub

Clone your fork:

git clone https://github.com/YOUR_USERNAME/mcp-memory-service.git
cd mcp-memory-service

Install dependencies:
```
python install.py
```
This will automatically detect your platform and install appropriate dependencies.
Verify installation:
```
python scripts/verify_environment.py
```
Run the service:
```
uv run memory server
```

Test with MCP Inspector (optional):

npx @modelcontextprotocol/inspector uv run memory server

Alternative: Docker Setup

For a containerized environment:

docker-compose up -d  # For MCP mode
docker-compose -f docker-compose.http.yml up -d  # For HTTP API mode

Development Process

1. Create a Feature Branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-description

Use descriptive branch names:

feature/ for new features
fix/ for bug fixes
docs/ for documentation
test/ for test improvements
refactor/ for code refactoring

2. Make Your Changes

Write clean, readable code
Follow the coding standards (see below)
Add/update tests as needed
Update documentation if applicable
Keep commits focused and atomic

3. Test Your Changes

# Run all tests
pytest tests/

# Run specific test file
pytest tests/test_server.py

# Run with coverage
pytest --cov=mcp_memory_service tests/

4. Commit Your Changes

Use semantic commit messages:

git commit -m "feat: add memory export functionality"
git commit -m "fix: resolve timezone handling in memory search"
git commit -m "docs: update installation guide for Windows"
git commit -m "test: add coverage for storage backends"

Format: <type>: <description>

Types:

feat: New feature
fix: Bug fix
docs: Documentation changes
test: Test additions or changes
refactor: Code refactoring
perf: Performance improvements
chore: Maintenance tasks

5. Push to Your Fork

git push origin your-branch-name

6. Create a Pull Request

Open a PR from your fork to the main repository with:

Clear title describing the change
Description of what and why
Reference to any related issues
Screenshots/examples if applicable

Coding Standards

Python Style Guide

Follow PEP 8 with these modifications:
- Line length: 88 characters (Black formatter default)
- Use double quotes for strings
Use type hints for all function signatures
Write descriptive variable and function names
Add docstrings to all public functions/classes (Google style)

Code Organization

# Import order
import standard_library
import third_party_libraries
from mcp_memory_service import local_modules

# Type hints
from typing import Optional, List, Dict, Any

# Async functions
async def process_memory(content: str) -> Dict[str, Any]:
    """Process and store memory content.

    Args:
        content: The memory content to process

    Returns:
        Dictionary containing memory metadata
    """
    # Implementation

Error Handling

Use specific exception types
Provide helpful error messages
Log errors appropriately
Never silently fail

try:
    result = await storage.store(memory)
except StorageError as e:
    logger.error(f"Failed to store memory: {e}")
    raise MemoryServiceError(f"Storage operation failed: {e}") from e

Testing Requirements

Writing Tests

Place tests in tests/ directory
Name test files with test_ prefix
Use descriptive test names
Include both positive and negative test cases
Mock external dependencies

Example test:

import pytest
from mcp_memory_service.storage import SqliteVecStorage

@pytest.mark.asyncio
async def test_store_memory_success():
    """Test successful memory storage."""
    storage = SqliteVecStorage(":memory:")
    result = await storage.store("test content", tags=["test"])
    assert result is not None
    assert "hash" in result

Test Coverage

Aim for >80% code coverage
Focus on critical paths and edge cases
Test error handling scenarios
Include integration tests where appropriate

Documentation

Code Documentation

Add docstrings to all public APIs
Include type hints
Provide usage examples in docstrings
Keep comments concise and relevant

Project Documentation

When adding features or making significant changes:

Update README.md if needed
Add/update Wiki pages for detailed guides
Update CHANGELOG.md following Keep a Changelog format
Update AGENTS.md or CLAUDE.md if development workflow changes

API Documentation

Document new MCP tools in docs/api/tools.md
Include parameter descriptions and examples
Note any breaking changes

Submitting Changes

Pull Request Guidelines

PR Title: Use semantic format (e.g., "feat: add batch memory operations")

PR Description Template:

## Description
Brief description of changes

## Motivation
Why these changes are needed

## Changes
- List of specific changes
- Breaking changes (if any)

## Testing
- How you tested the changes
- Test coverage added

## Screenshots
(if applicable)

## Related Issues
Fixes #123

PR Checklist:
- Tests pass locally
- Code follows style guidelines
- Documentation updated
- CHANGELOG.md updated
- No sensitive data exposed

Review Process

PRs require at least one review
Address review feedback promptly
Keep discussions focused and constructive
Be patient - reviews may take a few days

Reporting Issues

Bug Reports

When reporting bugs, include:

Environment:
- OS and version
- Python version
- MCP Memory Service version
- Installation method (pip, Docker, source)
Steps to Reproduce:
- Minimal code example
- Exact commands run
- Configuration used
Expected vs Actual Behavior:
- What you expected to happen
- What actually happened
- Error messages/stack traces
Additional Context:
- Screenshots if applicable
- Relevant log output
- Related issues