.env.example

# =============================================================================
# MemoryMaster Environment Variables
# =============================================================================
# Copy to `.env` and edit as needed:
#     cp .env.example .env
#
# `.env` is gitignored — never commit real secrets. Values are optional unless
# the selected deployment profile marks them required. A fresh local install
# works with zero env vars as long as you either
# (a) set GEMINI_API_KEY for the free cloud default, or (b) run Ollama
# locally. Everything else is tuning.
#
# Format per entry:
#     # One-line description
#     # Values / Default
#     NAME=

# ---------------------------------------------------------------------------
# Core
# ---------------------------------------------------------------------------

# Path to the SQLite claims DB used when --db isn't passed on the CLI.
# Default: memorymaster.db
MEMORYMASTER_DEFAULT_DB=memorymaster.db

# Workspace root for staleness detection + file-grep probes.
# Default: .
MEMORYMASTER_WORKSPACE=.

# Optional JSON config file; keys listed here override individual env vars.
# Default: unset
# MEMORYMASTER_CONFIG_FILE=config.json

# ---------------------------------------------------------------------------
# Deployment authorization
# ---------------------------------------------------------------------------

# MCP authorization is mandatory. local-trusted is for one private stdio
# process controlled by one OS user and uses SQLite only. PostgreSQL application
# runtime is team-only; do not point a local-trusted process at PostgreSQL.
# Values: local-trusted | team
MEMORYMASTER_MCP_AUTH_MODE=local-trusted

# Team mode requires every value below. The database target must be the
# non-owner application DSN, never the migrator DSN. Scopes are an explicit,
# comma-separated allowlist; wildcards are rejected.
# MEMORYMASTER_MCP_PRINCIPAL=agent-id
# MEMORYMASTER_ROLE_AGENT_ID=writer
# MEMORYMASTER_MCP_TENANT_ID=tenant-id
# MEMORYMASTER_MCP_WORKSPACE=/absolute/path/to/workspace
# MEMORYMASTER_MCP_ALLOWED_SCOPES=project:example,global
# MEMORYMASTER_MCP_DB=postgresql://app-role:password@host/database

# Reserved sensitive-read grant. Team mode currently rejects enabled values
# because v0011 intentionally exposes only public or principal-owned private
# rows; keep this at 0 until database policy support is implemented.
# Values: 0 (team mode)
# MEMORYMASTER_MCP_ALLOW_SENSITIVE=0

# Disposable PostgreSQL RLS integration test only. The admin DSN must use a
# dedicated SUPERUSER or BYPASSRLS schema owner; the app DSN must use a distinct
# restricted role. Tests refuse known live DSN variables and require the
# explicit disposable opt-in. Never set these to a product database.
# MEMORYMASTER_TEST_POSTGRES_DSN=postgresql://migrator:password@host/test_database
# MEMORYMASTER_TEST_POSTGRES_APP_DSN=postgresql://app-role:password@host/test_database
# MEMORYMASTER_TEST_POSTGRES_RLS_DISPOSABLE=1

# Required only when rendering docker-compose.postgres.yml. Use a generated
# secret and rotate any environment that used the retired fixed credential.
# MEMORYMASTER_POSTGRES_PASSWORD=

# Required only when rendering docker-compose.yml. Supply immutable image
# references verified for your platform; tags and unqualified names are unsafe.
# QDRANT_IMAGE_DIGEST=sha256:<64-hex-digest>
# OLLAMA_IMAGE_DIGEST=sha256:<64-hex-digest>

# ---------------------------------------------------------------------------
# LLM provider (auto-ingest Stop hook + steward + entity extraction)
# ---------------------------------------------------------------------------

# Which provider the Stop hook, steward, and entity LLM use.
# Values: google | openai | anthropic | ollama
# Default: google
MEMORYMASTER_LLM_PROVIDER=google

# Override the provider's default model. Per-provider defaults:
#   google     -> gemini-3.1-flash-lite-preview
#   openai     -> gpt-4o-mini
#   anthropic  -> claude-haiku-4-5-20251001
#   ollama     -> llama3.2:3b
# MEMORYMASTER_LLM_MODEL=

# Fallback provider used when the primary provider fails (roadmap 11.1).
# Values: google | openai | anthropic | ollama
# Default: unset (no fallback)
# MEMORYMASTER_LLM_FALLBACK_PROVIDER=

# Model used by the fallback provider.
# Default: per-provider default for MEMORYMASTER_LLM_FALLBACK_PROVIDER
# MEMORYMASTER_LLM_FALLBACK_MODEL=

# Google Gemini API key. Get a free one at https://aistudio.google.com
# Placeholder: YOUR_GEMINI_API_KEY_HERE
# GEMINI_API_KEY=
# GOOGLE_API_KEY=

# OpenAI API key.
# Placeholder: YOUR_OPENAI_API_KEY_HERE
# OPENAI_API_KEY=

# Anthropic API key.
# Placeholder: YOUR_ANTHROPIC_API_KEY_HERE
# ANTHROPIC_API_KEY=

# Ollama base URL (no API key required; run the daemon locally).
# Default: http://localhost:11434
OLLAMA_URL=http://localhost:11434

# Path to a rotating gemini-keys.env file (one KEY=value per line) used by
# the round-robin key rotator. Lets you stack multiple free quotas.
# Default: ~/.memorymaster/gemini-keys.env
# MEMORYMASTER_KEY_FILE=

# Legacy per-module model overrides (fall back to MEMORYMASTER_LLM_MODEL).
# EXTRACTOR_LLM_MODEL=llama3.2
# RESOLVER_LLM_MODEL=llama3.2
# ENTITY_LLM_MODEL=llama3.2

# Comma-separated steward API keys for round-robin rotation.
# MEMORYMASTER_API_KEYS=key1,key2,key3
# Single-key fallback (used when MEMORYMASTER_API_KEYS is unset).
# MEMORYMASTER_API_KEY=

# ---------------------------------------------------------------------------
# Steward / classifier
# ---------------------------------------------------------------------------

# Turn on the v3 statistical classifier (see docs/enabling-v2-systems.md).
# Values: 1 | 0
# Default: 0 (off)
# MEMORYMASTER_STEWARD_CLASSIFIER_ENABLED=0

# Absolute path to a trained classifier .pkl. Presence alone also enables.
# Default: unset
# MEMORYMASTER_STEWARD_CLASSIFIER_PATH=

# Steward cadence policy mode.
# Values: legacy | cadence | lookup
# Default: legacy
# MEMORYMASTER_POLICY_MODE=

# ---------------------------------------------------------------------------
# Recall ranker weights (memorymaster/context_hook.py)
# ---------------------------------------------------------------------------
# Override any single dimension of the linear re-ranker. Floats.
# Defaults: MATCHES=0.3 PHRASE=0.3 ALL=0.2 LEXICAL=0.3 CONFIDENCE=0.1
#           FRESHNESS=0.0 VECTOR=0.0 ENTITY=0.0 VERBATIM=0.0
# MEMORYMASTER_RECALL_W_MATCHES=
# MEMORYMASTER_RECALL_W_PHRASE=
# MEMORYMASTER_RECALL_W_ALL=
# MEMORYMASTER_RECALL_W_LEXICAL=
# MEMORYMASTER_RECALL_W_CONFIDENCE=
# MEMORYMASTER_RECALL_W_FRESHNESS=
# MEMORYMASTER_RECALL_W_VECTOR=
# MEMORYMASTER_RECALL_W_ENTITY=
# MEMORYMASTER_RECALL_W_VERBATIM=

# Weight on the Kuzu graph stream (roadmap 11.3 + 12.1). Distance-weighted
# graph_score = 1/(1+hops) is multiplied by this weight in the linear ranker.
# 0.0 keeps the legacy 5-stream behavior bit-identical (default).
# Type: float
# Default: 0.0
# MEMORYMASTER_RECALL_W_GRAPH=

# Fusion algorithm that combines recall streams.
# Values: linear | rrf
# Default: linear
# MEMORYMASTER_RECALL_FUSION=

# Multiplier (>=0.0) applied to `_relevance` when a claim's scope matches
# the current project scope. 0.0 = off.
# Default: 0.0
# MEMORYMASTER_RECALL_SCOPE_BOOST=

# Enable entity-alias query expansion (fanout on matched synonyms).
# Values: 1 | 0
# Default: 0
# MEMORYMASTER_RECALL_QUERY_EXPANSION=

# Enable the MemPalace-style verbatim recall stream. Only contributes when
# MEMORYMASTER_RECALL_W_VERBATIM > 0.
# Values: 1 | 0
# Default: 0
# MEMORYMASTER_RECALL_VERBATIM=

# Kuzu-backed graph retrieval stream (memorymaster/graph_store.py, roadmap 11.3).
# When 1, the 6th stream reaches claims within MAX_HOPS hops of the query's
# entities on the claim-entity bipartite graph. Requires the [graph] extra
# (pip install memorymaster[graph]) AND the graph DB populated by
# scripts/backfill_graph_store.py. Defensive: missing / corrupt graph falls
# back to the 5-stream stack.
# Values: 1 | 0
# Default: 0
# MEMORYMASTER_RECALL_GRAPH=

# BFS depth for the graph stream (one "hop" = Entity <- Claim -> Entity).
# Default: 2
# MEMORYMASTER_RECALL_GRAPH_MAX_HOPS=

# Path to the Kuzu DB file created by scripts/backfill_graph_store.py.
# Default: ~/.memorymaster/graph.kuzu
# MEMORYMASTER_RECALL_GRAPH_PATH=

# Legacy coarse retrieval ranking weights (advanced; prefer W_* above).
# MEMORYMASTER_RETRIEVAL_WEIGHTS=0.45,0.30,0.15,0.10
# MEMORYMASTER_RETRIEVAL_WEIGHTS_NO_VECTOR=0.55,0.30,0.15
# MEMORYMASTER_LEXICAL_WEIGHTS=0.55,0.15,0.25,0.05

# ---------------------------------------------------------------------------
# BM25 lexical scorer
# ---------------------------------------------------------------------------

# Master switch for BM25. When off, falls back to the overlap scorer.
# Values: 1 | 0
# Default: 1
# MEMORYMASTER_LEXICAL_BM25=

# BM25 term-frequency saturation parameter.
# Default: 1.2
# MEMORYMASTER_BM25_K1=

# BM25 length-normalisation parameter.
# Default: 0.25
# MEMORYMASTER_BM25_B=

# Per-field BM25 weights (subject column vs body text).
# Defaults: W_SUBJECT=1.0  W_TEXT=1.0
# MEMORYMASTER_BM25_W_SUBJECT=
# MEMORYMASTER_BM25_W_TEXT=

# ---------------------------------------------------------------------------
# Entity extraction / ingest defaults
# ---------------------------------------------------------------------------

# Enable LLM-backed entity extraction (off = regex-only fallback).
# Values: 1 | 0 | google | openai | anthropic | ollama
# Default: 0
# MEMORYMASTER_ENTITY_LLM=

# Default scope applied when a caller omits one.
# Values: project:<slug> | user | team:<name> | global
# Default: project:memorymaster
# MEMORYMASTER_SCOPE_DEFAULT=

# ---------------------------------------------------------------------------
# Qdrant (optional external vector backend)
# ---------------------------------------------------------------------------

# Base URL of a reachable Qdrant instance. Unset disables Qdrant and
# forces SQLite FTS5 + vector fallback.
# Default: http://localhost:6333 (only honoured when explicitly set)
QDRANT_URL=http://localhost:6333

# Required by the hardened Compose/Helm Qdrant profile. Generate and provision
# this out of band; never commit the value.
# QDRANT_API_KEY=
# QDRANT_TLS_CERT=
# QDRANT_TLS_KEY=
# QDRANT_CA_CERT=

# Optional path to a trusted CA certificate for a TLS-enabled Qdrant endpoint.
# QDRANT_CA_CERT=

# ---------------------------------------------------------------------------
# Lifecycle tuning (volatility: low,medium,high triples)
# ---------------------------------------------------------------------------

# Freshness half-life in hours.
# MEMORYMASTER_FRESHNESS_HALFLIFE=168.0,72.0,24.0

# Revalidation cadence in hours.
# MEMORYMASTER_CADENCE_HOURS=168.0,72.0,24.0

# Daily decay rates.
# MEMORYMASTER_DECAY_RATES=0.01,0.03,0.06

# ---------------------------------------------------------------------------
# Thresholds
# ---------------------------------------------------------------------------

# Minimum score for a claim to pass validation.
# Default: 0.58
# MEMORYMASTER_VALIDATION_THRESHOLD=

# Confidence below which a claim transitions to stale.
# Default: 0.35
# MEMORYMASTER_STALE_THRESHOLD=

# Score margin for conflict detection.
# Default: 0.08
# MEMORYMASTER_CONFLICT_MARGIN=

# Score bonus applied to pinned claims during ranking.
# Default: 0.03
# MEMORYMASTER_PINNED_BONUS=

# ---------------------------------------------------------------------------
# Access control
# ---------------------------------------------------------------------------

# Path to roles config JSON for RBAC.
# MEMORYMASTER_ROLES_CONFIG=roles.json

# Per-agent role overrides: MEMORYMASTER_ROLE_<AGENT>=<role>
# MEMORYMASTER_ROLE_CLAUDE=admin
# MEMORYMASTER_ROLE_CODEX=reader

# ---------------------------------------------------------------------------
# Security
# ---------------------------------------------------------------------------

# Set to 1 to allow the --allow-sensitive flag (off by default).
# MEMORYMASTER_ALLOW_SENSITIVE_BYPASS=0