.env.example

# ── Engraphis Configuration ──────────────────────────────────────────
# Copy this file to .env and edit. All values are optional — sensible defaults
# are applied in engraphis/config.py.

# ── Server ──────────────────────────────────────────────────────────────────
ENGRAPHIS_HOST=127.0.0.1
ENGRAPHIS_PORT=8700
# Clients point at the server via this base URL (derived from host/port):
#   export ENGRAPHIS_BASE_URL="http://127.0.0.1:8700"

# Optional bearer token for the REST API. If set, all /memory routes require
# the header  Authorization: Bearer <token>.  Leave empty to disable auth
# (recommended only for local, single-user, loopback-bound use).
ENGRAPHIS_API_TOKEN=

# ── Storage ─────────────────────────────────────────────────────────────────
# SQLite database file path. Defaults to ./engraphis.db in the project dir.
ENGRAPHIS_DB_PATH=./engraphis.db

# ── Encryption at rest (optional; SQLCipher / AES-256) ──────────────────────
# Transparently encrypt the ENTIRE memory database file. OFF by default. Needs the extra:
#     pip install "engraphis[encryption]"
# Generate a strong key:  python -c "import secrets; print(secrets.token_hex(32))"
# A 64-hex value is used as a raw 32-byte key; anything else is treated as a passphrase.
# WARNING: lose this key = lose the data (no recovery). In production, inject it from a
# secrets manager (or ENGRAPHIS_DB_KEY_FILE), NOT from this file. An existing PLAINTEXT
# db cannot just be keyed — migrate it (dump → import into a fresh keyed db).
# ENGRAPHIS_DB_KEY=
# ...or read the key from a file (e.g. a mounted docker/k8s secret):
# ENGRAPHIS_DB_KEY_FILE=/run/secrets/engraphis_db_key

# ── Embeddings ──────────────────────────────────────────────────────────────
# Local sentence-transformers model (downloaded on first run, ~80-400 MB).
ENGRAPHIS_EMBED_MODEL=sentence-transformers/all-MiniLM-L6-v2
# Embedding dimension is auto-detected from the model. Override only if needed.
# ENGRAPHIS_EMBED_DIM=384

# ── LLM (external, you choose the provider) ─────────────────────────────────
# Provider: openai | anthropic | google | openrouter | custom
# ── v2 write-path fact extraction (optional) ─────────────────────────────────
# "none" (default): store text as given. "chunk": deterministic offline chunks.
# "llm": free-form fact extraction. "llm_structured": schema-validated typed facts,
# entities, relations, keywords, and confidence using the LLM settings below.
ENGRAPHIS_EXTRACTOR=none

# ── Knowledge-graph extraction (powers the dashboard Graph tab) ──────────────
# "regex" (default): dependency-free heuristic NER runs on every ingest so the Graph tab
# has nodes — no API key, safe offline. "none": disable heuristic text extraction.
# Validated entity/relation metadata from "llm_structured" still feeds the graph
# automatically. Existing memories are backfilled when a workspace graph first opens.
ENGRAPHIS_GRAPH_EXTRACTOR=regex

# Optional host-LLM retention supervision. "none" preserves the deterministic write path;
# "llm" sends a bounded excerpt to the configured provider for an advisory
# ephemeral/normal/critical signal. Writes are never discarded.
ENGRAPHIS_RETENTION_SUPERVISOR=none

# Optional local resource adapters:
# ENGRAPHIS_WHISPER_MODEL=/absolute/path/to/local-whisper-model
# ENGRAPHIS_WHISPER_DEVICE=auto
# ENGRAPHIS_WHISPER_COMPUTE_TYPE=default
# ENGRAPHIS_POSTGRES_CONNECT_TIMEOUT=10
# ENGRAPHIS_POSTGRES_STATEMENT_TIMEOUT_MS=30000
# ENGRAPHIS_POSTGRES_DSN=postgresql://user:password@localhost/db

# Optional read-only team graph/recall server (`engraphis-graph-server`, port 8720).
# Required when binding that server beyond loopback; falls back to ENGRAPHIS_API_TOKEN.
# ENGRAPHIS_GRAPH_TOKEN=
# ENGRAPHIS_GRAPH_HOST=127.0.0.1
# ENGRAPHIS_GRAPH_PORT=8720

# ── Reverse proxy (TLS termination) ─────────────────────────────────────────
# When behind a proxy that terminates TLS (Railway/Fly/nginx), trust its
# X-Forwarded-Proto/-For headers so request.url.scheme is https and the session
# cookie's Secure flag is set. Default "127.0.0.1" trusts NO external forwarded
# headers (safe when the port is published directly). Behind a TLS-terminating proxy,
# set this to the proxy's IP/CIDR (or "*" if the container is reachable ONLY via that
# trusted proxy) to enable https scheme detection + the session cookie's Secure flag.
# Trusting "*" on a directly published port lets clients spoof X-Forwarded-For
# (rate-limit bypass / forged audit IP).
# ENGRAPHIS_FORWARDED_ALLOW_IPS=127.0.0.1

ENGRAPHIS_LLM_PROVIDER=openai
# Model name (provider-specific):
#   openai:      gpt-4o-mini, gpt-4o, gpt-4.1-mini, o4-mini ...
#   anthropic:   claude-3-5-haiku-20241022, claude-3-5-sonnet-20241022 ...
#   google:      gemini-1.5-flash, gemini-2.0-flash ...
#   openrouter:  anthropic/claude-3.5-sonnet, openai/gpt-4o-mini ...
#   custom:      any model name your OpenAI-compatible endpoint accepts
ENGRAPHIS_LLM_MODEL=gpt-4o-mini
# API key for chat/synthesis, llm/llm_structured extraction, and structured consolidation:
ENGRAPHIS_LLM_API_KEY=sk-your-key-here
# For openrouter / custom: the base URL of the OpenAI-compatible endpoint.
#   openrouter: https://openrouter.ai/api/v1
#   custom:     https://your-endpoint/v1
# ENGRAPHIS_LLM_BASE_URL=https://openrouter.ai/api/v1
# Optional: extra headers (JSON string) for custom providers.
# ENGRAPHIS_LLM_EXTRA_HEADERS={"HTTP-Referer":"https://myapp.com","X-Title":"engraphis"}

# ── Background Consolidation Loop ───────────────────────────────────────────
# Interval (seconds) between background thought-synthesis + reweight cycles.
# Set to 0 to disable the background loop.
ENGRAPHIS_LOOP_INTERVAL=60
# Max memories to consider per namespace per cycle.
ENGRAPHIS_LOOP_TOP_K=20
# Decay half-life in days (Ebbinghaus). Higher = memories persist longer.
ENGRAPHIS_DECAY_HALFLIFE_DAYS=7

# ── License & Team mode (Pro / Team) ────────────────────────────────────────
# Engraphis core is free forever. A signed license key unlocks Pro features
# (analytics, HTML/compliance export, automation, cloud sync) and Team mode
# (multi-user dashboard: per-user logins, roles admin/member/viewer, seats,
# team audit log). A key activates via ANY of: this variable, a one-line file at
# $ENGRAPHIS_STATE_DIR/license.key, or the dashboard's license dialog. Verified offline.
# ENGRAPHIS_LICENSE_KEY=ENGR1.xxxxx.yyyyy

# Team mode: per-user logins + roles on the dashboard (engraphis-dashboard binary).
# ON by default. Set ENGRAPHIS_TEAM_MODE=0 to disable (single-user mode). Requires a
# Team license to add seats beyond the first admin; first visit creates the admin.
# ENGRAPHIS_TEAM_MODE=0

# Public URL of your dashboard, included as a sign-in link in the "you've been
# added to a team" notification email sent when an admin adds a member. Without
# it, the email just tells the new member to ask their admin for the address.
# ENGRAPHIS_DASHBOARD_URL=https://dash.yourcompany.com

# "Add member" invite emails: if THIS instance has its own ENGRAPHIS_RESEND_API_KEY
# or ENGRAPHIS_SMTP_* configured (see the email-delivery section below), it sends
# invites directly from your own address. Otherwise it automatically falls back to
# relaying the invite through the VENDOR's mail provider at your Team license's
# relay (ENGRAPHIS_RELAY_URL), so self-hosting still "just works" with zero email
# setup — no code or extra config needed on your end for the fallback itself.

# Vendor-side only: cap on invite emails relayed per license key per day, so one
# key (including a free self-serve trial key — see start-trial below) can't be
# used to spam an open relay through the vendor's account. Default 10 — high
# enough for a real team onboarding, low enough to bound abuse of a free key.
# ENGRAPHIS_TEAM_INVITE_DAILY_CAP=10

# Where 402 responses / upgrade banners send users. Set to your real checkout at launch.
# ENGRAPHIS_PRO_UPGRADE_URL=https://buy.polar.sh/<your-pro-product>
# ENGRAPHIS_TEAM_UPGRADE_URL=https://buy.polar.sh/<your-team-product>
# (legacy single-URL alias, still honored): ENGRAPHIS_UPGRADE_URL=

# Persistent state dir (license.key, trial.json, machine_id, lease, relay/registry DB).
# In Docker this is /data/.engraphis (on the volume) so keys/trial/revocations survive
# redeploys. Locally it defaults to ~/.engraphis.
# ENGRAPHIS_STATE_DIR=/data/.engraphis

# ── Cloud sync — automatic (Pro / Team) ─────────────────────────────────────
# Cloud sync always works from the dashboard "Sync now" button and the CLI
# (python -m scripts.sync). In ADDITION, the dashboard can sync in the background on a
# cadence: enable it from Settings → Cloud Sync ("Sync automatically every N min"). It is
# opt-in (off by default), Pro/Team-gated, and the loop no-ops without a licensed key.
# The toggle + cadence persist to autosync.json next to the DB. See docs/SYNC.md.
#
# Kill switch for the in-process background loop (the button/CLI still work). Set to 0 if
# you drive sync purely from cron/pm2 and don't want the dashboard process syncing itself.
# ENGRAPHIS_AUTOSYNC_LOOP=1
# Override where the auto-sync policy is stored (default: next to ENGRAPHIS_DB_PATH).
# ENGRAPHIS_AUTOSYNC_STATE=/data/.engraphis/autosync.json

# ── Commercial / vendor (ONLY if you SELL Engraphis — not needed to self-host) ──
# Server-side of cloud enforcement + fulfillment. Set these on your vendor host.
#
# Vendor Ed25519 signing seed — signs issued license KEYS and short-lived LEASES.
# 64-char hex inline (how Railway/Fly set it) OR a path to a file with that hex.
# MUST correspond to the pinned public key in engraphis/licensing.py (_VENDOR_PUBKEY_HEX),
# else every key you issue fails to verify on clients. Verify with:
#   python -m scripts.license_admin verify-key
# ENGRAPHIS_VENDOR_SIGNING_KEY=<64-char-hex-seed or /path/to/vendor_signing.key>
#
# Registry + relay + registrations DB (issued keys, revocations, sync bundles, device
# seats). Put it on a PERSISTENT volume or revoked keys un-revoke on restart.
# ENGRAPHIS_RELAY_DB=/data/.engraphis/relay.db
#
# Lease lifetime (hours). Lower = faster revocation takes effect, more phone-home. Def 72.
# ENGRAPHIS_LEASE_TTL_HOURS=72
#
# Polar billing webhook (auto-fulfill: order.paid -> signed key -> email).
# POLAR_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxxxxxx
# POLAR_ORGANIZATION_ID=            # optional: verify the webhook's org matches
#
# Outbound email (license-key delivery AND team invite notifications). Resend
# API (preferred) OR SMTP.
# ENGRAPHIS_RESEND_API_KEY=re_xxxxxxxxxxxx
# ENGRAPHIS_SMTP_FROM=licenses@yourdomain.com
# ENGRAPHIS_SMTP_HOST=            # alternative to Resend
# ENGRAPHIS_SMTP_PORT=587
# ENGRAPHIS_SMTP_USER=
# ENGRAPHIS_SMTP_PASSWORD=
#
# ── Client side (end-user machines) ─────────────────────────────────────────
# Paid keys require a revocable, machine-bound lease from the managed service. The
# built-in default is https://team.engraphis.com; override only for a different vendor
# deployment. Free-tier use remains local and does not require the service.
# ENGRAPHIS_CLOUD_URL=https://team.engraphis.com

# Server-side license enforcement (vendor/fulfillment server only): when set, every key
# minted by the Polar webhook carries a signed enforce:"cloud" claim + this URL, and the
# client requires a live lease from it (revocable, seat-counted, useless offline).
# Set this to the canonical managed-service URL for newly issued keys. Older keys carrying
# the retired Railway hostname are migrated by the client without changing their signature.
# ENGRAPHIS_KEY_CLOUD_URL=https://team.engraphis.com