.env.example

# ── Engraphis Configuration ──────────────────────────────────────────
# Copy this file to .env and edit only the settings you need. Commented values preserve
# the platform-aware defaults in engraphis/config.py; hosted deployments additionally
# require the authentication and public-URL settings described below.

# ── Server ──────────────────────────────────────────────────────────────────
ENGRAPHIS_HOST=127.0.0.1
ENGRAPHIS_PORT=8700
# The public package supports only customer mode: dashboard, memory, and managed-service
# clients. Hosted vendor, relay, compute, and worker roles are not distributed here.
ENGRAPHIS_SERVICE_MODE=customer
# The dashboard base URL is derived from ENGRAPHIS_HOST:ENGRAPHIS_PORT.
# Set ENGRAPHIS_DASHBOARD_URL for a canonical public HTTPS URL behind a reverse proxy;
# it extends the dashboard MCP origin allow-list and drives legacy-inspector redirects.
# ENGRAPHIS_DASHBOARD_URL=https://engraphis.example.com
# Docker Compose stays loopback-only by default. For LAN MCP-over-HTTP, set a strong
# ENGRAPHIS_API_TOKEN, then run the token-required `docker-compose.lan.yml` overlay (Docker
# Compose v2.24.4+). Set this to the exact client URL:
# ENGRAPHIS_API_TOKEN=<a-long-random-secret>
# ENGRAPHIS_DASHBOARD_URL=http://192.168.10.151:8700
# Behind Traefik, use its LAN hostname instead:
# ENGRAPHIS_DASHBOARD_URL=http://engraphis.local

# Update reminder. It is OFF by default, so a local installation makes no update-related
# network request. Set this to 1 to check for a newer Engraphis release once a day and
# surface it in the dashboard banner, startup log, and over MCP. The check is cached
# and fail-silent.
# ENGRAPHIS_UPDATE_CHECK=1
# Override the release source. Default: the GitHub releases/latest API for the project
# repo. Accepts any HTTPS endpoint returning a GitHub-release, PyPI, or
# {"version": "...", "url": "..."} JSON payload.
# ENGRAPHIS_UPDATE_URL=
# Point the default GitHub source at a different owner/repo (ignored when
# ENGRAPHIS_UPDATE_URL is set). Default: Coding-Dev-Tools/engraphis.
# ENGRAPHIS_UPDATE_REPO=Coding-Dev-Tools/engraphis
# Which extras the self-updater installs on top of the base package. The installer
# cannot see which extras the current install selected, so it defaults to the safe
# superset `engraphis[all]`; set a comma-separated list (e.g. `server,mcp`) to pin
# a smaller surface, or `none` for the base package only.
# ENGRAPHIS_UPDATE_EXTRAS=

# Optional local API bearer. If set, supported protected routes accept
# Authorization: Bearer <token>. Use a strong, independently revocable value and do not
# reuse a hosted Engraphis credential here.
ENGRAPHIS_API_TOKEN=

# ── Storage ─────────────────────────────────────────────────────────────────
# SQLite database override. Leave commented to use <repo>/engraphis.db from a source
# checkout or the platform user-data directory from an installed wheel.
# ENGRAPHIS_DB_PATH=./engraphis.db

# Code indexing accepts roots under the working, home, or temporary directories by
# default. Set this to replace those defaults with an explicit absolute-path allow-list.
# Separate paths with ";" on Windows or ":" on macOS/Linux.
# ENGRAPHIS_INDEX_ROOTS=/srv/engraphis/repos:/mnt/code
# The dashboard and REST /api/code/index route accept paths only below this one root.
# An explicit root (or the ENGRAPHIS_INDEX_ROOTS fallback entry) must be absolute.
# Defaults to the first ENGRAPHIS_INDEX_ROOTS entry, or the current directory; an
# explicit HTTP root is included in the engine-approved set.
# ENGRAPHIS_HTTP_INDEX_ROOT=/srv/engraphis/repos

# ── 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
# Optional immutable Hugging Face commit for the embedding model. Required for remote
# models when ENGRAPHIS_REQUIRE_IMMUTABLE_MODELS=1; local:/paths remain permitted.
# ENGRAPHIS_EMBED_REVISION=<lowercase 40-character model commit>
# Reject mutable remote embedding, reranker, and chunk-tokenizer tags before loading. Off by default.
# ENGRAPHIS_REQUIRE_IMMUTABLE_MODELS=0
# Embedding dimension is auto-detected from the model. Override only if needed.
# ENGRAPHIS_EMBED_DIM=384
# Vector index backend for server entrypoints: "auto" (default; use sqlite-vec when
# engraphis[vector] is installed and compatible, otherwise NumPy), "sqlite-vec"
# (require native exact-KNN acceleration), or "numpy" (force the reference index).
# ENGRAPHIS_VECTOR_BACKEND=auto

# ── LLM (external, you choose the provider) ─────────────────────────────────
# Provider: openai | anthropic | google | openrouter | custom
# Copy-ready provider setups and endpoint requirements: docs/LLM_PROVIDERS.md
# Codex subscription users: connect Codex to this installation over MCP; the subscription
# path does not use ENGRAPHIS_LLM_PROVIDER or an Engraphis LLM API key.
# ── 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, and keywords using the LLM settings below.
ENGRAPHIS_EXTRACTOR=none
# OFF by default (opt-in). While ON, a successful dashboard connection test enables
# llm_structured automatically. Use the Settings "LLM extraction" On/Off button to turn
# it on or off; it updates the live engine immediately and persists this flag plus
# ENGRAPHIS_EXTRACTOR only when the project .env is writable. Explicit deployment
# environment variables remain authoritative after restart.
ENGRAPHIS_LLM_AUTO_EXTRACT=0

# ── 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
# A remote retention supervisor is advisory: without this opt-in, its "critical"
# recommendations keep normal retention strength. Set 1 to honor critical signals.
# ENGRAPHIS_ALLOW_AUTOMATIC_CRITICAL_RETENTION=0

# 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 local 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

# Standalone MCP-over-HTTP server (`engraphis-mcp-http`). Loopback-only by default;
# any non-loopback bind (via these or ENGRAPHIS_HOST) requires ENGRAPHIS_API_TOKEN.
# ENGRAPHIS_HTTP_HOST=127.0.0.1
# ENGRAPHIS_HTTP_PORT=8711
# ENGRAPHIS_HTTP_TRANSPORT=streamable-http

# When running under Docker (auto-detected via /.dockerenv), the self-updater skips
# in-place pip upgrades and prints a manual reinstall hint instead.
# ENGRAPHIS_DOCKER=0

# Docker Compose host port mapping override for the dashboard (default 8700).
# ENGRAPHIS_COMPOSE_PORT=8700

# ── 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. The default trusts no 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

# ── Response security headers ───────────────────────────────────────────────
# Every entrypoint sends CSP, X-Frame-Options, X-Content-Type-Options,
# Referrer-Policy, Permissions-Policy, and (over HTTPS only) HSTS. Both variables
# REPLACE the built-in value wholesale; set either to an EMPTY string to omit that
# header entirely, which is what you want when a fronting proxy sets its own.
# The default CSP is strict same-origin and contains no unsafe-inline; dashboard CSS,
# JavaScript, and vendored libraries are served under /static.
# Quote the values because both contain characters a shell would otherwise split on.
# ENGRAPHIS_CSP="default-src 'self'; frame-ancestors 'none'"   # replace the policy
# ENGRAPHIS_CSP=""                                             # send no CSP at all
# ENGRAPHIS_HSTS="max-age=31536000; includeSubDomains"

# Codex subscription users can use the local MCP connection documented in README.md and
# docs/AGENT_CONNECT.md; leave the optional external LLM settings below disabled unless
# Engraphis itself must call a separate provider.
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.
# Leave unset until you explicitly choose a provider and enable an LLM-backed feature.
# ENGRAPHIS_LLM_API_KEY=<your-api-key>
# 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"}

# ── Hosted Pro / Team customer client ───────────────────────────────────────
# Cloud Sync, Analytics, Automation, Auto Dreaming, Auto Consolidation, and Team
# administration run on the official private service. These variables configure only the
# public customer client; no setting turns this package into a relay, compute worker, license
# issuer, or Team identity server.
# ENGRAPHIS_CLOUD_CONTROL_URL=https://api.engraphis.com
# ENGRAPHIS_CLOUD_COMPUTE_URL=https://compute.engraphis.com
# ENGRAPHIS_CLOUD_ORGANIZATION_ID=org_replace_me

# Prefer the owner-only ~/.engraphis/cloud_session.json written by `engraphis connect`:
#
#   engraphis connect --preflight  # validate endpoints/storage; never reads or sends a token
#   engraphis connect --token engr_ct_...        # the command your account portal shows
#   printf %s "$TOKEN" | engraphis connect --token -   # keep the token out of shell history
#
# That is the supported way to connect a client. It redeems the one-time connect token, saves
# the rotating refresh credential with 0600 permissions, and keeps it rotated afterwards, so
# none of the variables below are needed on an interactive machine. Set
# ENGRAPHIS_CLOUD_COMPUTE_URL (or pass --compute-url) only if your account portal shows a
# compute endpoint different from the default. See docs/AGENT_CONNECT.md.
#
# For non-interactive deployments a refresh credential may be injected as a bootstrap secret.
# It rotates on use; the owner-only saved replacement takes precedence afterward, even while
# the environment variable remains set. Never commit it. Bind environment-only bootstrap
# credentials to the subject assigned at onboarding (device or member). A short-lived access
# token is supported for jobs.
# ENGRAPHIS_CLOUD_REFRESH_CREDENTIAL=
# ENGRAPHIS_CLOUD_TOKEN_SUBJECT=member
# ENGRAPHIS_CLOUD_ACCESS_TOKEN=

# Which plan the dashboard shows, and which capabilities it draws as unlocked. You should
# not need either of these.
#
# The plan is resolved automatically: once this installation has reached the control plane
# it reads the authoritative entitlement (plan and feature list) and caches it beside the
# cloud session, so a Pro or Team badge is correct on every later boot including offline
# ones. The refresh is opportunistic and runs on a background thread. It never blocks or
# delays startup, and it never fails the dashboard when the cloud is unreachable. Before
# the very first successful contact a connected installation is presented as Pro, the
# smallest paid plan, so a paying customer is never shown the free local core.
#
# ENGRAPHIS_CLOUD_PLAN is an override for the cases automatic resolution cannot cover: an
# air-gapped deployment, or one pinned to a short-lived ENGRAPHIS_CLOUD_ACCESS_TOKEN that
# cannot refresh. It takes precedence over the cached entitlement. Accepts pro, team, or
# free. It is presentation only. Setting it grants nothing, because Engraphis Cloud
# authorizes every paid call regardless of what this client displays.
# ENGRAPHIS_CLOUD_PLAN=team
#
# Set to 0 to stop the client contacting the control plane for the entitlement at all. The
# badge then falls back to ENGRAPHIS_CLOUD_PLAN, or to the last cached answer.
# ENGRAPHIS_CLOUD_ENTITLEMENT_REFRESH=0

# Persistent customer state (cloud session, the cached hosted entitlement, and an optional
# saved scoped relay bearer).
# Locally defaults to ~/.engraphis; in a container use a private persistent volume.
# ENGRAPHIS_STATE_DIR=/data/.engraphis

# The private control plane may report ``workspace_write_grace`` for already-authorized
# hosted-account continuity, capped at 24 hours. It never extends the exact 3-day trial,
# subscription expiry, or cloud access, and it never restricts the free local core.

# Managed compute consent is decided automatically and needs no customer action: a
# local-only installation (no cloud session) is never allowed to upload workspace
# snapshots, while an installation connected to Engraphis Cloud is allowed by default,
# because connecting already accepts the terms covering managed analytics, dreaming, and
# consolidation. This variable is an explicit operator override, not a customer-facing
# setting: set it to 0 to opt a connected installation back out, or to 1 to allow local
# snapshot preparation for a non-interactive deployment. ``1`` does not establish a cloud
# credential or authorize an upload; the cloud service remains authoritative for all paid
# computation.
# ENGRAPHIS_MANAGED_COMPUTE_CONSENT=0

# Optional credential-redacted JSON logs for hosted customer deployments.
# ENGRAPHIS_JSON_LOGS=1

# ── Advanced / Operational ───────────────────────────────────────────────
# These settings are used by advanced deployments, operators, and internal
# subsystems. Leave commented unless your deployment needs them.

# Logging: defaults to INFO, text format.
# ENGRAPHIS_LOG_LEVEL=INFO
# ENGRAPHIS_LOG_FORMAT=text
# ENGRAPHIS_LOG_JSON=0

# CORS: comma-separated origins allowed to call the dashboard REST API.
# Default: http://127.0.0.1:<ENGRAPHIS_PORT> and
# http://localhost:<ENGRAPHIS_PORT>. Explicit values replace both loopback origins.
# ENGRAPHIS_CORS_ORIGINS=https://myapp.example.com

# Rate limiting: requests per window. Default: 0 (disabled), with a 60s window
# used when ENGRAPHIS_RATE_LIMIT is set above zero.
# ENGRAPHIS_RATE_LIMIT=0
# ENGRAPHIS_RATE_WINDOW=60

# HTTPS security origin: used for HTTP-to-HTTPS redirects and security headers.
# ENGRAPHIS_PUBLIC_URL wins; when unset, security falls back to
# ENGRAPHIS_DASHBOARD_URL, then the legacy ENGRAPHIS_RELAY_PUBLIC_URL setting.
# These settings do not change CORS; configure ENGRAPHIS_CORS_ORIGINS separately.
# ENGRAPHIS_PUBLIC_URL=https://engraphis.example.com
# ENGRAPHIS_RELAY_PUBLIC_URL=https://relay.example.com

# Trusted local peers: comma-separated addresses exempt from rate limiting.
# ENGRAPHIS_LOCAL_TRUSTED_PEERS=127.0.0.1,::1

# Import roots: semicolon-separated (Windows) or colon-separated (POSIX)
# directories allowed as import sources.
# ENGRAPHIS_IMPORT_ROOTS=/srv/docs:/home/user/notes

# Memory engine tuning: runtime defaults for decay, chunk sizing, and the
# proactive context loop. CHUNK_MAX is a chunk-count limit, not a token limit.
# ENGRAPHIS_DECAY_HALFLIFE_DAYS=7
# ENGRAPHIS_CHUNK_TOKENS=256
# ENGRAPHIS_CHUNK_MAX=200
# ENGRAPHIS_CHUNK_OVERLAP=32
# Optional reader-tokenizer parity for chunk sizes (requires transformers).
# Pin the revision when the resulting memories support reproducible evidence.
# ENGRAPHIS_CHUNK_TOKENIZER_MODEL=Qwen/Qwen3.5-9B
# ENGRAPHIS_CHUNK_TOKENIZER_REVISION=<immutable model commit>
# ENGRAPHIS_LOOP_INTERVAL=60
# ENGRAPHIS_LOOP_TOP_K=20
# Automatic local consolidation inside the background loop. OFF by default (0): the
# sweep is a workspace-wide cluster scan, so it should be an explicit operator choice.
# N > 0 runs it at most once every N loop ticks (e.g. 30 with a 60s interval ≈ every
# 30 minutes). The sweep is deterministic/offline (never passes an LLM), archives
# decayed transients, and distills recurring episodic memories into semantic digests.
# ENGRAPHIS_LOOP_CONSOLIDATE=0
# ENGRAPHIS_RERANK_MODEL=cross-encoder/ms-marco-MiniLM-L-6-v2
# Optional immutable Hugging Face commit for the reranker. Required for remote
# rerankers when ENGRAPHIS_REQUIRE_IMMUTABLE_MODELS=1.
# ENGRAPHIS_RERANK_REVISION=<lowercase 40-character model commit>

# Workspace allow-list: comma-separated names. Empty = all allowed.
# ENGRAPHIS_WORKSPACES=acme,personal

# Cloud Sync relay: endpoint and optional token for self-hosted relay.
# ENGRAPHIS_RELAY_URL=https://relay.example.com
# ENGRAPHIS_SYNC_TOKEN=
# ENGRAPHIS_SYNC_READ_ONLY=0
# End-to-end encryption key for Cloud Sync bundles (relay transport). A single
# immutable 32-byte URL-safe base64 value (43 chars, or 44 with one '=' pad) that
# every authorized device shares; changing it makes previously stored ciphertext
# unreadable. The folder transport does not encrypt at rest — see docs/SYNC.md.
# ENGRAPHIS_SYNC_E2EE_KEY=

# Hosted plan upgrade URLs: override the default upgrade landing pages.
# ENGRAPHIS_UPGRADE_URL=
# ENGRAPHIS_PRO_UPGRADE_URL=
# ENGRAPHIS_TEAM_UPGRADE_URL=

# Update check cache duration (seconds). Default: 86400 (1 day).
# ENGRAPHIS_UPDATE_CACHE=86400

# Legacy inspector port (retired 2026-07-10; redirects to dashboard).
# ENGRAPHIS_INSPECTOR_PORT=8710