Skip to main content

​
Prerequisites

  • Docker & Docker Compose
  • Python 3.14 with uv
  • Node.js 20+

​
Getting started

git clone https://github.com/sebastianebg/engram.git
cd engram
docker compose up -d          # PostgreSQL (pgvector) for dev

# Backend
cd backend
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
uvicorn src.engram.api.main:app --reload  # http://localhost:8000

# Frontend (new terminal)
cd frontend
npm install
npm run dev  # http://localhost:3000
Copy .env.example to .env and configure. For auth-enabled mode, run make setup-auth.

​
Key commands

make dev              # API + frontend, no auth
make dev-auth         # API + MCP + frontend, auth enabled
make lint             # ruff + mypy + eslint + typecheck
make test             # Backend unit tests
make test-mcp         # MCP integration tests (requires DB)
make test-e2e         # Playwright E2E tests
make ci-local         # Full CI simulation

​
Branching

feat/* or fix/* > PR to staging > PR to main. Both branches are protected via GitHub Rulesets. Merge commits only.

​
Commits

<type>(<scope>): <subject>
Types: feat, fix, refactor, docs, test, chore, perf. Imperative mood, 50 char subject, no period.

​
Testing

  • Backend: pytest with pytest-cov (60% coverage floor)
  • MCP: Integration tests with savepoint isolation against pgvector
  • Frontend: Playwright E2E tests
  • No PR merge without corresponding tests

​
Architecture rules

  • SQL placeholders: %s (not $1)
  • engram.mcp and engram.api never import each other
  • Services own business logic, not routers
  • All DDL via Alembic migrations