Contributing Guide

Thank you for your interest in contributing to Memo. This guide covers how to participate effectively.

Ways to Contribute

Bug Reports

Open an issue on GitHub Issues. Include:

• Memo version (memo --version)
• Operating system and architecture
• Steps to reproduce
• Expected vs actual behavior
• Logs from the terminal where Memo is running

Feature Requests

Use GitHub Discussions for feature ideas. Describe:

• The problem the feature solves
• How you'd expect it to work
• Whether it affects existing workflows

Code Contributions

1. Fork the repository
2. Create a feature branch: git checkout -b feat/my-feature
3. Make your changes following the development standards below
4. Run the full test suite (see Testing Protocol)
5. Submit a pull request against the main branch

Development Standards

Privacy First

Memo is a local-first application. All contributions must respect this:

• No telemetry or analytics code
• No network calls except those explicitly requested by the user (API providers, cloud sync, web search)
• User data must never leave the machine without explicit user action and encryption

Performance

• Backend: avoid blocking the HTTP handler goroutines. Use background workers for long operations.
• Frontend: avoid per-message AnimationController instances. Minimize widget rebuilds.
• Memory: use streaming where possible, avoid loading entire datasets into RAM.

Documentation

Every user-facing feature needs:

• A section in the release notes (versionNoteEN.md and versionNoteTR.md)
• Updates to configuration reference if new config keys are added
• Doc page if the feature is non-trivial

Testing

• Backend tests use go test -race — every test must pass under the race detector
• Concurrency paths must have dedicated test coverage
• Frontend tests use Flutter's flutter_test package
• No PR is accepted without passing CI

Key Areas for Contribution

Area	What's Needed
Agent UI	Rich visualization of tool execution, progress indicators
Tests	Backend test coverage, integration tests, concurrency tests
Multi-step planning	Improve the chief model's planning and task decomposition
File edit tool	Smarter diff-based editing, conflict resolution
Git tools	Native git integration beyond shell commands

Philosophy

Memo is built on these principles, in order of priority:

1. Correctness — features work correctly in all states, including failure states
2. Privacy — the user controls all data; nothing is sent anywhere without consent
3. Performance — fast enough to feel instant, even with large memory stores
4. Simplicity — straightforward code, standard library where possible, no over-engineering

Pull Request Checklist

• go test ./... -race passes
• go build ./... succeeds
• flutter analyze lib/ passes (if Flutter touched)
• No TODO or FIXME comments left in code
• New config keys documented
• Release notes updated
• No hardcoded secrets or keys