Configuration variables

This page lists every environment variable that RememberStack's engine and the remember package read. Configuration explains how they reach the containers.

The variables in Client are read by the remember CLI, Python client and MCP server on your own machine. Every other section applies to a self-hosted engine.

The shipped compose.yaml hands every variable in .env to the engine containers. It sets three itself, overriding .env: REMEMBERSTACK_DATABASE_URL, REMEMBERSTACK_MINIO_ENDPOINT_URL and the container's REMEMBERSTACK_SELFHOST_API_PORT (Configuration).

Booleans accept true/false (also 1/0). An empty value counts as unset for optional settings.

Client

Variable	Default	Type	Purpose
`REMEMBER_API_URL`	`http://127.0.0.1:8000`	URL	The deployment endpoint.
`REMEMBER_API_KEY`	unset	secret	The API key, raw or as `Bearer …`.
`REMEMBER_PROJECT`	unset	id or name	The project to use when the key covers several.
`REMEMBER_CONFIG_DIR`	`$XDG_CONFIG_HOME/remember` or `~/.config/remember`	path	Where `credentials.json` lives.
`REMEMBERSTACK_INTERNAL_OPS`	`false`; `true` in the engine image	bool	Enables `remember ops`, which works only inside the engine image. Also read as `REMEMBER_INTERNAL_OPS`.
`REMEMBERSTACK_MCP_INGEST_ROOTS`	empty	JSON array or comma-separated paths	Directories from which the local MCP server may ingest a file by path. Empty refuses path ingest.
`REMEMBERSTACK_MCP_PATH_READ_MAX_BYTES`	`268435456`	int > 0	Largest file the local MCP server reads for path ingest.
`XDG_CONFIG_HOME`	unset	path	Standard base for `REMEMBER_CONFIG_DIR` and for agent configuration that `remember setup` writes.
`APPDATA`	unset	path	Windows base for agent configuration that `remember setup` writes.

The CLI and the Python client read REMEMBER_API_KEY, REMEMBER_API_URL and REMEMBER_PROJECT the same way: a flag or argument wins over the variable, and the variable wins over the credential file (CLI).

Compose file only

Read by compose.yaml from .env, not by the engine.

Variable	Default	Type	Purpose
`REMEMBERSTACK_POSTGRES_USER`	required	string	PostgreSQL user; also used to build `REMEMBERSTACK_DATABASE_URL`.
`REMEMBERSTACK_POSTGRES_PASSWORD`	required	string	PostgreSQL password. `.env.example` ships none; generate it at install.
`REMEMBERSTACK_POSTGRES_DB`	required	string	PostgreSQL database name.
`REMEMBERSTACK_POSTGRES_MAX_CONNECTIONS`	`300`	int	Read by Compose only. PostgreSQL `max_connections`. The default stack's ceiling is 215 connections; see Database connections.
`REMEMBERSTACK_BUILD_REVISION`	empty	string	Build argument when Compose builds the app image; stamped into it and reported by `GET /deployment` as `build_revision`.

Deployment and API

Variable	Default	Type	Purpose
`REMEMBERSTACK_DATABASE_URL`	required	SQLAlchemy URL	PostgreSQL connection, `postgresql+psycopg://user:password@host:5432/db`. Compose builds it from the `REMEMBERSTACK_POSTGRES_*` values.
`REMEMBERSTACK_SELFHOST_DEPLOYMENT_ID`	required	UUID	The deployment's identity; `.env.example` ships none, generate it at install. Fixed after the first start.
`REMEMBERSTACK_SELFHOST_DEPLOYMENT_SLUG`	`local`	string	Short name. Fixed after the first start. Default Sentry environment.
`REMEMBERSTACK_SELFHOST_DEPLOYMENT_NAME`	`Local memory`	string	Display name. Fixed after the first start.
`REMEMBERSTACK_SELFHOST_DEFAULT_LANGUAGE`	`en`	string	Default language of the deployment. Fixed after the first start.
`REMEMBERSTACK_SELFHOST_API_HOST`	`0.0.0.0`	string	Address the API listens on inside the container.
`REMEMBERSTACK_SELFHOST_API_PORT`	`8000`	int 1–65535	Port inside the container (Compose sets `8000`). In `.env` it is the host port Compose publishes.
`REMEMBERSTACK_SELFHOST_API_PUBLISH_ADDRESS`	`127.0.0.1`	host address	Read by Compose only. Host address Compose publishes the API port on. Set a token before changing it; see Opening the API to other machines.
`REMEMBERSTACK_SELFHOST_INGEST_BODY_MAX_BYTES`	unset (no cap)	int > 0	Largest `POST /ingest` body; larger uploads get `413`.
`REMEMBERSTACK_SELFHOST_BROWSER_ORIGINS`	empty	comma-separated https origins; http only on `localhost`, `127.0.0.1` or `[::1]`	Browser origins allowed by CORS.
`REMEMBERSTACK_SELFHOST_TRUSTED_PRINCIPAL_SOURCE`	`false`	bool	Believe `X-Ingest-Principal-*` headers on `POST /ingest`.
`REMEMBERSTACK_SELFHOST_API_ADMISSION_KEY_PER_MINUTE`	unset (no limit)	int ≥ 0; `0` = no limit	Optional. Requests per minute per credential (bursts of a quarter of it). Over it: `429` `rate_limited`.
`REMEMBERSTACK_SELFHOST_API_ADMISSION_KEY_IN_FLIGHT`	unset (no limit)	int ≥ 0; `0` = no limit	Optional. Requests running at once per credential. Over it: `429` `concurrency_limited`.
`REMEMBERSTACK_SELFHOST_API_ADMISSION_DEPLOYMENT_PER_MINUTE`	unset (no limit)	int ≥ 0; `0` = no limit	Optional. Requests per minute for the whole deployment (bursts of a quarter of it).
`REMEMBERSTACK_SELFHOST_API_ADMISSION_DEPLOYMENT_IN_FLIGHT`	unset (no limit)	int ≥ 0; `0` = no limit	Optional. Requests running at once for the whole deployment.

Storage

Variable	Default	Type	Purpose
`REMEMBERSTACK_MINIO_ENDPOINT_URL`	required	URL	S3-compatible endpoint. Compose sets `http://object-store:8333`.
`REMEMBERSTACK_MINIO_ACCESS_KEY`	required	secret	Object-store access key; also the bundled SeaweedFS store's admin access key. `.env.example` ships none; generate it at install.
`REMEMBERSTACK_MINIO_SECRET_KEY`	required	secret	Object-store secret key; also the bundled SeaweedFS store's admin secret key. `.env.example` ships none; generate it at install.
`REMEMBERSTACK_MINIO_REGION`	`us-east-1`	string	S3 region name used for signing.
`REMEMBERSTACK_SELFHOST_RAW_BUCKET_NAME`	`remember-raw`	string	Bucket for original files. Fixed after the first start.
`REMEMBERSTACK_SELFHOST_ARTIFACTS_BUCKET_NAME`	`remember-artifacts`	string	Bucket for converted Markdown and artifacts. Fixed after the first start.
`REMEMBERSTACK_SELFHOST_CORPUSFS_BUCKET_NAME`	`remember-corpusfs`	string	Bucket for filesystem-view snapshots. Fixed after the first start.
`REMEMBERSTACK_SELFHOST_RAW_MOUNT_ROOT`	unset	path	Default `--raw-root` for `mounts`.
`REMEMBERSTACK_SELFHOST_ARTIFACTS_MOUNT_ROOT`	unset	path	Default `--artifacts-root` for `mounts`.
`REMEMBERSTACK_SELFHOST_PROJECTION_WORK_ROOT`	`/var/lib/rememberstack/projection-work`	path	Working directory created by `setup`.
`REMEMBERSTACK_SELFHOST_FORGET_MANIFEST_ROOT`	`/var/lib/rememberstack/forget-manifests`	path	Where hard-forget manifests are read.
`REMEMBERSTACK_SELFHOST_MIGRATION_CONFIG`	`alembic.ini`	path	Alembic configuration used by `setup`.

Authentication

Variable	Default	Type	Purpose
`REMEMBERSTACK_SELFHOST_API_BEARER_TOKEN`	unset	secret	Shared secret with `write` scope. Setting it turns authentication on.
`REMEMBERSTACK_SELFHOST_API_BEARER_BIND`	unset	`<deployment-uuid>:<sha256-hex>`	The shared secret's digest instead of the secret. Must match the token if both are set.
`REMEMBERSTACK_SELFHOST_REQUIRE_API_AUTH`	`false`	bool	Refuse to start unless the token, the bind or the key issuer is set.
`REMEMBERSTACK_SELFHOST_API_KEY_ISSUER`	unset	URL	The key issuer, matched exactly against `iss`. Setting it turns signed keys on and requires the tenant id and both URLs below.
`REMEMBERSTACK_SELFHOST_API_KEY_TENANT_ID`	unset	string	The issuer's tenant id for this deployment. Keys carry `aud = org:<this>` and `org = <this>`.
`REMEMBERSTACK_SELFHOST_API_KEY_PROJECT_ID`	the deployment id	string	The issuer's project id for this deployment, matched against a key's `projects`.
`REMEMBERSTACK_SELFHOST_API_SIGNING_KEYS_URL`	unset	http(s) URL	Where the issuer's JWKS of Ed25519 public keys is fetched.
`REMEMBERSTACK_SELFHOST_API_REVOCATION_URL`	unset	http(s) URL	Where the issuer's signed revocation document for this deployment is fetched.
`REMEMBERSTACK_SELFHOST_API_KEY_REFRESH_S`	`60`	float > 0	Seconds between fetches of the key set and the revocation document.
`REMEMBERSTACK_SELFHOST_API_REVOCATION_MAX_AGE_S`	`3600`	float > 0	Maximum age of the accepted revocation document; past it every signed key is refused.

See Authentication and scopes.

Pools and workers

Variable	Default	Type	Purpose
`REMEMBERSTACK_SELFHOST_WORKER_RATE_PER_S`	`20.0`	float > 0	Claims per second per worker process.
`REMEMBERSTACK_SELFHOST_WORKER_BURST`	`20.0`	float ≥ 1	Claim burst per worker process.
`REMEMBERSTACK_SELFHOST_WORKER_FALLBACK_POLL_S`	`5.0`	float > 0	Poll interval when no notification arrives.
`REMEMBERSTACK_SELFHOST_WORKER_SESSION_S`	`3600.0`	float > 0	Length of one worker session.
`REMEMBERSTACK_SELFHOST_RETRIEVAL_POOL_SIZE`	`4`	int 1–32	Connections for retrieval in the API.
`REMEMBERSTACK_SELFHOST_RETRIEVAL_POOL_TIMEOUT_S`	`1.0`	float, max 30	Wait for a retrieval connection.
`REMEMBERSTACK_SELFHOST_RETRIEVAL_MAX_CONCURRENCY`	`4`	int 1–32, ≤ pool size	Retrievals at once.
`REMEMBERSTACK_SELFHOST_GRAPH_POOL_SIZE`	`4`	int 1–32	Connections for graph queries in the API.
`REMEMBERSTACK_SELFHOST_GRAPH_POOL_TIMEOUT_S`	`1.0`	float, max 30	Wait for a graph slot.
`REMEMBERSTACK_SELFHOST_GRAPH_MAX_CONCURRENCY`	`2`	int 1–32, ≤ pool size	Graph queries at once.
`REMEMBERSTACK_SELFHOST_GRAPH_WORK_MEM_KIB`	`16384`	int 64–65536	PostgreSQL `work_mem` per graph query.
`REMEMBERSTACK_WORK_RETRY_BACKOFF_BASE_S`	`2.0`	float	First retry delay; doubles per attempt.
`REMEMBERSTACK_WORK_RETRY_BACKOFF_MAX_S`	`60.0`	float	Longest retry delay.
`REMEMBERSTACK_WORK_BUDGETS`	`[]`	JSON list	Spend ceilings per deployment, stage and lane (Operating).
`REMEMBERSTACK_E1_EMBED_BATCH_SIZE`	`64`	int 1–512	Chunks per embedding request.
`REMEMBERSTACK_P1_EMBED_BATCH_SIZE`	`64`	int 1–1024	Claims or facts per embedding request.

Model provider

Variable	Default	Type	Purpose
`REMEMBERSTACK_OPENROUTER_API_KEY`	required	string	OpenRouter key for every model call.
`REMEMBERSTACK_OPENROUTER_BASE_URL`	`https://openrouter.ai/api/v1`	URL	OpenRouter API address.
`REMEMBERSTACK_OPENROUTER_TIMEOUT_S`	`120.0`	float > 0	Per-request timeout.
`REMEMBERSTACK_OPENROUTER_MAX_COMPLETION_TOKENS`	`32000`	int ≥ 1	Output allowance per chat call, reasoning included.
`REMEMBERSTACK_OPENROUTER_CHAT_PROVIDER_ORDER`	unset	comma-separated or JSON list	Preferred chat providers, with fallback.
`REMEMBERSTACK_OPENROUTER_CHAT_PROVIDER_ONLY`	unset	comma-separated or JSON list	Only these chat providers, no fallback. Exclusive with the order.
`REMEMBERSTACK_OPENROUTER_EMBEDDING_PROVIDER_ORDER`	unset	comma-separated or JSON list	Preferred embedding providers, with fallback.
`REMEMBERSTACK_OPENROUTER_EMBEDDING_PROVIDER`	unset	string	The one embedding provider, no fallback. The order wins if both are set.
`REMEMBERSTACK_OPENROUTER_ZDR`	`false`	bool	Only zero-data-retention endpoints for chat.
`REMEMBERSTACK_OPENROUTER_REASONING_EFFORT`	unset	`none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`	Reasoning effort for every chat call.
`REMEMBERSTACK_OPENROUTER_REASONING_EFFORT_MAP`	unset	JSON object	Reasoning effort per model id; wins over the global value.
`REMEMBERSTACK_OPENROUTER_CHAT_THROTTLE_RETRIES`	`3`	int ≥ 0	Retries of a chat call after HTTP 429, outside the work attempts.
`REMEMBERSTACK_OPENROUTER_CHAT_UPSTREAM_OVERLOAD_MAX_RETRY_AFTER_S`	`30.0`	float > 0	Longest wait before retrying an overloaded provider.
`REMEMBERSTACK_OPENROUTER_INVALID_COMPLETION_CAPTURE_DIR`	unset	absolute path	Debug only: keep schema-invalid model answers as files.
`REMEMBERSTACK_TYPESAFE_API_KEY`	unset	string	TypeSafe AI key, required with the `jev` fact engine. Also read as `TYPESAFE_AI_API_KEY`.
`REMEMBERSTACK_TYPESAFE_MODEL`	`jev-latest`	string	TypeSafe model.
`REMEMBERSTACK_TYPESAFE_BASE_URL`	`https://api.typesafe.ai/v1`	URL	TypeSafe API address.
`REMEMBERSTACK_TYPESAFE_TIMEOUT_S`	`30.0`	float	TypeSafe request timeout.

Model seats

See Models and providers.

Variable	Default	Type	Purpose
`REMEMBERSTACK_STRUCTURER_MODEL`	`openai/gpt-5.6-luna`	model id	Structure fallback: section anchors when headings are unusable.
`REMEMBERSTACK_STRUCTURER_MAX_PROMPT_CHARS`	`200000`	int ≥ 1000	Largest prompt sent to the structure fallback.
`REMEMBERSTACK_STRUCTURER_MIN_HEADING_DENSITY_PER_10K`	`0.25`	float ≥ 0	Structure check: minimum headings per 10,000 characters.
`REMEMBERSTACK_STRUCTURER_MAX_OVERSIZED_LEAF_RATIO`	`0.75`	float 0–1	Structure check: largest share of oversized sections.
`REMEMBERSTACK_STRUCTURER_MIN_BLOCKS_FOR_LLM`	`8`	int ≥ 1	Accepted for compatibility; not used.
`REMEMBERSTACK_SKELETON_CHECK_MODEL`	`z-ai/glm-4.7-flash`	model id	Checks a proposed section outline.
`REMEMBERSTACK_ROLE_MODEL`	`z-ai/glm-4.7-flash`	model id	Classifies section roles.
`REMEMBERSTACK_SUMMARY_MODEL`	`z-ai/glm-4.7-flash`	model id	Section summaries.
`REMEMBERSTACK_E2_EXTRACT_MODEL`	`openai/gpt-5.6-luna`	model id	Claim selection and extraction.
`REMEMBERSTACK_E3_NORMALIZE_MODEL`	`openai/gpt-5.6-luna`	model id	Relation normalisation.
`REMEMBERSTACK_OBS_SMALL_MODEL`	`openai/gpt-5.6-luna`	model id	Entity resolution.
`REMEMBERSTACK_FACT_MODEL`	`openai/gpt-5.6-luna`	model id	Fact adjudication with the `prompt` engine.
`REMEMBERSTACK_FACT_ADJUDICATION_ENGINE`	`prompt`	`prompt` or `jev`	Fact adjudication engine. Also read as `REMEMBERSTACK_FACT_ENGINE`.
`REMEMBERSTACK_FACT_CONFIDENCE_FLOOR`	`0.75`	float 0–1	Below this, both the new statement and the existing fact are kept.
`REMEMBERSTACK_FACT_FALLBACK_TO_PROMPT`	`false`	bool	Fall back to `prompt` when a `jev` call fails. Also read as `REMEMBERSTACK_TYPESAFE_FALLBACK_TO_PROMPT`.
`REMEMBERSTACK_P1_EMBEDDING_MODEL`	`qwen/qwen3-embedding-8b`	model id, 1,536-dim output	Every embedding, including search queries. Fixed once anything is embedded.

Converters

See File formats and converters.

Variable	Default	Type	Purpose
`REMEMBERSTACK_SELFHOST_CONVERSION_ROUTES`	Markdown and plain text → `passthrough`; HTML, `.docx`, `.pptx`, `.xlsx` → `markitdown` (the table)	JSON object	MIME type → converter. Replaces the default table.
`REMEMBERSTACK_MISTRAL_OCR_API_KEY`	unset	secret	Mistral key; required by `mistral_ocr` and `image_ocr_description`.
`REMEMBERSTACK_MISTRAL_OCR_BASE_URL`	`https://api.mistral.ai`	URL	Mistral API address.
`REMEMBERSTACK_MISTRAL_OCR_MODEL`	`mistral-ocr-latest`	string	OCR model.
`REMEMBERSTACK_MISTRAL_OCR_TIMEOUT_S`	`300`	float > 0	OCR request timeout.
`REMEMBERSTACK_MISTRAL_OCR_MAX_DOCUMENT_BYTES`	`50000000`	int > 0	Largest file sent to OCR.
`REMEMBERSTACK_MISTRAL_OCR_INCLUDE_IMAGES`	`true`	bool	Keep embedded images.
`REMEMBERSTACK_MISTRAL_OCR_TABLE_FORMAT`	`markdown`	`markdown` or `html`	Table format.
`REMEMBERSTACK_MISTRAL_OCR_EXTRACT_HEADERS_AND_FOOTERS`	`true`	bool	Extract headers and footers separately.
`REMEMBERSTACK_MISTRAL_OCR_CONFIDENCE_GRANULARITY`	`word`	`word` or `page`	Confidence score detail.
`REMEMBERSTACK_MISTRAL_OCR_KEEP_PROVIDER_RESPONSE`	`true`	bool	Keep the provider response as an artifact.
`REMEMBERSTACK_MISTRAL_OCR_PRICE_USD_PER_1000_PAGES`	`1`	decimal ≥ 0	Price used to record OCR cost.
`REMEMBERSTACK_IMAGE_DESCRIPTION_API_KEY`	unset	secret	OpenRouter key for image descriptions; required by `image_ocr_description`.
`REMEMBERSTACK_IMAGE_DESCRIPTION_BASE_URL`	`https://openrouter.ai/api/v1`	URL	API address.
`REMEMBERSTACK_IMAGE_DESCRIPTION_MODEL`	`google/gemini-2.5-flash`	model id	Vision model; must accept image input.
`REMEMBERSTACK_IMAGE_DESCRIPTION_TIMEOUT_S`	`120.0`	float > 0	Request timeout.
`REMEMBERSTACK_IMAGE_DESCRIPTION_MAX_IMAGE_BYTES`	`10000000`	int > 0	Largest image.
`REMEMBERSTACK_IMAGE_DESCRIPTION_MAX_IMAGE_PIXELS`	`40000000`	int > 0	Largest width × height.
`REMEMBERSTACK_IMAGE_DESCRIPTION_MAX_IMAGE_WIDTH`	`16000`	int > 0	Largest width.
`REMEMBERSTACK_IMAGE_DESCRIPTION_MAX_IMAGE_HEIGHT`	`16000`	int > 0	Largest height.
`REMEMBERSTACK_IMAGE_DESCRIPTION_MAX_DESCRIPTION_CHARS`	`16000`	int > 0	Longest description.
`REMEMBERSTACK_IMAGE_DESCRIPTION_MAX_TOKENS`	`4096`	int ≥ 1	Output allowance of the description call.
`REMEMBERSTACK_IMAGE_DESCRIPTION_LANE_CONCURRENCY`	`2`	int 1–2	OCR and description in parallel (2) or in turn (1).

Operations

Variable	Default	Type	Purpose
`REMEMBERSTACK_OPERATIONAL_SAMPLE_LIMIT`	`20`	int 1–1000	Cap on lists in `remember ops inspect`.
`REMEMBERSTACK_P3_SNAPSHOT_PREFIX`	`corpusfs/snapshots`	string	Object prefix of filesystem-view snapshots.
`REMEMBERSTACK_P3_FACETS`	`["by-source", "by-time", "by-topic"]`	JSON array	Top-level view directories of the corpus tree.
`REMEMBERSTACK_P3_SHARD_THRESHOLD`	`150`	int ≥ 2	Entries above which a directory is split.
`REMEMBERSTACK_COST_EXPORT_BIND`	unset	`host:port`, `[ipv6]:port` or `unix:/path`	Address of the HTTP cost export. Unset: off.
`REMEMBERSTACK_COST_EXPORT_TOKEN`	unset	secret, ≥ 32 bytes	Bearer token for the cost export.

Observability

Variable	Default	Type	Purpose
`REMEMBERSTACK_SENTRY_DSN`	unset	secret	Sentry-protocol DSN; unset keeps error tracking off.
`REMEMBERSTACK_SENTRY_ENVIRONMENT`	deployment slug	string	Environment name on events.
`REMEMBERSTACK_SENTRY_SAMPLE_RATE`	`1.0`	float 0–1	Share of error events sent.
`REMEMBERSTACK_LANGFUSE_ENABLED`, `_HOST`, `_PUBLIC_KEY`, `_SECRET_KEY`, `_CA_FILE`, `_RUN_TAG`	`false` / empty		Read only by the benchmark harness; no effect on the engine.
`LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`, `LANGFUSE_HOST`	empty		Read only by the benchmark harness; no effect on the engine.

Knowledge plane and other unused settings

These are read by code in the engine that no shipped command runs. Setting them has no effect on a Compose deployment.

Variables	Read by
`REMEMBERSTACK_K_PLANNER_PLANNER_MODEL`, `_PLANNER_MODEL_FAMILY`, `_REFLECTION_MODEL`, `_REFLECTION_MODEL_FAMILY`, `_TIMEOUT_SECONDS`, `_AUTO_APPLY_MAX_EXPECTED_IMPACT`, `_TRANSCRIPT_PREFIX`	Knowledge-page planner
`REMEMBERSTACK_K_WRITER_MODEL`, `_TIMEOUT_SECONDS`, `_RESIDUE_CLAIM_LIMIT`, `_EVIDENCE_CLAIMS_PER_FACT`, `_TRANSCRIPT_PREFIX`	Knowledge-page writer
`REMEMBERSTACK_K_DRIVER_MAX_PARALLEL_PAGES`	Knowledge-page driver
`REMEMBERSTACK_K_CODEX_EXECUTABLE`, `REMEMBERSTACK_K_WRITER_CODEX_EXECUTABLE` (default `codex`)	Knowledge-page agent adapter
`REMEMBERSTACK_SYNC_DEBOUNCE_QUIET_SECONDS` (default `120`), `REMEMBERSTACK_SYNC_LANE` (default `steady`)	Watched-directory sync loop
`REMEMBERSTACK_BACKFILL_BATCH_SIZE` (default `500`)	Backfill seeder
`REMEMBERSTACK_VERTEX_PROJECT_ID`, `_LOCATION` (default `global`), `_TIMEOUT_S`, `_MAX_COMPLETION_TOKENS` (default `128000`), `_PRICE_TABLE_USD_PER_MILLION`, `_THROTTLE_RETRY_DELAYS_S`	Google Vertex model adapter, used by the benchmark harness