Contributing - Basic Memory

Thank you for considering contributing to Basic Memory! This guide covers the process for contributing and getting started as a developer.

Quick Start

Fork the repository

Fork basicmachines-co/basic-memory on GitHub

Clone your fork

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

Install dependencies

just install
source .venv/bin/activate

Create a branch

git checkout -b feature/your-feature-name

Make changes and test

# Make your changes
just check  # Lint, format, typecheck, test

Commit with sign-off

git commit -s -m "Add your feature"
git push origin feature/your-feature-name

Create pull request

Open a PR on GitHub against the main branch

Development Environment

Prerequisites

Python 3.12+

Required for type parameter syntax

just

Modern command runner

brew install just

Docker (optional)

For PostgreSQL tests

uv (recommended)

Fast Python package manager

Setup

# Install dependencies
just install

# Activate virtual environment
source .venv/bin/activate

# Verify setup
just test-unit-sqlite

Development Workflow

1. Code Changes

Make your changes following these guidelines:

Code Style

Line length: 100 characters
Use type annotations for all functions
Follow existing patterns
Add docstrings to public APIs

Testing

Write tests for new features
Maintain 100% coverage where practical
Add integration tests for workflows
Use markers: @pytest.mark.benchmark, @pytest.mark.slow

Documentation

Update relevant docs in docs/
Add docstrings to public functions
Update CHANGELOG.md for user-facing changes

2. Quality Checks

Run quality checks before committing:

# Run all checks
just check

# Or individually
just lint       # Auto-fix linting issues
just format     # Format with ruff
just typecheck  # Type check with pyright
just test       # Run all tests

3. Commit Guidelines

All commits must be signed off with the -s flag to certify you agree to the Developer Certificate of Origin.

# Commit with sign-off
git commit -s -m "feat: add new feature"

Commit message format:

type: short description

Longer explanation if needed.

Fixes #123

Types:

feat: New feature
fix: Bug fix
docs: Documentation only
style: Code style changes (formatting)
refactor: Code refactoring
test: Adding or updating tests
chore: Build/tooling changes

Pull Request Process

Creating a Pull Request

Update your branch

git fetch upstream
git rebase upstream/main

Push to your fork

git push origin feature/your-feature-name

Open PR on GitHub

Use a clear, descriptive title
Explain what the PR changes and why
Reference related issues with Fixes #123
Add screenshots for UI changes

PR Template

## Description

Brief description of changes

## Motivation

Why is this change needed?

## Testing

How did you test these changes?

## Checklist

- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] Signed commits (`git commit -s`)
- [ ] All CI checks pass

Code Review

A maintainer will review your PR. Address feedback by pushing new commits to your branch.

What reviewers look for:

✅ Code follows style guidelines
✅ Tests cover new functionality
✅ Documentation is updated
✅ No breaking changes (or clearly documented)
✅ CI checks pass

Developer Certificate of Origin

By contributing, you agree to the Developer Certificate of Origin (DCO). What this means:

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

How to sign off:

# Use -s flag when committing
git commit -s -m "Your commit message"

This adds a Signed-off-by line to your commit:

feat: add new feature

Signed-off-by: Your Name <[email protected]>

Testing Guidelines

Running Tests

All Tests
Unit Tests
Integration Tests
Selective

# SQLite + PostgreSQL
just test

# SQLite only (faster)
just test-sqlite

# PostgreSQL only
just test-postgres

# Fast, isolated tests
just test-unit-sqlite
just test-unit-postgres

# Real workflows, no mocks
just test-int-sqlite
just test-int-postgres

# Changed files only
just testmon

# Smoke test
just test-smoke

# Benchmarks
just test-benchmark

# Specific test
pytest tests/test_file.py::test_function

Writing Tests

Choose test type

Unit test (tests/) - Test individual functions with mocks
Integration test (test-int/) - Test complete workflows

Write the test

import pytest

@pytest.mark.asyncio
async def test_create_entity(async_session):
    # Arrange
    repo = EntityRepository(async_session)
    
    # Act
    entity = await repo.create(title="Test")
    
    # Assert
    assert entity.title == "Test"
    assert entity.external_uuid is not None

Add markers if needed

@pytest.mark.benchmark  # Slow performance test
@pytest.mark.slow       # > 5 seconds
@pytest.mark.postgres   # PostgreSQL only

Run your test

pytest tests/test_file.py::test_create_entity -v

Coverage Requirements

We aim for high test coverage. Use # pragma: no cover sparingly and only for:

TYPE_CHECKING blocks
Error handlers requiring failure injection
Runtime-mode-dependent paths that can’t be tested in one run

# Generate coverage report
just coverage
open htmlcov/index.html

LLM-Assisted Development

Basic Memory is designed for collaborative development between humans and LLMs.

Using Claude/GPT for Contributions

CLAUDE.md Reference

The CLAUDE.md file contains:

Project architecture overview
Development commands
Code style guidelines
Common patterns

Use this to provide context to AI assistants.

AI-Human Workflow

AI generates code based on specifications
Human reviews and runs tests
AI adjusts based on test results
Human commits with sign-off

This enables faster development while maintaining quality.

Knowledge Persistence

Save important context in markdown files:

Decision records
Architecture notes
Common patterns

This enables knowledge transfer between sessions.

Creating Issues

Before starting work, create an issue to discuss the approach. Good issue template:

## Description

Clear description of the bug or feature request

## Steps to Reproduce (for bugs)

1. Step 1
2. Step 2
3. See error

## Expected Behavior

What should happen

## Actual Behavior

What actually happens

## Proposed Solution (optional)

Your suggested approach

## Environment

- Basic Memory version: 0.15.0
- Python version: 3.12.1
- OS: macOS 14.2

Areas for Contribution

Bug Fixes

Check GitHub issues labeled bug

Features

Check issues labeled enhancement

Documentation

Improve guides, examples, docstrings

Testing

Increase test coverage, add benchmarks

Performance

Optimize sync, search, indexing

Integrations

New import sources, MCP tools

Good First Issues

Look for issues labeled good first issue:

Documentation improvements
Small bug fixes
Additional test coverage
Error message improvements

Code of Conduct

All contributors must follow the Code of Conduct.

Summary:

Be respectful and inclusive
Welcome newcomers
Focus on technical merit
Assume good faith
Disagree constructively

Getting Help

Discord Community

Ask questions and discuss development

GitHub Discussions

Feature requests and longer discussions

GitHub Issues

Report bugs and request features

Development Guide

Detailed development setup

Thank You!

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

Get Started

Core Concepts

User Guide

Cloud Features

Advanced

​Quick Start

​Development Environment

​Prerequisites

Python 3.12+

just

Docker (optional)

uv (recommended)

​Setup

​Development Workflow

​1. Code Changes

​2. Quality Checks

​3. Commit Guidelines

​Pull Request Process

​Creating a Pull Request

​PR Template

​Code Review

​Developer Certificate of Origin

​Testing Guidelines

​Running Tests

​Writing Tests

​Coverage Requirements

​LLM-Assisted Development

​Using Claude/GPT for Contributions

​Creating Issues

​Areas for Contribution

Bug Fixes

Features

Documentation

Testing

Performance

Integrations

​Good First Issues

​Code of Conduct

​Getting Help

Discord Community

GitHub Discussions

GitHub Issues

Development Guide

​Thank You!

Build docs developers (and LLMs) love

Quick Start

Development Environment

Prerequisites

Setup

Development Workflow

1. Code Changes

2. Quality Checks

3. Commit Guidelines

Pull Request Process

Creating a Pull Request

PR Template

Code Review

Developer Certificate of Origin

Testing Guidelines

Running Tests

Writing Tests

Coverage Requirements

LLM-Assisted Development

Using Claude/GPT for Contributions

Creating Issues

Areas for Contribution

Good First Issues

Code of Conduct

Getting Help

Thank You!