docker-compose.yml

# ctx by GottZ — The memory your LLM pretends to have.
# GottZ 4-Way RRF | GottZ Scope Model | GottZ Guard
# https://github.com/GottZ/ctx

services:
  ctx:
    build:
      context: ./go
      dockerfile: Dockerfile
    container_name: ctx
    restart: unless-stopped
    labels:
      - "reversed.host=${CTX_HOSTNAME}"
      - "reversed.port=8080"
      - "reversed.ssl=${CTX_SSL_DOMAIN}"
    environment:
      CONTEXT_DB: ${CONTEXT_DB}
      CONTEXT_DB_USER: ${CONTEXT_DB_USER}
      CONTEXT_DB_PASSWORD: ${CONTEXT_DB_PASSWORD}
      CONTEXT_DB_HOST: db
      CONTEXT_DB_PORT: 5432
      # Sealbox master key (env-only by design — the key that unseals DB rows
      # can never itself live in the DB). _PREV only while a §3.6 rotation
      # sweep is pending. Without this declaration the secrets API answers
      # 503 although .env carries the key (compose gap, found live G17).
      CTX_SECRETS_KEY: ${CTX_SECRETS_KEY:-}
      CTX_SECRETS_KEY_PREV: ${CTX_SECRETS_KEY_PREV:-}
      CTX_EMBED_HOST: ${CTX_EMBED_HOST}
      CTX_EMBED_API_KEY: ${CTX_EMBED_API_KEY:-}
      CTX_EMBED_PROTOCOL: ${CTX_EMBED_PROTOCOL:-ollama}
      CTX_EMBED_MODEL: ${CTX_EMBED_MODEL}
      CTX_EMBED_NUM_CTX: ${CTX_EMBED_NUM_CTX:-0}
      CTX_CHAT_HOST: ${CTX_CHAT_HOST}
      CTX_CHAT_API_KEY: ${CTX_CHAT_API_KEY:-}
      CTX_CHAT_PROTOCOL: ${CTX_CHAT_PROTOCOL:-ollama}
      CTX_CHAT_MODEL: ${CTX_CHAT_MODEL}
      CTX_CHAT_THINK: ${CTX_CHAT_THINK:-false}
      CTX_CHAT_NUM_CTX: ${CTX_CHAT_NUM_CTX:-0}
      CTX_CHAT_FALLBACK_HOST: ${CTX_CHAT_FALLBACK_HOST:-}
      CTX_CHAT_FALLBACK_API_KEY: ${CTX_CHAT_FALLBACK_API_KEY:-}
      CTX_CHAT_FALLBACK_PROTOCOL: ${CTX_CHAT_FALLBACK_PROTOCOL:-openai}
      CTX_CHAT_FALLBACK_TIMEOUT: ${CTX_CHAT_FALLBACK_TIMEOUT:-420}
      CTX_DREAM_ENABLED: ${CTX_DREAM_ENABLED:-false}
      CTX_DREAM_HOST: ${CTX_DREAM_HOST:-}
      CTX_DREAM_API_KEY: ${CTX_DREAM_API_KEY:-}
      CTX_DREAM_PROTOCOL: ${CTX_DREAM_PROTOCOL:-ollama}
      CTX_DREAM_MODEL: ${CTX_DREAM_MODEL:-}
      CTX_DREAM_NUM_CTX: ${CTX_DREAM_NUM_CTX:-0}
      CTX_DREAM_THINK: ${CTX_DREAM_THINK:-}
      # CTX_DREAM_EMBED_* (separate dream-embedding endpoint) is no longer wired
      # here: live it was identical to CTX_EMBED_*, and the backend pool (053)
      # dedups an identical tuple onto the llama-embed row's dream-embed role.
      # To run a SEPARATE dream-embed backend, create a pool row instead
      # (`ctx backends`, role dream-embed); config.go still reads these vars for
      # the one-time bootstrap of an empty context_backends if you re-add them.
      # Reranker (post-RRF re-score). Default ON since Wave 3.5: the surface-gold
      # counter-probe showed the cross-encoder earns its keep on real-user
      # queries (nDCG@10 +0.164, MRR +0.169 on judge-annotated answer gold)
      # while blend 0.5 keeps it neutral on latent gold — graph+ce-bw0.5 is the
      # best arm on BOTH gold sets. The ~80-90s/query path stays proxy-safe via
      # the query body-heartbeat. Disable with CTX_RERANK_ENABLED=false.
      # RERANK_HOST dispatches: empty => LLM-as-judge on the chat model; set =>
      # local cross-encoder sidecar (service below). BLEND_WEIGHT/MAX_DOCS are
      # cross-encoder sweep knobs (quality, not latency — CPU rerank ~1s/doc
      # is intentionally not a constraint; the client timeout is sized for 50).
      CTX_RERANK_ENABLED: ${CTX_RERANK_ENABLED:-true}
      CTX_RERANK_HOST: ${CTX_RERANK_HOST:-http://ctx-rerank:8082}
      CTX_RERANK_API_KEY: ${CTX_RERANK_API_KEY:-}
      CTX_RERANK_MODEL: ${CTX_RERANK_MODEL:-bge-reranker-v2-m3}
      CTX_RERANK_MAX_DOCS: ${CTX_RERANK_MAX_DOCS:-50}
      # BLEND_WEIGHT default 0.5 (not 1.0): the Wave-3 sweep showed pure
      # cross-encoder (bw1.0) discards the RRF prior and re-ranks latent neighbors
      # down — and as final arbiter over graph-injected neighbors it is destructive
      # (R@10 0.715->0.571). bw0.5 keeps RRF/graph and is the only setting that
      # didn't hurt (graph+ce-bw0.5 R@20 0.811, best overall).
      CTX_RERANK_BLEND_WEIGHT: ${CTX_RERANK_BLEND_WEIGHT:-0.5}
      # Dream-graph expansion (Wave 1). Post-RRF stage that 1-hop-expands the top
      # RRF seeds along the positive Dream link types. Default ON since Wave 3: the
      # only arm that moves the recall ceiling (R@20 0.763 vs 0.625 for every
      # reorderer; a reorderer structurally cannot surface what RRF didn't return),
      # ~0s deterministic = zero latency cost. Caveat: the +31% R@10 magnitude is
      # partly circular (the eval gold is derived from these same Dream links);
      # the non-circular floor (graph surfaces link-gold RRF never finds) is what
      # justifies ON. Every value is a runtime knob.
      CTX_GRAPH_EXPAND_ENABLED: ${CTX_GRAPH_EXPAND_ENABLED:-true}
      CTX_GRAPH_EXPAND_DIRECTED: ${CTX_GRAPH_EXPAND_DIRECTED:-true}
      CTX_GRAPH_EXPAND_HOP_DEPTH: ${CTX_GRAPH_EXPAND_HOP_DEPTH:-1}
      CTX_GRAPH_EXPAND_SEED_COUNT: ${CTX_GRAPH_EXPAND_SEED_COUNT:-5}
      CTX_GRAPH_EXPAND_SEED_SCORE_FLOOR: ${CTX_GRAPH_EXPAND_SEED_SCORE_FLOOR:-0.5}
      CTX_GRAPH_EXPAND_PER_SEED_CAP: ${CTX_GRAPH_EXPAND_PER_SEED_CAP:-3}
      CTX_GRAPH_EXPAND_MAX_INJECTED: ${CTX_GRAPH_EXPAND_MAX_INJECTED:-10}
      CTX_GRAPH_EXPAND_MIN_CONFIDENCE: ${CTX_GRAPH_EXPAND_MIN_CONFIDENCE:-0.75}
      CTX_GRAPH_EXPAND_MIN_CONFIDENCE_RECURRENT: ${CTX_GRAPH_EXPAND_MIN_CONFIDENCE_RECURRENT:-0.8}
      CTX_GRAPH_EXPAND_BOOST_WEIGHT: ${CTX_GRAPH_EXPAND_BOOST_WEIGHT:-0.20}
      CTX_GRAPH_EXPAND_HUB_DAMPING: ${CTX_GRAPH_EXPAND_HUB_DAMPING:-true}
      CTX_GRAPH_EXPAND_WEIGHT_TOPICAL: ${CTX_GRAPH_EXPAND_WEIGHT_TOPICAL:-0.5}
      CTX_GRAPH_EXPAND_WEIGHT_FACTUAL: ${CTX_GRAPH_EXPAND_WEIGHT_FACTUAL:-0.9}
      CTX_GRAPH_EXPAND_WEIGHT_CAUSAL: ${CTX_GRAPH_EXPAND_WEIGHT_CAUSAL:-0.9}
      CTX_GRAPH_EXPAND_WEIGHT_RECURRENT: ${CTX_GRAPH_EXPAND_WEIGHT_RECURRENT:-1.0}
      CTX_GRAPH_EXPAND_NEW_PLACEMENT_FRAC: ${CTX_GRAPH_EXPAND_NEW_PLACEMENT_FRAC:-0.6}
      # Graph overview "landkarte" (F5-W6): the Louvain cluster-supergraph rebuild
      # job (gonum, offline in the scheduler) + GET /api/graph/overview. ENABLED
      # gates BOTH the job and the endpoint (off ⇒ 404). REBUILD_INTERVAL takes
      # seconds (default 6h); RESOLUTION is the Louvain γ (higher ⇒ more, smaller
      # clusters). First build runs at boot when ENABLED and the tables are empty.
      CTX_GRAPH_OVERVIEW_ENABLED: ${CTX_GRAPH_OVERVIEW_ENABLED:-false}
      CTX_GRAPH_OVERVIEW_REBUILD_INTERVAL: ${CTX_GRAPH_OVERVIEW_REBUILD_INTERVAL:-21600}
      CTX_GRAPH_OVERVIEW_RESOLUTION: ${CTX_GRAPH_OVERVIEW_RESOLUTION:-1.0}
      CTX_RATE_LIMIT_WRITE: ${CTX_RATE_LIMIT_WRITE:-100}
      CTX_RATE_LIMIT_READ: ${CTX_RATE_LIMIT_READ:-0}
      CTX_TIMEZONE: ${CTX_TIMEZONE:-}
      CTX_SCORE_THRESHOLD: ${CTX_SCORE_THRESHOLD:-0.001}
      CTX_CONFIDENT_THRESHOLD: ${CTX_CONFIDENT_THRESHOLD:-0.008}
      # Scheduler ReadScopes (comma-separated). Background guard/digest/dream
      # operate on these scopes. Default = v1.x backwards-compat. v2.0.0 M045
      # dropped chk_scope, so any scope name is valid (no schema validation).
      CTX_READ_SCOPES: ${CTX_READ_SCOPES:-private,shared,work}
      # Age after which the background janitor NULLs context_llm_log prompt/
      # response bodies (telemetry row survives — Body-NULLing, not a chunk
      # drop; audit stays lossless). 0 = keep bodies forever (no retention).
      CTX_LLMLOG_RETENTION_DAYS: ${CTX_LLMLOG_RETENTION_DAYS:-90}
      # Web-chat harness (F6). ENABLED gates POST /api/chat/stream + the session
      # routes (off ⇒ 404). The integer budgets cap one turn; CONCURRENT_TURNS
      # is the per-home_scope semaphore (429 above it) that bounds turn frequency
      # on the single llama.cpp slot. SESSION_RETENTION takes a duration suffix
      # (h/d/w/m/y); 0 = keep sessions forever (the janitor stays off).
      CTX_WEBCHAT_ENABLED: ${CTX_WEBCHAT_ENABLED:-true}
      CTX_WEBCHAT_MAX_ITERATIONS: ${CTX_WEBCHAT_MAX_ITERATIONS:-6}
      CTX_WEBCHAT_MAX_TOKENS: ${CTX_WEBCHAT_MAX_TOKENS:-2048}
      CTX_WEBCHAT_COMPLETION_BUDGET: ${CTX_WEBCHAT_COMPLETION_BUDGET:-8192}
      CTX_WEBCHAT_TOOL_RESULT_MAX_CHARS: ${CTX_WEBCHAT_TOOL_RESULT_MAX_CHARS:-8000}
      CTX_WEBCHAT_HISTORY_BUDGET_CHARS: ${CTX_WEBCHAT_HISTORY_BUDGET_CHARS:-60000}
      CTX_WEBCHAT_LLM_TIMEOUT: ${CTX_WEBCHAT_LLM_TIMEOUT:-900}
      CTX_WEBCHAT_CONCURRENT_TURNS: ${CTX_WEBCHAT_CONCURRENT_TURNS:-1}
      CTX_WEBCHAT_SESSION_RETENTION: ${CTX_WEBCHAT_SESSION_RETENTION:-0}
      LISTEN_ADDR: ":8080"
    networks:
      - n8nintern
    depends_on:
      db:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "/ctx", "-health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 15s
    security_opt:
      - "no-new-privileges:true"
    cap_drop:
      - ALL
    read_only: true
    deploy:
      resources:
        limits:
          memory: 256M
        reservations:
          memory: 32M
    logging:
      options:
        max-size: "50m"
        max-file: "3"

  db:
    build: ./db-image
    image: pgvector-timescaledb:pg18
    restart: unless-stopped
    networks:
      - n8nintern
    environment:
      POSTGRES_DB:
      POSTGRES_USER:
      POSTGRES_PASSWORD:
      CONTEXT_DB: ${CONTEXT_DB}
      CONTEXT_DB_USER: ${CONTEXT_DB_USER}
      CONTEXT_DB_PASSWORD: ${CONTEXT_DB_PASSWORD}
    volumes:
      - ./db:/var/lib/postgresql
      - ./init-data.sh:/docker-entrypoint-initdb.d/init-data.sh
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -h localhost -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 10

  # Optional: llama.cpp CPU-only inference sidecar.
  # Useful for Dream embedding on CPU (frees GPU for query-path).
  # Mount your GGUF models into /models. Route Dream embedding here via a pool
  # row (`ctx backends`, role dream-embed, base_url http://llama-embed:8081,
  # protocol openai) — not env vars (see the dream-embed note above).
  #
  # llama-embed:
  #   image: ghcr.io/ggml-org/llama.cpp:server
  #   container_name: llama-embed
  #   restart: unless-stopped
  #   volumes:
  #     - /opt/models:/models:ro
  #   command: >
  #     --model /models/Qwen3-Embedding-8B-Q4_K_M.gguf
  #     --embedding
  #     --pooling last
  #     --port 8081
  #     --ctx-size 2048
  #     --n-gpu-layers 0
  #   networks:
  #     - n8nintern
  #   healthcheck:
  #     test: ["CMD", "curl", "-sf", "http://localhost:8081/health"]
  #     interval: 30s
  #     timeout: 5s
  #     retries: 3
  #     start_period: 15s

  # llama.cpp CPU-only cross-encoder reranker sidecar (Wave 2, default-on
  # since Wave 3.5 — see the CTX_RERANK_* block above). bge-reranker-v2-m3
  # (XLM-RoBERTa, multilingual de+en) over the cohere-style /v1/rerank
  # endpoint; ctx reaches it at http://ctx-rerank:8082; all-local, $0. The
  # real oversized-input guard is ctx's app-side per-doc clamp
  # (rrf.RerankCrossEncoderContentLimit, ~2048 chars): a single query+doc
  # pair longer than the batch kills the server PROCESS (not a graceful
  # error), so ctx-size/batch must stay >= that clamp in tokens.
  ctx-rerank:
    image: ghcr.io/ggml-org/llama.cpp:server
    container_name: ctx-rerank
    restart: unless-stopped
    mem_limit: 4g
    volumes:
      - /opt/models:/models:ro
    # --reranking implies embedding pooling internally; --pooling rank is the
    # documented activation. KEY: llama.cpp splits --ctx-size across --parallel
    # slots, so per-slot context = 4096/4 = 1024 tokens — must exceed the
    # longest query+doc pair (~750 tokens for a 2048-char German doc; a
    # 2048/4=512 slot rejected pairs with HTTP 400 exceed_context_size).
    # --batch (compute buffer, NOT divided) stays at 2048 to bound memory; an
    # 8192 batch OOM-killed at 2g. --threads 12 = all host cores. CPU rerank
    # costs ~0.85s/doc — the query body-heartbeat keeps reverse proxies from
    # timing out on the ~80-90s path.
    command: >
      --model /models/bge-reranker-v2-m3-Q8_0.gguf
      --reranking
      --pooling rank
      --port 8082
      --ctx-size 4096
      --batch-size 2048
      --ubatch-size 2048
      --parallel 4
      --threads 12
      --n-gpu-layers 0
    networks:
      - n8nintern
    healthcheck:
      test: ["CMD", "curl", "-sf", "http://localhost:8082/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 30s

  # llama.cpp CPU emergency fallback for the query path (synthesis only).
  # Engaged by ctx via CTX_CHAT_FALLBACK_HOST when the primary GPU chat
  # backend is unreachable at transport level (host down/Gaming-Mode) — never
  # on HTTP errors or slow responses. Same MTP-GGUF as production → identical
  # answer quality at CPU speed (~2.25 tok/s tg, 74 tok/s pp ⇒ a 500-token
  # synthesis takes 4.5-5.5 min; the response-body heartbeat keeps buffering
  # reverse proxies alive). ctx-size 32k suffices: the openai path never sends
  # num_ctx, query prompts are ≤10k tokens. --threads 10 leaves headroom for
  # PG + ctx on the 12-thread host. Idle cost ≈ 0 (mmap'd weights, no compute).
  llama-cpu:
    image: ghcr.io/ggml-org/llama.cpp:server
    container_name: llama-cpu
    restart: unless-stopped
    volumes:
      - /opt/models:/models:ro
    command: >
      --model /models/Qwen3.6-27B-MTP-Q4_K_M.gguf
      --host 0.0.0.0
      --port 8090
      --ctx-size 32768
      --n-gpu-layers 0
      --threads 10
      --jinja
      --reasoning off
      --top-k 20
      --top-p 0.95
      --min-p 0
      --presence-penalty 1.5
    networks:
      - n8nintern
    healthcheck:
      test: ["CMD", "curl", "-sf", "http://localhost:8090/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 180s

networks:
  n8nintern:
    name: n8nintern