Configuration

How to bind a single deployment to stores, model seats, budgets, and optional exporters. This page is operator-facing and agent-scannable. Run-through: Getting started · Deployment.

TL;DR

One deployment id = one trust domain. Changing REMEMBERSTACK_SELFHOST_DEPLOYMENT_ID creates a different deployment identity.

Distribution surfaces

Environment map (self-host)

Authoritative template: repository .env.example.

Identity and API

Signed credential scopes

A credential verified through REMEMBERSTACK_SELFHOST_API_SIGNING_KEYS names exactly one of three scopes:

Unlisted routes require write. A new route therefore stays unavailable to narrow credentials until it is classified deliberately, and an unknown scope on a signed credential is refused rather than downgraded.

An ingest credential also cannot assert X-Ingest-Principal-Kind or X-Ingest-Principal-Ref. Those immutable attribution headers are ignored unless REMEMBERSTACK_SELFHOST_TRUSTED_PRINCIPAL_SOURCE is enabled and the caller has full write authority. The unscoped API_BEARER_BIND shared secret is unrestricted and qualifies; a narrow credential's attribution headers are ignored while its otherwise valid upload still succeeds.

Calling a deployment from a browser

A browser refuses a cross-origin request before it is sent unless the server says the origin is allowed. The credential is never examined and the perimeter never runs, so the failure looks like the deployment being down — which is why this is configuration rather than something that can be worked around in a client.

REMEMBERSTACK_SELFHOST_BROWSER_ORIGINS names the origins permitted to do that. It is empty by default: a deployment nobody told about an app should not advertise anything, and a permissive default would hand every website on the internet the ability to make authenticated requests from a visitor's browser.

Each entry must be an origin exactly as a browser sends it: https://app.example.com, optionally with a port, and nothing else — lowercase scheme and host, no path, no query, no userinfo, no wildcard.

The reason is worth knowing. The match is a byte comparison against the request's Origin header, so a value that is not exactly what a browser sends can never match — it does not widen the perimeter, it silently closes it. An operator who writes https://*.example.com and watches the deployment start cleanly believes they have granted a subdomain tree; they have granted nothing, and will go looking for the fault in their app.

Validation is deliberately small: scheme, structure, case and port, and no finer judgement of hostname syntax than that. A rule strict enough to catch every impossible name also refuses real ones — underscores, trailing dots and IDNA2008 labels are all things browsers send and naive checks reject. DNS fails loudly and specifically for a name that does not exist, which is a better error than a startup refusal for a host that does. The origins actually installed are logged when the API starts, so a typo is something you can see rather than infer.

Credentialed CORS is disabled (allow_credentials is off). Be precise about what that does: it stops the response being shared with a page that made the request in credentials: "include" mode. It does not block an ordinary bearer call — a request carrying Authorization is preflighted, and that preflight succeeds because the header is on the allowlist. What is refused is a page trying to have cookies or client certificates count as authentication across the origin boundary. It does not reach into the browser and stop a page attaching cookies to a simple cross-origin request in the first place; that request may still be sent, and only its response is withheld.

So the honest statement is that no credentialed cross-origin call can succeed here, not that cookies can never leave the browser. The credential this surface expects travels in Authorization, and same-origin traffic is unaffected by any of it.

Only GET and POST are advertised, with Authorization and Content-Type. Sending Authorization makes the request preflighted, and that preflight succeeds because the header is on the allowlist — it is the browser's credentials: "include" mode, not the presence of a bearer header, that would need credentialed CORS.

Preflight responses are cached for ten minutes, which is worth knowing when you remove an origin: a browser that has already been told "yes" may keep that answer for up to that long, so revoking the credential is what ends access immediately, not editing this list.

The CORS layer is installed outermost, so refusals raised by other layers — an oversize body, an exhausted spend ceiling — reach the browser as the errors they are rather than as opaque network failures.

A non-default port is part of an origin and may be included: https://app.example.com:8443 (1–65535, but not 443 — a browser omits the default port from Origin, so writing it out matches nothing). https://localhost and https://localhost:3000 are accepted, so a self-hoster can develop against a local https listener.

Several origins are comma-separated, and the whole list is validated together — a stray comma is a refusal, not a silently skipped entry, because a list that starts with fewer origins than you wrote hides the missing one until somebody's browser is turned away.

REMEMBERSTACK_SELFHOST_BROWSER_ORIGINS=https://app.remember.dev

Compose passes this through, so it can be set in .env beside the other deployment settings.

Stores (Compose local defaults)

Replace every local-only secret before any non-isolated use.

Ingest admission

Managed deployments also configure content-free billing receipts. These values are fleet-authored as one all-or-nothing set; ordinary self-host installations leave all of them unset and do not start the Compose managed profile.

Conversion routes

The mistral_ocr route is BYO-key (provider-backed; off unless routed):

Every output-affecting mistral_ocr option is folded into the converter version, so changing the model or an option re-converts affected documents as new representations instead of replaying old ones.

The image_ocr_description route runs both dedicated OCR (the Mistral OCR adapter) and one independent vision-LLM description call for every supported static image. There is no classifier. OCR-only routing of images via mistral_ocr remains available if you bind it explicitly; the dual-lane adapter is the image route this engine ships for pictures. Supported input MIME types are static image/png and image/jpeg (the documented overlap of Mistral OCR image_url types and OpenRouter image-input types). WebP, GIF, HEIC, TIFF, AVIF, SVG, and animated PNG/JPEG are not in the shipped set. Before either provider call, Pillow inspects the original bytes (header/structure, detected MIME, animation, dimensions, and pixel count) and the tighter of the OCR and image byte ceilings is enforced. The original bytes stay unmodified in raw storage.

Both provider keys are required when any route names image_ocr_description; composition refuses to start without them:

The description lane uses OpenRouter's chat-completions image input (content parts with type: image_url and a data:<mime>;base64,… URL). Description accounting reuses the OpenRouter adapter's fail-closed path: inline usage, then GET generation metadata for the existing generation id — never a second paid generation, never invented zero cost. The representation manifest records the provider-echoed model, including when a description checkpoint is reused. Successful empty OCR (no visible text) is success; a provider failure is not treated as empty. Both lanes must succeed before a representation is published. Successful lane output is checkpointed privately under the source identity (endpoint, MIME, prompt/normalizer versions, model, and acceptance/output bounds) so a retry or worker restart does not repeat an already completed call. A crash between the provider response and durable persistence can still repeat a call. A corrupt occupied checkpoint is a terminal conversion error, not another paid recall.

Every output-affecting description option is folded into the converter version. Changing only one lane's model, endpoint, or options invalidates that lane's checkpoint and produces a new representation.

Live-graph resources

Size these four values together with PostgreSQL shared memory and host reserve. Increasing pool or concurrency independently multiplies worst-case memory; the managed service applies a stricter host-level admission calculation.

Interactive retrieval resources

Keep maximum concurrency at or below pool size. facts_context also clamps every admitted PostgreSQL statement and transaction to its remaining operation deadline; pool saturation returns a typed boundary rather than using the worker/write pool.

Provider (OpenRouter)

Embedding routing policy notes: design/operations/openrouter-embedding-routing.md in the repo.

Model seats (optional overrides)

Pin explicit IDs for reproducible runs. Unset values fall back to deployment profile defaults.

Structure honesty: routine skeleton construction is deterministic. Bounded summary/role/check calls still run; STRUCTURER is not “the whole document structure model.”

Smoke conversion route is Markdown unless you register more converters on the deployment.

P1 search indexes (D94)

P1 lives in PostgreSQL. Migrations own the pgvector HNSW and pg_textsearch BM25 indexes, while ordinary ingestion transactions update the search rows and embedding attestations. There is no separate search-store path, maintenance worker, or search-index environment namespace to configure.

Spend ceilings (optional)

export REMEMBERSTACK_WORK_BUDGETS='[
  {
    "deployment_id":"<deployment-uuid>",
    "stage":"extract_claims",
    "lane":"steady",
    "window_seconds":86400,
    "ceiling_usd":"10.00"
  }
]'

• JSON list; omit a route → unlimited
• Use null lane for unlaned K/P routes
• Exhaustion parks healthy work until the window ends — does not burn handler attempts or invent a failure
• Inspect: remember budget inspect --deployment <uuid> (needs [server])

Observability (optional, fail-closed off)

Exporters stay disabled until env is non-empty.

What is not sent: request bodies, local vars, breadcrumbs, PII, prompts/completions, exception message text as free-form dumps. Worker tags stay stage/lane/processing id. Postgres + JSON telemetry remain authoritative for retries.

Conversion and connectors

See Ingestion and Lifecycle.

What configuration is not

• Not multi-tenant control-plane config
• Not a hosted SLA or billing product
• Not free-tier model routing for publication benchmarks
• Not secret storage — use your secret manager outside git

Progressive disclosure

Next

• Deployment
• Troubleshooting
• Evaluation

Vertex generation adapter

Library integrations can bind VertexModelProvider explicitly through the model provider port. This does not change the default self-host provider. Generation uses Vertex; embeddings must be routed separately to their configured provider.

VertexSettings reads REMEMBERSTACK_VERTEX_*. Set PROJECT_ID for the billed Google Cloud project; LOCATION defaults to global. MAX_COMPLETION_TOKENS defaults to 128000, the documented Gemma 4 26B A4B IT output maximum, verified September 14, 2026. This is an allowance, not a requested output length. Provider context limits still apply. Set it explicitly when binding another model.

TIMEOUT_S is optional and defaults to no client deadline, allowing slow generations to finish. Set a positive number only when an operator deadline is intended. Monitor running calls: a stalled service can otherwise wait indefinitely. Invalid structured responses remain errors with available token usage retained; allowing more output does not make an invalid response usable.

generate() stays a single synchronous call. The adapter receives the completion as server-sent events on the documented Chat Completions route, assembles the full text, and still requires a complete stop finish, schema-valid JSON, and provider usage before it succeeds. Truncated or dropped streams are errors. Missing usage is never billed as zero. HTTP 429 is retried only before a stream has started.