Contributing to Basic Memory

May 23, 2026 ยท View on GitHub

Thank you for considering contributing to Basic Memory! This document outlines the process for contributing to the project and how to get started as a developer.

Getting Started

Development Environment

  1. Clone the Repository:

    git clone https://github.com/basicmachines-co/basic-memory.git
cd basic-memory

  2. Install Dependencies:

    # Using just (recommended)
just install

# Or using uv
uv install -e ".[dev]"

# Or using pip
pip install -e ".[dev]"

    Note: Basic Memory uses just as a modern command runner. Install with brew install just or cargo install just.

  3. Activate the Virtual Environment

    source .venv/bin/activate

  4. Run the Tests:

    # Run all tests with unified coverage (unit + integration)
just test

# Run unit tests only (fast, no coverage)
just test-unit

# Run integration tests only (fast, no coverage)
just test-int

# Generate HTML coverage report
just coverage

# Run a specific test
pytest tests/path/to/test_file.py::test_function_name

Development Workflow

  1. Fork the Repo: Fork the repository on GitHub and clone your copy.
  2. Create a Branch: Create a new branch for your feature or fix. 
    git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-you-are-fixing
  3. Make Your Changes: Implement your changes with appropriate test coverage.
  4. Check Code Quality: 
    # Run all checks at once
just check

# Or run individual checks
just lint      # Run linting
just format    # Format code
just type-check  # Type checking
  5. Test Your Changes: Ensure all tests pass locally and maintain 100% test coverage. 
    just test
  6. Submit a PR: Submit a pull request with a detailed description of your changes.

LLM-Assisted Development

This project is designed for collaborative development between humans and LLMs (Large Language Models):

  1. CLAUDE.md: The repository includes a CLAUDE.md file that serves as a project guide for both humans and LLMs. This file contains:

    • Key project information and architectural overview
    • Development commands and workflows
    • Code style guidelines
    • Documentation standards

  2. AI-Human Collaborative Workflow:

    • We encourage using LLMs like Claude for code generation, reviews, and documentation
    • When possible, save context in markdown files that can be referenced later
    • This enables seamless knowledge transfer between different development sessions
    • Claude can help with implementation details while you focus on architecture and design

  3. Adding to CLAUDE.md:

    • If you discover useful project information or common commands, consider adding them to CLAUDE.md
    • This helps all contributors (human and AI) maintain consistent knowledge of the project

Pull Request Process

  1. Create a Pull Request: Open a PR against the main branch with a clear title and description.
  2. Sign the Developer Certificate of Origin (DCO): All contributions require signing our DCO, which certifies that you have the right to submit your contributions. This will be automatically checked by our CLA assistant when you create a PR.
  3. PR Description: Include:
    • What the PR changes
    • Why the change is needed
    • How you tested the changes
    • Any related issues (use "Fixes #123" to automatically close issues)
  4. Code Review: Wait for code review and address any feedback.
  5. CI Checks: Ensure all CI checks pass.
  6. Merge: Once approved, a maintainer will merge your PR.

Developer Certificate of Origin

By contributing to this project, you agree to the Developer Certificate of Origin (DCO). This means you certify that:

  • You have the right to submit your contributions
  • You're not knowingly submitting code with patent or copyright issues
  • Your contributions are provided under the project's license (AGPL-3.0)

This is a lightweight alternative to a Contributor License Agreement and helps ensure that all contributions can be properly incorporated into the project and potentially used in commercial applications.

Signing Your Commits

Sign your commit:

Using the -s or --signoff flag:

git commit -s -m "Your commit message"

This adds a Signed-off-by line to your commit message, certifying that you adhere to the DCO.

The sign-off certifies that you have the right to submit your contribution under the project's license and verifies your agreement to the DCO.

Code Style Guidelines

  • Python Version: Python 3.12+ with full type annotations (3.12+ required for type parameter syntax)
  • Line Length: 100 characters maximum
  • Formatting: Use ruff for consistent styling
  • Import Order: Standard lib, third-party, local imports
  • Naming: Use snake_case for functions/variables, PascalCase for classes
  • Documentation: Add docstrings to public functions, classes, and methods
  • Type Annotations: Use type hints for all functions and methods

Testing Guidelines

Test Structure

Basic Memory uses two test directories with unified coverage reporting:

  • tests/: Unit tests that test individual components in isolation

    • Fast execution with extensive mocking
    • Test individual functions, classes, and modules
    • Run with: just test-unit (no coverage, fast)

  • test-int/: Integration tests that test real-world scenarios

    • Test full workflows with real database and file operations
    • Include performance benchmarks
    • More realistic but slower than unit tests
    • Run with: just test-int (no coverage, fast)

Running Tests

# Run all tests with unified coverage report
just test

# Run only unit tests (fast iteration)
just test-unit

# Run only integration tests
just test-int

# Generate HTML coverage report
just coverage

# Run specific test
pytest tests/path/to/test_file.py::test_function_name

# Run tests excluding benchmarks
pytest -m "not benchmark"

# Run only benchmark tests
pytest -m benchmark test-int/test_sync_performance_benchmark.py

Performance Benchmarks

The test-int/test_sync_performance_benchmark.py file contains performance benchmarks that measure sync and indexing speed:

  • test_benchmark_sync_100_files - Small repository performance
  • test_benchmark_sync_500_files - Medium repository performance
  • test_benchmark_sync_1000_files - Large repository performance (marked slow)
  • test_benchmark_resync_no_changes - Re-sync performance baseline

Run benchmarks with:

# Run all benchmarks (excluding slow ones)
pytest test-int/test_sync_performance_benchmark.py -v -m "benchmark and not slow"

# Run all benchmarks including slow ones
pytest test-int/test_sync_performance_benchmark.py -v -m benchmark

# Run specific benchmark
pytest test-int/test_sync_performance_benchmark.py::test_benchmark_sync_100_files -v

See test-int/BENCHMARKS.md for detailed benchmark documentation.

Testing Best Practices

  • Coverage Target: We aim for high test coverage for all code
  • Test Framework: Use pytest for unit and integration tests
  • Mocking: Avoid mocking in integration tests; use sparingly in unit tests
  • Edge Cases: Test both normal operation and edge cases
  • Database Testing: Use in-memory SQLite for testing database operations
  • Fixtures: Use async pytest fixtures for setup and teardown
  • Markers: Use @pytest.mark.benchmark for benchmarks, @pytest.mark.slow for slow tests

Creating Issues

If you're planning to work on something, please create an issue first to discuss the approach. Include:

  • A clear title and description
  • Steps to reproduce if reporting a bug
  • Expected behavior vs. actual behavior
  • Any relevant logs or screenshots
  • Your proposed solution, if you have one

Code of Conduct

All contributors must follow the Code of Conduct.

Thank You!

Your contributions help make Basic Memory better. We appreciate your time and effort!