Configuration

RememberStack is configured entirely through environment variables. There is no configuration file inside the engine. This page explains how the variables reach the containers, which ones matter first, and which ones cannot change later. Configuration variables lists every variable with its default.

How the engine reads settings

Each part of the engine reads its own group of variables when the process starts, through typed settings classes (pydantic-settings). Each group has a prefix:

Three rules follow from this:

• The engine reads only the process environment. It does not open a .env file itself. In the Compose setup, Docker Compose reads .env and passes values into the containers.
• Values are checked at start. A malformed value (a non-UUID deployment id, a pool concurrency larger than its pool, a converter route naming an unknown converter) stops the process with an error that names the variable. It never starts half-configured.
• Blank means unset. Compose turns an unset ${VAR:-} into an empty string; the engine treats an empty value as "use the default" for the optional settings.

What Compose passes through

compose.yaml loads your .env into every engine container (env_file), so any engine variable you put in .env takes effect: for example REMEMBERSTACK_IMAGE_DESCRIPTION_API_KEY, REMEMBERSTACK_COST_EXPORT_BIND, the worker rate settings, REMEMBERSTACK_OPENROUTER_ZDR or REMEMBERSTACK_WORK_BUDGETS.

Each engine service also has an environment: list. It supplies defaults and three values Compose sets itself, which win over .env:

A variable exported in your shell overrides .env only if it is on the environment: list, because Compose substitutes shell values into that list but reads env_file from the file alone. Put settings in .env.

Apply a change

docker compose up -d

Compose recreates every container whose configuration changed. setup runs again first, then the API and workers restart with the new values. A running process never picks up a changed variable on its own.

What to change first

For a machine only you can reach, these settings matter:

Compose publishes the API on 127.0.0.1 only. To let other machines reach it, set REMEMBERSTACK_SELFHOST_API_BEARER_TOKEN and REMEMBERSTACK_SELFHOST_REQUIRE_API_AUTH=true, then REMEMBERSTACK_SELFHOST_API_PUBLISH_ADDRESS (Opening the API to other machines).

To accept more than Markdown and plain text, set REMEMBERSTACK_SELFHOST_CONVERSION_ROUTES (File formats and converters).

Settings fixed after the first start

The first setup records these in the database, and later runs refuse to start if they change. A database holds one deployment, so a new deployment id is refused too; it does not start a second, empty deployment.

• REMEMBERSTACK_SELFHOST_DEPLOYMENT_ID
• REMEMBERSTACK_SELFHOST_DEPLOYMENT_SLUG
• REMEMBERSTACK_SELFHOST_DEPLOYMENT_NAME
• REMEMBERSTACK_SELFHOST_DEFAULT_LANGUAGE (default en)
• the three bucket names, REMEMBERSTACK_SELFHOST_RAW_BUCKET_NAME, …_ARTIFACTS_BUCKET_NAME and …_CORPUSFS_BUCKET_NAME

setup also refuses a new REMEMBERSTACK_P1_EMBEDDING_MODEL once anything has been embedded; see Models and providers.

The client side

The remember CLI and Python client read a separate, small set of variables on your own machine, most importantly REMEMBER_API_URL and REMEMBER_API_KEY. They are listed at the top of Configuration variables.