docker-compose.example.yml

# Mnemolis Full Stack — Example Docker Compose
# This file shows all services that Mnemolis can connect to, running together on mnemo-net.
# Copy to docker-compose.yml and fill in your credentials before running.
#
# Usage:
#   docker network create mnemo-net
#   docker compose up -d

services:

  # ---------------------------------------------------------------------------
  # Mnemolis — unified knowledge broker
  # REST API: http://your-host:8888
  # MCP:      http://your-host:8888/mcp  (Streamable HTTP)
  # API docs: http://your-host:8888/docs
  # ---------------------------------------------------------------------------
  mnemolis:
    build: .
    container_name: mnemolis
    restart: unless-stopped
    ports:
      - "8888:8000"
    environment:
      TZ: ""                          # your timezone e.g. America/New_York — REQUIRED for accurate "this morning"/"while at work" changes queries, container defaults to UTC otherwise
      KIWIX_URL: "http://kiwix:8080"
      FRESHRSS_URL: "http://freshrss"
      FRESHRSS_USER: ""               # your FreshRSS username
      FRESHRSS_API_PASSWORD: ""       # your FreshRSS API password (Profile → API password)
      FRESHRSS_MAX_ARTICLES: "10"
      SEARXNG_URL: "http://searxng:8080"
      # LLM — source routing, Kiwix book selection, disambiguation.
      # Point at any Ollama instance reachable from this container
      # (typically a separate GPU machine, not this docker host).
      # Leave LLM_URL blank to run without an LLM: keyword routing
      # still works, everything else falls back to kiwix.
      LLM_URL: ""                     # e.g. http://192.168.1.20:11434
      LLM_MODEL: "qwen3:8b"
      LLM_API_TYPE: "ollama"          # "ollama" (native) or "openai" (OpenAI-compatible)
      LLM_KEEP_ALIVE: "5m"            # how long Ollama keeps the model in VRAM after the last call
      # Semantic routing cache (optional) — reuses routing decisions
      # across rephrasings of the same question, skipping the cold LLM
      # routing call. Requires an embedding model on the LLM backend:
      #   docker exec ollama ollama pull nomic-embed-text
      # Leave EMBEDDING_MODEL blank to disable the feature entirely.
      # See https://github.com/immortalbob/Mnemolis/wiki/Semantic-Routing-Cache
      EMBEDDING_MODEL: ""             # e.g. nomic-embed-text
      EMBEDDING_URL: ""               # blank = same as LLM_URL
      SEMANTIC_ROUTING_THRESHOLD: "0.92"  # cosine-similarity floor; tune only after auditing with explain=true
      SEMANTIC_WARMUP_ENABLED: "true"     # re-embed the persisted routing cache at startup so rephrasings match immediately after a restart
      # Grounded answer synthesis — when a client sets synthesize=true on
      # /search (or the MCP search tool), the local LLM composes a short,
      # grounded answer FROM the retrieved material and returns it in a
      # separate `answer` field, alongside the raw result (never instead of
      # it). Built for the voice pipeline, whose TTS otherwise reads fused
      # headers and article boilerplate aloud. Defaults on (opt-out): it's
      # additive and gated per-request, so it costs nothing for clients
      # that don't ask. Set false to make the per-request flag a no-op.
      # Recommended: LLM_KEEP_ALIVE=30m on a dedicated Beast-class backend
      # so voice synthesis never pays a model load.
      # See https://github.com/immortalbob/Mnemolis/wiki/Answer-Synthesis
      SYNTHESIS_ENABLED: "true"           # master switch; per-request synthesize=true is a no-op while false
      SYNTHESIS_TIMEOUT_SECONDS: "20"     # own budget — a real generation, not a routing pick
      SYNTHESIS_MODEL: ""                 # blank = LLM_MODEL; set to run a larger instruct model just for synthesis
      SYNTHESIS_MIN_INPUT_CHARS: "200"    # results shorter than this skip synthesis (a one-line HA state is already ideal)
      SYNTHESIS_INPUT_BUDGET_CHARS: "6000"    # source material offered to the prompt, apportioned across sections
      SYNTHESIS_MAX_CHARS: "2000"         # answer_style=detailed ceiling; brief is fixed 800
      SYNTHESIS_VOICE_MAX_CHARS: "400"    # answer_style=voice ceiling (≤2 sentences for TTS)
      SYNTHESIS_DIGEST_MAX_CHARS: "3000"  # answer_style=digest output ceiling — preserves many items instead of fusing
      SYNTHESIS_DIGEST_INPUT_BUDGET_CHARS: "12000"  # digest-only input budget; how much wide material reaches the model
      FORECAST_LATITUDE: ""           # your latitude (e.g. 40.7128)
      FORECAST_LONGITUDE: ""          # your longitude (e.g. -74.0060)
      FORECAST_LOCATION_NAME: ""      # e.g. "New York, NY"
      FORECAST_TIMEZONE: ""           # e.g. America/New_York — see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
      # Home Assistant
      HA_URL: ""
      HA_TOKEN: ""
      # Uptime Kuma
      UPTIME_KUMA_URL: ""              # e.g. http://minikuma.local:3001
      UPTIME_KUMA_USERNAME: ""         # your Uptime Kuma username
      UPTIME_KUMA_PASSWORD: ""         # your Uptime Kuma password
      # Background analytics (both optional)
      # Temporal patterns: mines the query log for recurring time-of-day
      # correlations. Adversarial testing: continuously probes routing with
      # synthetic adversarial queries and flags anomalies — off by default
      # because it generates extra background traffic against your
      # LLM/SearXNG/Kiwix backends. Enable when you want the diagnostic.
      TEMPORAL_PATTERN_DETECTION_ENABLED: "true"
      ADVERSARIAL_TEST_ENABLED: "false"       # opt-in; POST /adversarial/trigger runs one cycle on demand regardless
      ADVERSARIAL_TEST_INTERVAL_MINUTES: "60"
      # History source: records the numeric sensors the snapshot path
      # already fetches (temperature, CO2, humidity, power, uptime) into a
      # time series and answers highs/lows/averages/counts/trends. Off by
      # default because it has an on-disk cost (see HISTORY_RETENTION_DAYS
      # and the wiki's History-and-Trends page). The event-count leg reads
      # temporal_events, so counts ("how many times did the door open")
      # need TEMPORAL_PATTERN_DETECTION_ENABLED too. There is no sampling
      # interval to set: ingestion rides inside the HA (5 min) and uptime
      # (2 min) snapshot jobs, consuming the payloads they already fetch.
      HISTORY_ENABLED: "false"
      HISTORY_RETENTION_DAYS: "90"            # ~40 numeric entities ≈ 60–80 MB at 90 days; scales linearly with entity count
      HISTORY_DEVICE_CLASSES: "temperature,humidity,carbon_dioxide,power,energy,illuminance,pressure,battery"
      HISTORY_EXTRA_ENTITIES: ""              # allowlist: unclassified sensors worth recording, comma-separated entity_ids
      HISTORY_EXCLUDE_ENTITIES: ""            # denylist: e.g. noisy button-cell battery sensors you don't want to store
      HISTORY_TREND_MIN_SAMPLES: "12"         # below this, no trend is asserted (says the window's too short instead)
      HISTORY_TREND_MIN_DELTA: "0.1"          # a slope must clear 10% of the window's own value range to count as a trend
      # Security — comma-separated API keys. Blank = no auth (open on your
      # LAN). Set one or more keys to require them on every request.
      API_KEYS: ""
    volumes:
      - mnemolis_data:/app/data
    networks:
      - mnemo-net
    depends_on:
      - kiwix
      - freshrss
      - searxng

  # ---------------------------------------------------------------------------
  # Kiwix — offline knowledge base
  # Web UI: http://your-host:8081
  # Add ZIM files to your data directory, then mount them here.
  # Download ZIMs at: https://library.kiwix.org
  # ---------------------------------------------------------------------------
  kiwix:
    image: ghcr.io/kiwix/kiwix-serve:latest
    container_name: kiwix
    restart: unless-stopped
    ports:
      - "8081:8080"
    volumes:
      - ./data/kiwix:/data   # place your .zim files here
    command: /data
    networks:
      - mnemo-net

  # ---------------------------------------------------------------------------
  # FreshRSS — self-hosted RSS reader
  # Web UI: http://your-host:8082
  # After first run, complete setup at the web UI, then:
  #   1. Administration → Authentication → Allow API access
  #   2. Profile → API password → set a password
  #   3. Add that password to FRESHRSS_API_PASSWORD above
  # ---------------------------------------------------------------------------
  freshrss:
    image: freshrss/freshrss:latest
    container_name: freshrss
    restart: unless-stopped
    ports:
      - "8082:80"
    environment:
      TZ: ""                # your timezone e.g. America/New_York
      CRON_MIN: "*/15"      # feed refresh interval
    volumes:
      - freshrss_data:/var/www/FreshRSS/data
      - freshrss_extensions:/var/www/FreshRSS/extensions
    networks:
      - mnemo-net

  # ---------------------------------------------------------------------------
  # SearXNG — self-hosted web search
  # Web UI: http://your-host:8080
  # Requires custom settings.yml — see searxng/settings.yml in this repo.
  # ---------------------------------------------------------------------------
  searxng:
    image: searxng/searxng:latest
    container_name: searxng
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./searxng:/etc/searxng   # must contain settings.yml
    networks:
      - mnemo-net

  # ---------------------------------------------------------------------------
  # Note: Open-Meteo (weather forecast) is an external API — no container needed.
  # It requires no API key and is the only external call Mnemolis makes.
  # ---------------------------------------------------------------------------

volumes:
  mnemolis_data:
  freshrss_data:
  freshrss_extensions:

networks:
  mnemo-net:
    external: true