Skip to main content

Contributing to Engram

We welcome contributions to Engram! This guide will help you get started.

Development Setup​

Prerequisites​

  • Python 3.13+
  • Node.js 18+
  • Docker and Docker Compose
  • uv (Python package manager)

Local Setup​

# Clone the repository
git clone https://github.com/your-org/engram.git
cd engram

# Create virtual environment
uv venv --python 3.13
source .venv/bin/activate

# Install dependencies
uv pip install -e ".[dev]"

# Start database
docker compose up -d

# Run tests
pytest tests/

Frontend Setup​

cd frontend
npm install
npm run dev

Code Standards​

Python​

We use ruff for linting and formatting, and mypy for type checking:

# Lint
ruff check src/

# Format
ruff format src/

# Type check
mypy src/engram/

TypeScript​

TypeScript strict mode is enabled. Run checks with:

cd frontend
npm run lint
npm run typecheck

Testing​

Backend Tests​

# Run all tests
pytest tests/

# Run specific test
pytest tests/test_file.py -k "test_name"

# Run with coverage
pytest --cov=src/engram tests/

Frontend Tests​

cd frontend

# Unit tests
npm test

# E2E tests
npm run test:e2e

Git Workflow​

Branch Naming​

Format: ENG-<phase>.<epic>.<task> or descriptive names like fix-search-ranking.

Commit Messages​

Use conventional commits:

feat: add batch enrichment support
fix: correct embedding dimension mismatch
docs: update API reference
refactor: simplify chunker logic

Pull Requests​

  1. Create a feature branch from main
  2. Make your changes with tests
  3. Ensure all checks pass
  4. Open a PR with a clear description
  5. Address review feedback

Issue Tracking​

We use issue numbering format: ENG-<phase>.<epic>.<task>

# TODO(ENG-2.3.1): Implement memory decay algorithm
# MOCK(ENG-1.2.3): Returns hardcoded response
# DEPENDS(ENG-1.4.2): Requires streaming infrastructure

Documentation​

  • Update relevant docs when changing functionality
  • Add JSDoc/docstrings for public APIs
  • Keep README files current

Questions?​

Open an issue or reach out to the maintainers.