Self-host Deployment

Environment variables, model seats, and budgets: Configuration.
When something fails: Troubleshooting.

The repository ships Docker Compose for a fresh, single-deployment self-host. It starts PostgreSQL, MinIO, the HTTP API, and one process for each of the ten implemented continuous document routes: conversion, structure, chunking, chunk embedding, claim extraction, normalization, supersession, claim embedding, reconciliation, and fact labeling. P1 search writes occur in those workers' ordinary PostgreSQL transactions; there is no separate search-store or index maintenance process. The one-shot setup service applies every migration, provisions object buckets, bootstraps the deployment, and seeds the four canonical assured operations plus the examples.* saved queries. The RememberStack, rememberstack, and remember names used here are final. Do not expose this stack to untrusted traffic.

Model seats are per-deployment environment bindings. The document-structure stage uses four: REMEMBERSTACK_SKELETON_CHECK_MODEL (the bounded skeleton sanity judge, default z-ai/glm-4.7-flash), REMEMBERSTACK_ROLE_MODEL (the title-only section-role classifier, default z-ai/glm-4.7-flash), REMEMBERSTACK_SUMMARY_MODEL (bottom-up section summaries plus the root placement reduction, default z-ai/glm-4.7-flash), and REMEMBERSTACK_STRUCTURER_MODEL — which names only the string-anchor fallback proposer for documents whose headings cannot be parsed or whose parsed tree fails the sanity check. Routine skeleton construction is deterministic; bounded summary calls still run on the selected tree. Their versioned token estimate is whitespace-based, while a companion character ceiling is the hard request bound for whitespace-poor input.

Start the stack

Docker Engine with Compose v2 is required.

cp .env.example .env
docker compose up --build --detach --wait

The pinned PostgreSQL 19 prerelease container mounts its named volume at /var/lib/postgresql. Pre-release volumes created by the older PostgreSQL image are not migrated. For this disposable quickstart, remove the old stack with docker compose down --volumes before starting a different PostgreSQL 19 prerelease checkout.

--build deliberately tests the checked-out source. The public v0.17.0 release also ships this Compose file pinned to ghcr.io/writeitai/remember-stack:0.17.0; release consumers use --no-build --pull always so Compose cannot fall back to a local source build.

Do not put cost export on the public query port. When you want HTTP export, set REMEMBERSTACK_COST_EXPORT_BIND to a second address (loopback or a unix socket) and REMEMBERSTACK_COST_EXPORT_TOKEN to a ≥32-byte secret. The API process starts one export worker in-process; do not multiply workers in front of that bind. If the bind is unset, use remember ops cost-export locally. If the bind is set and the token is missing or short, the API process refuses to start.

The example file contains local-only PostgreSQL and MinIO credentials. Replace every secret before using the stack outside an isolated development machine. It also contains an OpenRouter placeholder. Replace it before processing a corpus: the complete pipeline makes extraction and embedding calls. Pin explicit model IDs for reproducible work; do not use a rotating free-model router.

Optional observability

Observability is strictly opt-in. The self-host image includes the remember[observability] extra, but no exporter initializes unless its environment configuration is non-empty.

Set REMEMBERSTACK_SENTRY_DSN to send metadata-only error events to a Sentry-protocol service such as Sentry, GlitchTip, or Bugsink. REMEMBERSTACK_SENTRY_ENVIRONMENT defaults to the deployment slug, and REMEMBERSTACK_SENTRY_SAMPLE_RATE defaults to 1.0. Request bodies, local variables, breadcrumbs, PII, prompt/completion text, and exception messages are not sent. Caught worker failures carry only their stage, lane, and processing ID as routing tags; PostgreSQL and the existing JSON telemetry remain authoritative for retry and ledger state.

LoCoMo answer and judge stages create Langfuse traces only when LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, and LANGFUSE_HOST are all set. Run the benchmark with both optional groups, for example uv run --extra benchmark --extra observability python -m benchmarks.locomo. The observer records per-call model/accounting metadata, content-free tool argument shapes, final answers, and verdicts, then flushes at stage end. It never sends source chunks, documents, rendered prompts, tool response bodies, or gold answers.

Full LoCoMo publication runs can be split across independent Compose hosts while retaining the benchmark's one-conversation-per-deployment guard. The harness accepts repeated summarize --run flags and recomputes the full-manifest score from disjoint item records. The repository's sharding operator guide covers balanced shard planning, scaled workers, six-hour drain waits, forensic database dumps, collection, and merge validation.

Check the API and the deployment-seeded operation registry:

curl --fail http://localhost:8000/healthz
curl --fail http://localhost:8000/operations

Ingest a document

Create a short Markdown document and push it through the ordinary E0 API:

printf '# Hello\n\nRemember this deployment.\n' > /tmp/remember-smoke.md
curl --fail \
  --data-binary @/tmp/remember-smoke.md \
  'http://localhost:8000/ingest?filename=remember-smoke.md&mime=text%2Fmarkdown'

The response names the deployment, document, and version. Every worker uses the normal PostgreSQL work ledger. Inspect its exact state:

docker compose exec postgres psql -U rememberstack -d rememberstack -c \
  "SELECT stage, status FROM processing_state ORDER BY enqueued_at"

The original bytes and derived Markdown/sidecars are in the MinIO buckets. The MinIO console is available at http://localhost:9001 with the credentials from .env.

Publish P3

The graph reads live PostgreSQL rows and has no build. P3 is a whole-corpus build; after the selected ingestion set has settled, publish it once:

docker compose --profile operations run --rm projections

The API reads the same MinIO P3 snapshot store. POST /readiness can verify a bounded list of document version IDs plus requested pipeline, P1, live-graph, and P3 capabilities. P3 must begin after the latest requested terminal stage. The response also records the API process's current non-secret model bindings for configuration review; these are not processing-time provenance.

Stop and reset

Stop containers while retaining state:

docker compose down

To erase this local deployment completely, including PostgreSQL, MinIO, and the separately mounted forget-manifest directory:

docker compose down --volumes

The second command is destructive. It is appropriate only for this disposable quickstart deployment—not for backup or restore. Production portability uses native store tools and preserves the hard-forget manifest root first.

Fact stores created before chosen world dates

Migration p9_30_0051 changes the meaning of fact dates: a missing end no longer means "still true", and dates are world time chosen by adjudication rather than copied from source time. Earlier stores are not converted in place. The migration refuses to run against a database that already holds claims, and it refuses downgrade because that would drop the application receipts and restore the old meaning. Recreate the deployment and ingest its sources again. Disposable quickstart deployments use docker compose down --volumes above.