.env.example

# ─── MemForge Standalone — Environment Configuration ────────────────────────

# PostgreSQL connection string (required)
DATABASE_URL=postgresql://user:password@localhost:5432/memforge

# HTTP server port (default: 3333)
PORT=3333

# Connection pool size (default: 10)
DB_POOL_MAX=10

# Max hot-tier rows to process per consolidation run (default: 500)
CONSOLIDATION_BATCH_SIZE=500

# Rows processed per inner transaction within a consolidation run (default: 50)
# CONSOLIDATION_INNER_BATCH_SIZE=50

# Minimum hot-tier rows before auto-consolidation triggers (default: 50)
CONSOLIDATION_THRESHOLD=50

# Auto-register unknown agent IDs on add() (default: true)
# Set to "false" to require explicit agent registration first
AUTO_REGISTER_AGENTS=true

# ─── Embedding / Vector Search ───────────────────────────────────────────────

# Embedding provider: "openai", "ollama", or "none" (default: none)
# When set to "none", semantic/hybrid search is disabled — keyword search only
EMBEDDING_PROVIDER=none

# OpenAI-compatible API settings (used when EMBEDDING_PROVIDER=openai)
OPENAI_API_KEY=
OPENAI_API_BASE_URL=https://api.openai.com/v1
EMBEDDING_MODEL=text-embedding-3-small
EMBEDDING_DIMENSIONS=1536

# Ollama settings (used when EMBEDDING_PROVIDER=ollama)
OLLAMA_BASE_URL=http://localhost:11434
# EMBEDDING_MODEL=nomic-embed-text
# EMBEDDING_DIMENSIONS=768

# ─── LLM Consolidation ───────────────────────────────────────────────────────

# LLM provider for intelligent consolidation: "anthropic", "openai", "ollama", or "none" (default: none)
# When set to "none", consolidation uses concat mode (fast, no LLM calls)
LLM_PROVIDER=none

# Consolidation mode: "concat" (default, fast) or "summarize" (LLM-driven distillation)
# Can also be overridden per-request via POST body { "mode": "summarize" }
CONSOLIDATION_MODE=concat

# Anthropic settings (used when LLM_PROVIDER=anthropic)
ANTHROPIC_API_KEY=
# LLM_MODEL=claude-sonnet-4-20250514

# OpenAI settings for LLM (used when LLM_PROVIDER=openai)
# Uses OPENAI_API_KEY and OPENAI_API_BASE_URL from the embedding section above
# LLM_MODEL=gpt-4o-mini

# Ollama settings for LLM (used when LLM_PROVIDER=ollama)
# Uses OLLAMA_BASE_URL from the embedding section above
# LLM_MODEL=llama3.2

# ─── Audit Chain & Integrity Verification ────────────────────────────────────

# HMAC key for content hashes and chain integrity (REQUIRED for tamper detection)
# Generate with: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
# Without this, audit uses a default key — detects accidents but not targeted attacks.
AUDIT_HMAC_KEY=

# HMAC key for Redis cache envelope signing. Unsigned or tampered cache
# entries are rejected and dropped. Falls back to AUDIT_HMAC_KEY when
# unset; a fixed default is used if neither is set (accidental-corruption
# detection only — set this in production to resist targeted tampering).
# CACHE_HMAC_KEY=

# Days to keep audit records immutable (default: 90)
AUDIT_RETENTION_DAYS=90

# Cold tier retention — hard-delete archived rows older than N days (default: unset = keep forever)
# Opt-in: leave unset or set to 0 to disable. Existing deploys are unaffected.
# COLD_TIER_RETENTION_DAYS=365

# Archive expired audit records to cold_audit (true) or delete them (false)
AUDIT_ARCHIVE_ON_EXPIRY=true

# ─── Content Classification & LLM Safety ────────────────────────────────────

# Allow sending memory content to external (non-local) LLM providers (default: false)
# When false, only Ollama (local) is permitted for consolidation, reflection, and revision.
# When true, a warning is logged on first use. See THREAT_MODEL.md for risks.
ALLOW_REMOTE_LLM=false

# ─── Sleep Cycle / Memory Revision Engine ────────────────────────────────────

# Separate LLM provider for sleep cycle revisions (default: uses main LLM_PROVIDER)
# Use a local model here for low-cost routine maintenance
# REVISION_LLM_PROVIDER=ollama

# Max tokens to spend on LLM calls per sleep cycle (default: 100000)
SLEEP_CYCLE_TOKEN_BUDGET=100000

# Importance threshold below which memories are evicted to cold tier (default: 0.1)
SLEEP_CYCLE_EVICTION_THRESHOLD=0.1

# Confidence threshold below which memories are flagged for LLM revision (default: 0.4)
SLEEP_CYCLE_REVISION_THRESHOLD=0.4

# Whether to run reflection as part of sleep cycles (default: true)
SLEEP_CYCLE_INCLUDE_REFLECTION=true

# Hard cap on warm_tier rows per agent (default: unset or 0 = no cap, opt-in).
# When an agent exceeds this limit, the sleep cycle archives lowest-importance
# memories first (not oldest) until exactly this many rows remain.
# Existing deployments are unaffected when left unset.
# WARM_TIER_MAX_PER_AGENT=1000

# ─── Sleep Advisory (Adaptive Scheduling) ────────────────────────────────────
#
# Advisory only — MemForge has no built-in scheduler by design. These thresholds
# control the recommendation returned by GET /memory/:agentId/sleep/advisory.
# External orchestrators (cron jobs, control planes, dashboards) read the result
# and decide whether to call POST /memory/:agentId/sleep.
#
# hot_backlog signal: urgency level when unconsolidated hot-tier row count exceeds:
# SLEEP_ADVISORY_HOT_BACKLOG_LOW=25
# SLEEP_ADVISORY_HOT_BACKLOG_MEDIUM=100
# SLEEP_ADVISORY_HOT_BACKLOG_HIGH=500
#
# contradiction_rate signal: urgency 'high' when fraction of recent reflections
# containing contradictions exceeds this value (0–1):
# SLEEP_ADVISORY_CONTRADICTION_HIGH=0.20
#
# revision_debt signal: urgency 'medium' when warm-tier rows with confidence < 0.4
# exceeds this count:
# SLEEP_ADVISORY_REVISION_DEBT_MEDIUM=50
#
# time_since_last_sleep signal: urgency 'medium' when hours since last sleep cycle
# exceeds this value (and the agent has activity):
# SLEEP_ADVISORY_MAX_AGE_HOURS=24
#
# stability ceiling: if the fraction of graduated warm-tier rows exceeds this
# value, the overall urgency is clamped to 'low' — frequent sleeps are wasted
# effort on a stable knowledge base:
# SLEEP_ADVISORY_STABILITY_CEILING=0.80

# ─── Temporal Intelligence ───────────────────────────────────────────────────

# Temporal decay rate per hour for query ranking (default: 0 = no decay)
# Example: 0.01 means a memory loses ~1% relevance per hour
TEMPORAL_DECAY_RATE=0

# ─── Rate Limiting ───────────────────────────────────────────────────────────

# Rate limit window in milliseconds (default: 60000 = 1 minute)
RATE_LIMIT_WINDOW_MS=60000

# Max requests per window per IP on /memory routes (default: 100, 0 = disabled)
RATE_LIMIT_MAX=100

# ─── Redis Cache ─────────────────────────────────────────────────────────────

# Redis connection URL (default: redis://localhost:6379)
# If Redis is unavailable, cache is silently disabled — service still works
REDIS_URL=redis://localhost:6379

# Admin token for /admin/cache/* endpoints (default: no auth required)
# Set to a strong random string in production
ADMIN_TOKEN=