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.

Code of Conduct
Ways to Contribute
Getting Started
Development Process
Coding Standards
Testing Requirements
Documentation
Submitting Changes
Security-Sensitive Changes
Autonomous Agents & AI-Generated PRs
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:

# HTTP server (background, dashboard + REST API, recommended)
memory launch

# OR MCP stdio server (for Claude Desktop integration)
memory server

Test with MCP Inspector (optional, stdio child process):
```
npx @modelcontextprotocol/inspector 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

Advanced Workflow Automation:

See 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

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 (bash scripts/pr/pre_pr_check.sh)
- Code follows style guidelines
- Documentation updated
- CHANGELOG.md updated
- No sensitive data exposed
- If adding/modifying MCP tools: tool is added to valid_actions in server/handlers/graph.py (if applicable) and write-scope enforcement is correct (see Security-Sensitive Changes)
- I am a human contributor, or I have disclosed that this PR was generated by an automated agent (see Autonomous Agents & AI-Generated PRs)

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

Security-Sensitive Changes

The following areas require extra care. PRs touching them receive additional scrutiny and may require a second maintainer review.

Protected paths

Path	Risk
`src/mcp_memory_service/web/api/mcp.py`	HTTP MCP transport, OAuth scope enforcement
`src/mcp_memory_service/server_impl.py`	MCP tool registration, write-scope gate
`src/mcp_memory_service/web/oauth/`	OAuth 2.1 implementation
`src/mcp_memory_service/storage/`	Data integrity, production database
`.github/workflows/`	CI/CD pipeline, supply-chain security

Required for any PR that adds or modifies an MCP tool

Scope enforcement: State explicitly whether the new tool is read-only or write. Read-only tools must set readOnlyHint=True in annotations. Write tools must be reachable only with a write-scoped token.
valid_actions registration: If the tool is routed through handle_memory_graph(), it must be added to the valid_actions list at the top of that function — otherwise the new branches are dead code.
Security section in PR description: Add a ## Security section explaining (a) what data the tool reads/writes, (b) how scope is enforced, and (c) any edge cases (None inputs, malformed arguments, concurrent access).

Handling a security vulnerability

Do not open a public issue. Use GitHub's private Security Advisories to report vulnerabilities confidentially.

Autonomous Agents & AI-Generated PRs

We welcome contributions from AI coding assistants and autonomous agents. However, transparency is required.

Disclosure requirement

If a PR was generated, drafted, or submitted by an automated agent (an AI system acting without direct human review of each change), the PR description must include:

## Agent Disclosure
This PR was generated by [agent name/system]. The submitting account is operated by [human name / organization].
Human review of this PR: [yes — describe what was reviewed / no — fully automated]

PRs that appear to be automated but carry no disclosure may be closed pending clarification.

Why this matters

Automated agents can miss context-specific security constraints (scope gates, invariants, production safeguards) that are not visible from the code alone.
Disclosure lets maintainers calibrate review depth accordingly.
It is not a barrier to contribution — filhocf's fully automated RFC #732 series is a model example of high-quality agent contributions. Disclosure + quality work = fast merge.

What happens without disclosure

Maintainer asks for clarification in a comment.
If no response within 7 days, PR is closed. Re-opening with disclosure is welcome.

Reporting Issues

Language

All issues, pull requests, and discussions should be written in English. This keeps the project accessible to our international community of contributors and ensures problems are searchable for others hitting the same issue. If English isn't your first language, tools like DeepL or Google Translate work well — we genuinely appreciate the effort.

Contributions opened in other languages may be translated by a maintainer, or redirected with a polite request to resubmit in English.

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

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 first
Issues: Search existing issues before creating new ones
Discussions: Use GitHub 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 - Generic AI agent instructions
CLAUDE.md - Claude-specific guidelines
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 or check our Wiki.

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History