Configuration

Configuration

Where settings come from

Settings come from four sources, each overriding the one before: the defaults below, the user-level config.env, the file named by STRATAKB_CONFIG, then environment variables (your shell, or the env block of your MCP client's configuration).

flowchart LR
    d["Defaults"] --> u["User config.env"] --> c["File named by<br/>STRATAKB_CONFIG"] --> e["Environment<br/>variables"]

Loading

Source	Where
User config file	%APPDATA%\stratakb\config.env on Windows; $XDG_CONFIG_HOME/stratakb/config.env, else ~/.config/stratakb/config.env, elsewhere
STRATAKB_CONFIG	Any file you name
Environment variables	Your shell, or the env block of your MCP client's configuration

Copy .env.example to the user config file to start.

• ./.env is not read unless you set STRATAKB_CONFIG=.env. When the server finds one it does not read, it logs a warning at startup (dotenv_not_read).
• A STRATAKB_CONFIG that names a missing file is logged and skipped by the server; stratakb add and stratakb receipt refuse with exit 2 and say to fix the path or unset it.
• Keys the server does not know, such as DB_PASSWORD, are ignored, so one file can serve both the server and Docker. docker compose still reads ./.env itself for its own variables (see Passwords).

When a change takes effect

• The server reads STRATA_USER and STRATA_ROLE once, when it starts; changing either takes a restart. stratakb add, stratakb receipt and the scripts read them each time they run.
• The server keeps the settings it started with for strata_admin_health, strata_search, strata_ask, strata_verify, strata_ingest_documents, strata_apply_preset, query rewriting, the query embedding and the raw-query audit setting: a config file edited while the server runs changes nothing for them until you restart it. That includes STRATA_LOCAL_ONLY for the outbound providers: turning it on in a config file stops them only after a restart, though a model the server has not loaded yet is kept from downloading at once.

Settings

Variable	Default	Description
STRATAKB_CONFIG		A settings file read after the user-level config.env; environment variables still win
DATABASE_URL	postgresql://strata:…@127.0.0.1:5433/strata	PostgreSQL connection. Logs never show its user or password
READONLY_DATABASE_URL		Connection for strata_db_query and strata_db_explain; point it at the strata_readonly role from db/03_readonly_role.sql. Empty means the two tools are off; a superuser, or a member of a superuser or server-access role (such as the Docker strata user) is refused
STRATA_USER, STRATA_ROLE	developer, viewer	Identity and role on stdio, read once when the server starts; see Roles and Audit
EMBEDDING_BACKEND	local	local (sentence-transformers) or openai (OpenAI, or the OpenAI-compatible server in EMBEDDING_BASE_URL); searches and ingests refuse any other value
EMBEDDING_MODEL	all-mpnet-base-v2	Embedding model; the openai backend uses text-embedding-3-large unless set
EMBEDDING_DIMENSIONS	768	Must match the model and the vector(…) column; vectors of another length are refused, and strata_admin_health reports a column of another size
EMBEDDING_BASE_URL		openai backend: an OpenAI-compatible server, ending in /v1 (for example http://127.0.0.1:11434/v1); empty means OpenAI. See Embeddings from a model server
EMBEDDING_API_KEY		Key for EMBEDDING_BASE_URL, only if the server asks for one; a local server usually needs none (requests then carry no Authorization header)
OPENAI_API_KEY		Needed for the openai backend without EMBEDDING_BASE_URL; never sent to that server
OPENAI_BASE_URL, ANTHROPIC_BASE_URL		Read by the OpenAI and Anthropic SDKs: where openai embeddings without EMBEDDING_BASE_URL, and Anthropic query rewriting, are sent. STRATA_LOCAL_ONLY checks them too
QUERY_REWRITE_PROVIDER	anthropic	Who rewrites questions in strata_ask: anthropic, or openai_compatible (the endpoint in QUERY_REWRITE_BASE_URL); see Query rewriting
ANTHROPIC_API_KEY		Turns on query rewriting with the anthropic provider
QUERY_REWRITE_BASE_URL		openai_compatible provider: an OpenAI-compatible chat endpoint, ending in /v1 (for example http://127.0.0.1:11434/v1)
QUERY_REWRITE_API_KEY		Key for QUERY_REWRITE_BASE_URL, only if the endpoint asks for one; a local endpoint usually needs none (requests then carry no Authorization header); OPENAI_API_KEY is never sent there
QUERY_REWRITE_MODEL	claude-haiku-5-5	Model used for query rewriting; must be set for openai_compatible
HYBRID_SEARCH_ENABLED	true	Vector plus full-text search
HYBRID_SEMANTIC_WEIGHT, HYBRID_KEYWORD_WEIGHT	0.7, 0.3	RRF weights
HYBRID_RRF_K	60	RRF constant
HYBRID_KEYWORD_SLOTS	1	Results kept for the best full-text matches, so an exact term the embedding misses still comes back (at most top_k − 1; 0 turns it off)
HNSW_EF_SEARCH	40	Recall versus latency for the vector index
RERANKING_ENABLED	true	Cross-encoder reranking in strata_ask. Extractive answers score their sentences with the same model even when this is off
RERANKING_MODEL	cross-encoder/ms-marco-MiniLM-L-6-v2	Reranker
RERANKING_CANDIDATE_MULTIPLIER	3	strata_ask reranks top_k times this many candidates
ANSWER_TOKEN_BUDGET	1500	How much text strata_ask returns: the best passages that fit this many tokens (about four characters each), citations included; the first passage always comes back. It also sets how long an exact clause strata_verify accepts can be
CACHE_ENABLED, CACHE_TTL_SECONDS	true, 600	Query result cache, cleared whole when any server process changes a layer (checked at most every 2 seconds)
CACHE_MAXSIZE	500	Query results kept in the cache
LEARNING_ENABLED	true	Record interactions and learn from them
LEARNING_STORE_RAW_QUERIES	false	Store queries without scrubbing personal data
AUDIT_STORE_RAW_QUERIES	false	Keep questions in audit entries without scrubbing personal data; independent of LEARNING_STORE_RAW_QUERIES
RECEIPT_RETENTION_DAYS	90	Days a receipt is kept; the server deletes older ones at startup and then once a day, with the document versions only they kept, and records each prune in the audit log. 0 keeps receipts forever
LEARNING_SESSION_TIMEOUT_MINUTES	30	Idle minutes that end a session for rephrase detection
LEARNING_PROMOTE_EVERY_N_QUERIES	50	Interactions between promotion runs
LEARNING_MIN_SUCCESS_RATE	0.6	Lowest success rate for a learned rewrite to be used
LEARNING_REWRITE_BYPASS_THRESHOLD, LEARNING_REWRITE_BYPASS_MIN_SAMPLES	0.85, 5	A learned rewrite at or above this success rate and sample count skips the rewrite model
STRATA_LOCAL_ONLY	false	Refuse to start while any provider would send content off this machine, and load models from local files only; see Where your data goes
LOG_LEVEL	INFO	Logs on stderr: JSON lines, or readable console lines at DEBUG

Changing the embedding model takes a re-embed of every layer; see Changing the embedding model.