Contributing to Engrams

Contributions of all kinds are welcome — bug reports, feature requests, documentation improvements, and code contributions.

Code of conduct

By participating in this project you are expected to uphold our Code of Conduct. Please report unacceptable behaviour via a GitHub issue.

Reporting bugs

Open a new issue on GitHub Issues and include:

  • A clear description of the bug
  • Steps to reproduce
  • Engrams version (engrams --version)
  • Operating system and Python version
  • Relevant error messages or log output

Suggesting enhancements

Open a GitHub issue describing:

  • The proposed enhancement
  • The problem it solves or benefit it provides
  • Any design considerations

Development setup

1. Clone and install

git clone https://github.com/stevebrownlee/engrams-mcp.git
cd engrams-mcp

# Create virtual environment (uv recommended)
uv venv
source .venv/bin/activate   # macOS/Linux
# .venv\Scripts\activate  # Windows

# Install all dependencies including dev extras
uv pip install -r requirements.txt
uv pip install -e ".[dev,dashboard,test]"

2. Run tests

pytest
# or with coverage
pytest --cov=src/engrams

3. Code style

# Format
black src/ tests/
isort src/ tests/

# Lint
flake8 src/ tests/
autoflake --remove-all-unused-imports -r src/

Pull request workflow

  1. Fork the repository
  2. Create a branch: git checkout -b feature/my-feature
  3. Make your changes and add tests
  4. Ensure all tests pass and code style is clean
  5. Push to your fork and open a PR against main
  6. Provide a clear description of your changes

Documentation improvements

Documentation lives in docs/src/pages/ as Astro .astro files. To preview locally: 

cd docs
npm install
npm run dev

Licensing

By contributing you agree that your contributions will be licensed under the Apache-2.0 License.