# Contributing to MCP Memory Service

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.

## Table of Contents

- [Code of Conduct](#code-of-conduct)
- [Ways to Contribute](#ways-to-contribute)
- [Getting Started](#getting-started)
- [Development Process](#development-process)
- [Coding Standards](#coding-standards)
- [Testing Requirements](#testing-requirements)
- [Documentation](#documentation)
- [Submitting Changes](#submitting-changes)
- [Reporting Issues](#reporting-issues)
- [Community & Support](#community--support)
- [Recognition](#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

1. **Fork the repository** on GitHub

2. **Clone your fork**:
   ```bash
   git clone https://github.com/YOUR_USERNAME/mcp-memory-service.git
   cd mcp-memory-service
   ```

3. **Install dependencies**:
   ```bash
   python install.py
   ```
   This will automatically detect your platform and install appropriate dependencies.

4. **Verify installation**:
   ```bash
   python scripts/verify_environment.py
   ```

5. **Run the service**:
   ```bash
   uv run memory server
   ```

6. **Test with MCP Inspector** (optional):
   ```bash
   npx @modelcontextprotocol/inspector uv run memory server
   ```

### Alternative: Docker Setup

For a containerized environment:
```bash
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

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

```bash
# 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:
```bash
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

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

```python
# 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

```python
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:
```python
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:

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

**Advanced Workflow Automation**:
- See [Context Provider Workflow Automation](https://github.com/doobidoo/mcp-memory-service/wiki/Context-Provider-Workflow-Automation) for automating development workflows with intelligent patterns

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

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

2. **PR Description Template**:
   ```markdown
   ## 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
   ```

3. **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:

1. **Environment**:
   - OS and version
   - Python version
   - MCP Memory Service version
   - Installation method (pip, Docker, source)

2. **Steps to Reproduce**:
   - Minimal code example
   - Exact commands run
   - Configuration used

3. **Expected vs Actual Behavior**:
   - What you expected to happen
   - What actually happened
   - Error messages/stack traces

4. **Additional Context**:
   - Screenshots if applicable
   - Relevant log output
   - Related issues

### Feature Requests

For feature requests, describe:

- The problem you're trying to solve
- Your proposed solution
- Alternative approaches considered
- Potential impact on existing functionality

## Community & Support

### Getting Help

- **Documentation**: Check the [Wiki](https://github.com/doobidoo/mcp-memory-service/wiki) first
- **Issues**: Search existing [issues](https://github.com/doobidoo/mcp-memory-service/issues) before creating new ones
- **Discussions**: Use [GitHub Discussions](https://github.com/doobidoo/mcp-memory-service/discussions) for questions
- **Response Time**: Maintainers typically respond within 2-3 days

### Communication Channels

- **GitHub Issues**: Bug reports and feature requests
- **GitHub Discussions**: General questions and community discussion
- **Pull Requests**: Code contributions and reviews

### For AI Agents

If you're an AI coding assistant, also check:
- [AGENTS.md](AGENTS.md) - Generic AI agent instructions
- [CLAUDE.md](CLAUDE.md) - Claude-specific guidelines
- [Context Provider Workflow Automation](https://github.com/doobidoo/mcp-memory-service/wiki/Context-Provider-Workflow-Automation) - Automate development workflows with intelligent patterns

## Recognition

We value all contributions! Contributors are:

- Listed in release notes for their contributions
- Mentioned in CHANGELOG.md entries
- Credited in commit messages when providing fixes/solutions
- Welcome to add themselves to a CONTRIBUTORS file (future)

### Types of Recognition

- 🐛 Bug reporters who provide detailed, reproducible issues
- 💻 Code contributors who submit PRs
- 📝 Documentation improvers
- 🧪 Test writers and reviewers
- 💬 Community helpers who support other users
- 🎨 UI/UX improvers (for dashboard contributions)

---

Thank you for contributing to MCP Memory Service! Your efforts help make AI assistants more capable and useful for everyone. 🚀

If you have questions not covered here, please open a [Discussion](https://github.com/doobidoo/mcp-memory-service/discussions) or check our [Wiki](https://github.com/doobidoo/mcp-memory-service/wiki).