Contributing to TradeMemory Protocol

March 27, 2026 · View on GitHub

We welcome contributions! Whether it's bug fixes, new features, documentation improvements, or broker integrations — every contribution helps make AI trading agents smarter.

Getting Started

1. Fork & Clone

# Fork the repo on GitHub, then:
git clone https://github.com/YOUR_USERNAME/tradememory-protocol.git
cd tradememory-protocol

2. Set Up Development Environment

python -m venv venv
source venv/bin/activate    # Linux/Mac
# venv\Scripts\activate     # Windows

pip install -e ".[dev]"
cp .env.example .env

3. Install Pre-commit Hooks

pre-commit install

This runs ruff, mypy, and formatting checks automatically on every commit.

4. Verify Setup

python -m pytest tests/ -v
# Expected: 1,233 passed

Making Changes

Branch Naming

Create a branch from master for your work:

git checkout -b feat/your-feature    # New feature
git checkout -b fix/your-bugfix      # Bug fix
git checkout -b docs/your-change     # Documentation
git checkout -b refactor/your-change # Refactoring

Commit Messages

We use Conventional Commits:

feat: add Binance exchange connector
fix: correct timezone handling in reflection engine
docs: update API reference for risk tools
refactor: simplify state persistence logic
test: add integration tests for trade journal

Code Style

  • Python 3.10+ — Use modern syntax (type hints, f-strings)
  • Linting — Ruff for linting and formatting
  • Type checking — mypy with --ignore-missing-imports
  • Type hints — Required for public function signatures
# Lint and auto-fix
ruff check src/ tests/ --fix

# Type check
mypy src/tradememory/ --ignore-missing-imports

# Run tests
python -m pytest tests/ -v

# Run tests with coverage
python -m pytest tests/ --cov=src/tradememory

If you installed pre-commit hooks (step 3 above), these checks run automatically on git commit.

Testing Requirements

All PRs must pass tests. No exceptions.

  • Add tests for new features in tests/
  • Ensure existing tests still pass: python -m pytest tests/ -v
  • Aim for meaningful test coverage, not 100% line coverage

Submitting a Pull Request

1. Push Your Branch

git push origin feat/your-feature

2. Create the PR

  • Open a PR against the master branch
  • Use a clear title (e.g., "feat: add Binance connector")
  • Fill in the PR template with:
    • Summary — What does this PR do?
    • Test plan — How did you verify it works?

3. PR Checklist

Before submitting, confirm:

  • python -m pytest tests/ -v passes (1,233+ tests)
  • New features include tests
  • ruff check and mypy pass (or use pre-commit hooks)
  • Commit messages follow conventional commits
  • Documentation updated if behavior changed
  • No secrets, API keys, or credentials in the code

4. Review Process

  • A maintainer will review your PR
  • Address any feedback with additional commits
  • Once approved, we'll merge it

What We're Looking For

High Priority

  • Broker integrations — Binance, Bybit, Alpaca, Interactive Brokers
  • Reflection algorithms — Better pattern detection, multi-timeframe analysis
  • Performance optimizations — Faster queries, better caching
  • Evolution Engine extensions — Custom fitness functions, multi-asset support
  • OWM enhancements — New memory type adapters

Also Welcome

  • Documentation improvements and translations
  • Dashboard UI enhancements
  • Example trading strategies
  • Bug reports and fixes
  • Test coverage improvements

Issue Guidelines

Bug Reports

Use the Bug Report template and include:

  • Steps to reproduce
  • Expected vs actual behavior
  • Environment (OS, Python version)
  • Error messages or logs

Feature Requests

Use the Feature Request template and include:

  • Problem description
  • Proposed solution
  • Use case

Architecture Notes

Before contributing, understand the key design principles:

  1. Platform-agnostic core — TradeMemory does NOT connect to brokers directly. Broker-specific code stays in adapters (scripts/trade_adapter.py, scripts/mt5_sync.py).
  2. 5 OWM Memory Types — Episodic (trade events), Semantic (strategy rules), Procedural (behavioral patterns), Affective (confidence/risk state), Prospective (conditional plans). Plus Evolution Engine for autonomous strategy discovery.
  3. All timestamps in UTC — No exceptions.
  4. LLM outputs are untrusted — Always validate and provide fallback defaults.

See Architecture Overview for the full design.

Code of Conduct

Be respectful. We're all here to build something useful.

  • DO: Ask questions, propose ideas, report bugs, share insights
  • DON'T: Be rude, spam, or demand features

We reserve the right to block contributors who don't follow basic courtesy.

License

By contributing to TradeMemory Protocol, you agree that your contributions will be licensed under the MIT License.

Thanks for contributing! Every PR makes AI trading agents a little smarter.

Built by Mnemox — AI memory infrastructure.