Momo

Momo is a local-first personal assistant with:

• A CLI (momo ...)
• A FastAPI backend + web UI
• Tool execution with approvals
• Memory extraction/retrieval and daily briefing generation

Quickstart

1. Server Deployment (Docker Recommended) Use Docker Compose to run the main Momo app stack:

docker compose up -d

This starts:

• momo-server: the FastAPI app and web frontend
• momo-face: the face daemon process
• momo-dozzle: optional container log viewer

The stack uses a single repo Dockerfile, and Compose reuses that one image for both momo-server and momo-face.

The server will be listening on http://localhost:8000. Dozzle is also included for container logs on the Momo host at http://127.0.0.1:9999 by default.

2. CLI Usage (Local installation) If you want to use the momo command-line tools, create a virtualenv and install the package locally:

source activate_env.sh
pip install -e .

Then run CLI chat:

momo chat

Raspberry Pi Zero Client (Whisplay Display)

This project runs natively on a Raspberry Pi 5 serving a Chromium Web Kiosk.

Architecture

• momo/main.py: Typer CLI entrypoint
• momo/api/: FastAPI server and routes
• momo/face/: face daemon backend and face controller runtime
• momo/agent/: Agent runtime + LLM orchestration
• momo/tools/: Tool registry and tool handlers
• momo/connectors/: Integrations (weather, Hue, Google Calendar, Home Assistant)
• momo/memory/: Memory journal, extraction, retrieval, OpenMemory backend
• momo/briefing/: Daily brief generation, storage, scheduler
• momo/web_app/: React/Vite frontend, public assets, and generated web files

Configuration

Config is loaded from profile storage and mapped into typed models in momo/config.py.

Common overrides include:

• db_path
• model_provider
• model
• voice.*
• stt.*
• face.*
• home_assistant.*
• weather.*
• briefing.*
• ai_hub.*

Docker / observability overrides:

• MOMO_DOZZLE_PORT changes the published Dozzle port for the Momo host stack
• MOMO_DOZZLE_BIND_HOST changes the bind address for Dozzle and defaults to 127.0.0.1

For appliance deployments, the same variables apply to docker-compose.appliance.yml. Set MOMO_DOZZLE_BIND_HOST=0.0.0.0 only if you intentionally want Dozzle reachable from other machines on your LAN.

The AI hub now lives in the separate momo-ai-hub repository and is expected to run as an external service configured through ai_hub.*. The current HTTP contract between the two lives in momo-ai-hub/CONTRACT.md.

Development

Preferred agent/developer setup:

make setup

This creates .venv, installs the full supported runtime extras (dev,knowledge,memory,voice), and installs web tooling when npm is available. Use Python 3.11 or 3.12 for the full runtime stack when possible. Some voice/ML dependencies do not yet install cleanly on Python 3.13.

If the full runtime dependency graph is not available on your machine, use the lean verification toolchain:

make setup-toolchain

This installs only the Python packages needed for linting, typing, migrations, and Python tests. This installs only the Python packages needed for linting, typing, migrations, and Python tests.

Primary verification commands:

make lint
make typecheck
make test-fast
make test-smoke

CI now enforces make lint-python, make typecheck, make test-fast, and make test-web.

Focused verification commands:

make typecheck-auth
make typecheck-organizer
make typecheck-email
make typecheck-knowledge
make typecheck-connectors
make typecheck-finance
make test-auth
make test-organizer
make test-email
make test-knowledge
make test-connectors
make test-finance

Manual equivalents:

pip install -e ".[dev]"

Frontend unit tests use Vitest and Playwright. You need Node 20+ available for the current web tooling and browser lane.

Frontend TypeScript Build Flow

• Frontend source lives under momo/web_app/src/.
• Shared public assets live under momo/web_app/public/.
• Built bundles are emitted into momo/web_app/dist/.
• Generated image/chart files served at /generated/ live under momo/web_app/generated/.
• npm run build:web:app builds the Vite app under momo/web_app/.
• npm run build:web is the production web build entrypoint used by Docker.
• npm run lint:web runs frontend type checks plus CSS linting for the app public assets.

Docker behavior:

• The image build runs npm ci and npm run build:web, so built web assets are present in the image automatically.
• Compose uses one shared repo image for both momo-server and momo-face.
• docker compose startup for momo-server does one initial npm run build:web, then starts a live Vite build watcher alongside the Python server.
• Frontend edits inside the bind-mounted repo should rebuild momo/web_app/dist/ automatically without restarting the container.
• Generated user-visible files persist through the bind mount at momo/web_app/generated/.

UI Regression and Browser Testing

• npm run test:web:app runs Vitest for the web app under momo/web_app/.
• npm run test:web:e2e runs Playwright browser tests under tests/e2e/.
• make test-web runs the frontend unit lane.
• make test-web-e2e runs the browser smoke lane.

Current browser smoke coverage starts with the login page so the E2E stack can be validated before the new /home route lands.

UI Debug Mode Direction

The new app scaffold includes a debug-mode seam intended for agent-assisted diagnosis. The long-term contract is:

• stable data-testid or data-ui selectors for critical regions
• explicit data-state markers for loading, ready, empty, and error UI
• structured client logging for route and API failures

The login route keeps stable selectors so Playwright can smoke-test the browser stack quickly.

Email OAuth Setup

Gmail OAuth:

• Provide a Google web OAuth client in the Momo Google config directory as credentials.json
• Register this callback URI in Google Cloud:
  • https://momo.goinsfamily.org/v1/email/oauth/callback
• Optional env override:
  • MOMO_EMAIL_GOOGLE_REDIRECT_URI=https://momo.goinsfamily.org/v1/email/oauth/callback

Outlook OAuth:

• Set these env vars for momo-server:
  • MOMO_MS_EMAIL_CLIENT_ID
  • MOMO_MS_EMAIL_CLIENT_SECRET
  • optional MOMO_MS_EMAIL_TENANT (defaults to common)
  • recommended MOMO_MS_EMAIL_REDIRECT_URI=https://momo.goinsfamily.org/v1/email/oauth/callback
• Register the same callback URI in Azure / Microsoft Entra.

Run lint and type checks manually:

npm run lint:web
ruff check momo tests scripts
mypy momo

Run all linting:

npm run lint

Run Python tests:

pytest

Run the focused smoke lane:

make test-smoke

Run web UI unit tests:

npm run test:web

Run browser smoke tests:

npm run test:web:e2e

Run both:

npm test

Forgejo Actions runs lint, type checks, a focused smoke lane, and the full Python suite (see .forgejo/workflows/ci.yml). When a push to main passes all CI jobs, Forgejo also builds and publishes the Momo container image to registry.goinsfamily.org/<owner>/<repo> with :latest, :<version>, :<version>-build.<run_number>, and :sha-<commit> tags.

Debug and repro scripts (e.g. debug_display.py, repro_latency.py) live in scripts/. Run them from the repo root, e.g. python scripts/debug_stt.py or python scripts/repro_latency.py (with the project installed: pip install -e .).

Memory Migration

Legacy local SQLite memory rows can be migrated into OpenMemory:

Dry-run:

python scripts/migrate_memory_to_openmemory.py

Apply migration:

python scripts/migrate_memory_to_openmemory.py --apply

Optional flags:

• --db-path /path/to/momo_memory.sqlite3
• --limit 500

Dependency Strategy

• Core app dependencies live in pyproject.toml under [project.dependencies].
• Optional feature stacks live under extras:
  • knowledge
  • memory
  • voice
• Dev/test tooling lives in [project.optional-dependencies].dev.
• Baseline pinned sets are included in requirements.lock and requirements-dev.lock.

TODO:

• Files for Momo case need to be uploaded and then 3d printed