Self-host Deployment

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. The one-shot setup service applies every migration, provisions object buckets, bootstraps the deployment, and seeds canonical plus P2 retrieval recipes. 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

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

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 rememberstack[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 recipe registry:

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

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 aggregate projections

P2 and P3 are whole-corpus rebuilds, not per-document workers. After the selected ingestion set has settled, publish both once:

docker compose --profile operations run --rm projections

The API reads the same MinIO snapshot stores. POST /readiness can then verify a bounded list of document version IDs: all ten exact component generations must be terminal, and both projection builds must begin after the latest 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, Lance, 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.