.env.example

# --- Database ---
# Docker image users can omit DATABASE_URL, or set DATABASE_URL=embedded, to use
# the bundled single-container Postgres/pgvector instance. Source checkouts and
# production deployments should set a real Postgres connection string.
DATABASE_URL=postgresql://atomicmemory:atomicmemory@localhost:5433/atomicmemory
# Docker entrypoint only: set false when migrations run from a separate
# pre-deploy job. Defaults to true when omitted.
# ATOMICMEMORY_RUN_MIGRATIONS_ON_STARTUP=true
# Docker entrypoint only: forwarded to `migrate({ lockTimeoutMs })`.
# Increase for rolling deploys where another replica may hold the migration lock.
# MIGRATION_LOCK_TIMEOUT_MS=120000

# --- Provider credentials ---
# Required when either EMBEDDING_PROVIDER=openai or LLM_PROVIDER=openai.
OPENAI_API_KEY=<openai-api-key>
# Required only for the matching provider selections:
# GROQ_API_KEY=<groq-api-key>
# ANTHROPIC_API_KEY=<anthropic-api-key>
# GOOGLE_API_KEY=<google-api-key>

# --- Core API auth ---
# Shared API key clients must send as `Authorization: Bearer <key>`.
# Rotate by restarting the server with a new value.
# Generate with: openssl rand -hex 32
# Docker image local mode defaults this to `local-dev-key` when omitted.
CORE_API_KEY=replace-with-a-strong-random-secret

# Optional admin-only cleanup endpoint for disposable smoke/eval scopes.
# When both values are set, DELETE /v1/admin/scope accepts a JSON body
# `{ "user_id": "..." }` and deletes only matching test scopes.
# Use a different secret from CORE_API_KEY. Do not enable for general clients.
# CORE_ADMIN_API_KEY=<admin-cleanup-secret>
# CORE_TEST_SCOPE_ALLOW_PATTERN=^(smoke-|docker-|test-).+

# Hex-encoded HMAC secret used to derive PII-safe storage-key
# prefixes. Must be at least 64 hex chars (32 bytes of entropy).
# Rotating this invalidates existing managed-blob storage paths;
# only generate once per deployment.
# Generate with: openssl rand -hex 32
# Docker image local mode provides a non-production default when omitted.
STORAGE_KEY_HMAC_SECRET=000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f

# --- Server ---
PORT=3050
# Required deployment posture for storage-policy gates. Use `local` for
# laptop/docker-compose development, `staging` for pre-prod, and `production`
# for hardened hosted deployments.
# Docker image local mode defaults this to `local` when omitted.
RAW_STORAGE_DEPLOYMENT_ENV=local
# Comma-separated list of allowed CORS origins (default: localhost:3050,3081)
# ALLOWED_ORIGINS=http://localhost:3050,http://localhost:3081

# --- Embedding ---
# EMBEDDING_PROVIDER=openai
# EMBEDDING_MODEL=text-embedding-3-small
# Required — must match the actual output dimensions of your embedding model.
# mxbai-embed-large=1024, text-embedding-3-small=1536, Voyage 4=1024
# Docker image local mode defaults this to `1536` when omitted.
EMBEDDING_DIMENSIONS=1536

# Local/no-embedding-key option:
# EMBEDDING_PROVIDER=transformers
# EMBEDDING_MODEL=Xenova/all-MiniLM-L6-v2
# EMBEDDING_DIMENSIONS=384

# OpenAI-compatible embedding endpoint:
# EMBEDDING_PROVIDER=openai-compatible
# EMBEDDING_API_URL=http://localhost:1234/v1
# EMBEDDING_API_KEY=local-or-provider-key
# EMBEDDING_MODEL=text-embedding-3-small
# EMBEDDING_DIMENSIONS=1536

# Voyage embedding lane:
# EMBEDDING_PROVIDER=voyage
# VOYAGE_API_KEY=<voyage-api-key>
# VOYAGE_DOCUMENT_MODEL=voyage-4-large
# VOYAGE_QUERY_MODEL=voyage-4-lite
# EMBEDDING_DIMENSIONS=1024

# --- LLM ---
# LLM_PROVIDER=openai
# LLM_MODEL=gpt-4o-mini

# OpenAI-compatible LLM endpoint:
# LLM_PROVIDER=openai-compatible
# LLM_API_URL=http://localhost:1234/v1
# LLM_API_KEY=local-or-provider-key
# LLM_MODEL=gpt-4o-mini

# Ollama LLM endpoint:
# LLM_PROVIDER=ollama
# OLLAMA_BASE_URL=http://localhost:11434
# LLM_MODEL=llama3.1

# Other hosted LLM providers:
# LLM_PROVIDER=groq
# GROQ_API_KEY=<groq-api-key>
# LLM_MODEL=llama-3.1-8b-instant
# LLM_PROVIDER=anthropic
# ANTHROPIC_API_KEY=<anthropic-api-key>
# LLM_MODEL=claude-3-5-haiku-latest
# LLM_PROVIDER=google-genai
# GOOGLE_API_KEY=<google-api-key>
# LLM_MODEL=gemini-2.0-flash

# Personal local Claude Code extraction, no separate Anthropic API key:
# LLM_PROVIDER=claude-code
# For fully local/no-provider-key development, pair this with a non-OpenAI
# embedding provider such as EMBEDDING_PROVIDER=transformers.

# --- Runtime config mutation (dev/test only) ---
# Opt-in gate for PUT /memories/config. Leave unset in production — the
# route returns 410 Gone unless this is true.
# See https://docs.atomicstrata.ai/platform/consuming-core.
# CORE_RUNTIME_CONFIG_MUTATION_ENABLED=false

# --- Internal retrieval tuning ---
# Defaults mirror the balanced adaptive policy. These are experimental knobs
# for benchmark sweeps and should not be treated as stable product config.
# Normalized fallback relevance floor for unscoped simple/medium non-temporal searches.
# SIMILARITY_THRESHOLD=0.3
# ADAPTIVE_SIMPLE_LIMIT=5
# ADAPTIVE_MEDIUM_LIMIT=5
# ADAPTIVE_COMPLEX_LIMIT=8
# ADAPTIVE_MULTI_HOP_LIMIT=12
# ADAPTIVE_AGGREGATION_LIMIT=25
# LITERAL_LIST_PROTECTION_ENABLED=false
# LITERAL_LIST_PROTECTION_MAX_PROTECTED=3
# OBSERVATION_DATE_EXTRACTION_ENABLED=false
# QUOTED_ENTITY_EXTRACTION_ENABLED=false
# TEMPORAL_QUERY_CONSTRAINT_ENABLED=false
# TEMPORAL_QUERY_CONSTRAINT_BOOST=2

# --- Raw document storage (optional) ---
# Defaults to pointer-only mode. Use managed_blob only when configuring a
# concrete storage provider; misconfigured provider blocks fail at startup.
# RAW_STORAGE_MODE=pointer_only
# RAW_STORAGE_MODE=managed_blob
# RAW_STORAGE_PREFIX=local/core
# RAW_STORAGE_PROVIDER=local_fs
# RAW_STORAGE_LOCAL_FS_ROOT=./data/raw-storage
# RAW_CONTENT_CODEC=none

# Filecoin managed blob storage:
# Filecoin data is publicly retrievable by CID unless encrypted before
# upload. Staging and production Filecoin deployments require AES-GCM.
# RAW_STORAGE_PROVIDER=filecoin
# RAW_STORAGE_DEPLOYMENT_ENV=production
# RAW_CONTENT_CODEC=aes_gcm
# RAW_CONTENT_CODEC_KEYS=v1:<base64url-32-byte-key>
# RAW_CONTENT_CODEC_ACTIVE_KEY_ID=v1
# RAW_STORAGE_FILECOIN_DRIVER=synapse
# RAW_STORAGE_FILECOIN_NETWORK=calibration
# RAW_STORAGE_FILECOIN_PRIVATE_KEY=0x<64-hex-private-key>
# RAW_STORAGE_FILECOIN_SOURCE=atomicmemory-core
# RAW_STORAGE_FILECOIN_WITH_CDN=false
# For calibration live-test credentials, copy .env.foc.local.example to
# .env.foc.local and fill in the placeholders. Do not commit .env.foc.local.

# S3-compatible managed blob storage:
# RAW_STORAGE_PROVIDER=s3
# RAW_STORAGE_S3_BUCKET=atomicmemory-raw
# RAW_STORAGE_S3_REGION=us-east-1
# RAW_STORAGE_S3_ENDPOINT=https://s3.amazonaws.com
# RAW_STORAGE_S3_ACCESS_KEY_ID=...
# RAW_STORAGE_S3_SECRET_ACCESS_KEY=...

# --- Railway ---
# On Railway, DATABASE_URL is injected by the Postgres plugin.
# Set OPENAI_API_KEY in Railway service variables.
# PORT is injected automatically by Railway.