.env.example

# Shared Brain Configuration (Zengram v4)

# --- Required ---
BRAIN_API_KEY=your-admin-api-key-here
PORT=8084
# HOST=0.0.0.0  # Default: 127.0.0.1 (localhost only). Set to 0.0.0.0 for LAN/Docker access.

# --- Auth notes ---
# A single admin key (BRAIN_API_KEY) authenticates every caller. Agent identity
# is declarative: each write carries its own source_agent (validated), so give
# every agent in your fleet a stable name — briefings, filters, and cross-agent
# corroboration key off it. Scoped per-agent keys are on the roadmap.

# --- Reverse proxy ---
# TRUST_PROXY=1  # Express 'trust proxy' (true/false, hop count, or IP/CIDR list).
#                # Set when running behind a reverse proxy so the failed-auth
#                # throttle keys on the real client IP. Default: off.

# --- Rate Limiting ---
# RATE_LIMIT_WRITES=60          # Max write requests per minute (default: 60)
# RATE_LIMIT_READS=120          # Max read requests per minute (default: 120)
# RATE_LIMIT_CONSOLIDATION=10   # Max consolidation + research runs per hour (default: 10)

# --- Vector store (v4) ---
# Vectors live in Postgres via the pgvector extension. No separate Qdrant container.
# Uses STRUCTURED_STORE=postgres + POSTGRES_URL below.

# --- Embedding Provider ---
# Options: openai, gemini, ollama
EMBEDDING_PROVIDER=gemini
# For OpenAI (text-embedding-3-small, 1536 dims):
# EMBEDDING_PROVIDER=openai
# OPENAI_API_KEY=your-openai-key-here
# For a self-hosted OpenAI-compatible encoder (vLLM / Infinity / TEI / llama.cpp):
# OPENAI_BASE_URL=http://localhost:8000/v1  # api key optional for local servers
# OPENAI_EMBEDDING_DIMS=1024   # Only set to request truncated dims; unset = the
#                              # model's native size (probed at startup). Local
#                              # servers often reject an explicit dimensions param.
# For Gemini (gemini-embedding-2-preview, Matryoshka truncation):
GEMINI_API_KEY=your-gemini-key-here
GEMINI_EMBEDDING_MODEL=gemini-embedding-2-preview
GEMINI_EMBEDDING_DIMS=1536    # 1536 is the v4 default — sweet spot for quality/cost/index memory. 3072 max, 768 min.
# For Ollama:
# OLLAMA_URL=http://localhost:11434
# OLLAMA_MODEL=nomic-embed-text
# Instruction-aware encoders (qwen3-embedding, e5, gte) expect an instruction
# prefix on the QUERY side only — without it they can score below older models.
# \n and \t escapes are decoded, so the prefix can live in one env line.
# EMBED_QUERY_PREFIX=Instruct: Given a web search query, retrieve relevant passages that answer the query\nQuery:
# EMBED_DOC_PREFIX=             # Rarely needed; documents usually embed raw.
# Swapping encoders on an existing corpus? Re-embed in place (dry-run first):
#   node api/scripts/reembed.js [--commit]

# --- Structured Storage Backend ---
# v4: Postgres is required. The postgres container uses the pgvector/pgvector:pg16 image
# so that vectors and structured metadata live in the same DB, same transaction boundary.
STRUCTURED_STORE=postgres
# Use the container name `zengram-postgres` as the host, not the compose service name
# `postgres` — if zengram-api shares a network with another stack that also has a
# `postgres` service (e.g. baserow), Docker DNS will resolve the wrong one.
POSTGRES_URL=postgresql://brain:brain_secret@zengram-postgres:5432/shared_brain
POSTGRES_PASSWORD=brain_secret
# PGPOOL_MAX=10                  # Max connections per pool (default: 10)
# PG_STATEMENT_TIMEOUT_MS=30000  # Per-connection statement_timeout in ms (default: 30000)

# --- Consolidation Engine ---
CONSOLIDATION_ENABLED=true
CONSOLIDATION_INTERVAL=0 */6 * * *
# Gate: skip scheduled runs if active corpus < this size. Manual POST /consolidate always runs.
CONSOLIDATION_MIN_CORPUS=1500
# LLM provider for consolidation: openai, anthropic, ollama
CONSOLIDATION_LLM=openai
CONSOLIDATION_MODEL=gpt-4o-mini
# For Anthropic:
# ANTHROPIC_API_KEY=your-anthropic-key-here
# CONSOLIDATION_MODEL=claude-sonnet-4-20250514
# CONSOLIDATION_MAX_MEMORIES=500  # Per-run backlog cap, oldest-first (default: 500)
# LLM_MAX_TOKENS=8192             # Max output tokens per consolidation call (default: 8192)
# LLM_RETRY_BASE_MS=500           # Base delay for the one-retry backoff on 429/5xx/network (default: 500)

# --- Research (agentic retrieval) ---
# POST /research + the brain_research MCP tool run an iterate-until-sufficient
# retrieval loop (several LLM calls per request). OFF by default; needs the same
# CONSOLIDATION_LLM provider. Enable explicitly once measured against /reflect.
# RESEARCH_ENABLED=false
# MAX_RESEARCH_ITERS=2          # Retrieval rounds before synthesis (1-4, default: 2)
# RESEARCH_FETCH_PER_ITER=15    # Memories fetched per iteration (default: 15)
# RESEARCH_MAX_CONTEXT=40       # Max memories sent to the LLM per call (default: 40)

# --- Memory Decay ---
# Decay factor per day without access (0.98 = 2% decay/day). Only affects facts and statuses.
DECAY_FACTOR=0.98

# --- Event TTL ---
# EVENT_TTL_DAYS=30  # Auto-expire low-importance, never-accessed events after N days (default: 30)

# --- Multi-Path Retrieval & Ranking ---
# Parallel vector + full-text search, merged with Reciprocal Rank Fusion; final
# ordering blends the fused RRF signal with vector similarity, then weights
# confidence decay, capped access boost, temporal proximity, and importance.
# MULTI_PATH_SEARCH=true      # Enable/disable multi-path retrieval (default: true)
# RRF_K=60                    # RRF smoothing constant. Range 50-100 (default: 60)
# RRF_VECTOR_WEIGHT=1         # Weighted RRF: vector list multiplier (default: 1)
# RRF_KEYWORD_WEIGHT=1        # Weighted RRF: keyword list multiplier (default: 1)
# SEARCH_SCORE_FLOOR=0.55     # Min vector score, on the 0.5+cosine/2 scale (default: 0.55 ≈ cosine 0.1)
# RANK_W_SIM=0.6              # Blend weight: vector similarity (default: 0.6)
# RANK_W_RRF=0.4              # Blend weight: normalized RRF score (default: 0.4)
# RANK_ACCESS_BOOST_CAP=2.0   # Max access-frequency multiplier (default: 2.0)
# RANK_KEYWORD_ONLY_SIM=0.55  # Similarity stand-in for keyword-only hits (default: 0.55)

# --- Cross-Encoder Reranker (optional; the biggest retrieval-precision lever) ---
# Re-scores the fused candidate pool by reading query and document together.
# Speaks the standard /rerank shapes: TEI, Infinity, vLLM, Jina, Cohere.
# Off by default — search behavior is unchanged until enabled. On any reranker
# outage, search degrades gracefully to fused order.
# RERANK_ENABLED=true
# RERANK_URL=http://localhost:8090/rerank
# RERANK_API=cohere            # cohere (Infinity/vLLM/Jina/Cohere/llama.cpp) | tei
# RERANK_MODEL=                # Sent in cohere flavour; many servers ignore it
# RERANK_API_KEY=              # Optional bearer token
# RERANK_CANDIDATES=40         # Fused pool size handed to the cross-encoder (default: 40)
# RERANK_MAX_BATCH=32          # Client-side chunking for servers that cap batch size (default: 32)
# RERANK_TIMEOUT_MS=20000

# --- Entity-Graph Retrieval (optional) ---
# Third retrieval path: entities extracted from the query expand one hop over
# the co-occurrence graph, and their linked memories join RRF fusion as a
# weighted list. Off by default.
# GRAPH_RETRIEVAL_ENABLED=true
# RRF_GRAPH_WEIGHT=0.5         # Fusion weight for the graph list (default: 0.5)
# GRAPH_HOP_DECAY=0.5          # Neighbor score multiplier vs direct match (default: 0.5)
# GRAPH_NEIGHBOR_LIMIT=12      # Max expanded edges per query (default: 12)

# --- Full-Text Search Language ---
# BM25_TSCONFIG=english        # Postgres text-search config for the keyword path.
#                              # 'zengram_multi' = managed accent-folding config
#                              # (unaccent+simple) for mixed-language corpora —
#                              # better for non-English text, but loses English
#                              # stemming. Changing this reindexes once on boot.

# --- Temporal Resolution ---
# BRAIN_TIMEZONE=America/Toronto  # IANA zone for resolving "today"/"this week" to civil days
#                                 # (default: the server's own timezone)

# --- MCP Server Timeouts ---
# BRAIN_MCP_TIMEOUT=15000          # Default timeout for MCP→API calls in ms (default: 15000)
# BRAIN_MCP_CONSOLIDATION_TIMEOUT=120000  # Sync consolidation timeout in ms (default: 120000)

# --- MCP Server Responses & Identity ---
# BRAIN_MCP_MAX_RESPONSE_CHARS=24000  # Cap serialized tool responses; oversized results
#                                     # return a truncation envelope suggesting format=index/compact
# BRAIN_MCP_PRETTY_JSON=false         # Pretty-print tool JSON (costs tokens; default: compact)
# BRAIN_MCP_LOCK_SOURCE_AGENT=false   # When true, the env-configured identity always wins —
#                                     # tool calls cannot pass a different source_agent
#                                     # (impersonation guard for multi-writer setups)

# --- Self-Hosted LLM (consolidation/reflect/research) ---
# OPENAI_BASE_URL=http://localhost:8000/v1  # Point CONSOLIDATION_LLM=openai at vLLM/llama.cpp/Ollama
# LLM_CHAT_TEMPLATE_KWARGS={"enable_thinking": false}  # Forwarded to the server; disables
#                                     # reasoning-mode on models that leak <think> blocks