RememberStackremember.dev/docs

Releases and changelog

Each release publishes the remember Python package to PyPI and the engine image ghcr.io/writeitai/remember-stack:<version> to GitHub's container registry. Release tags are v<major>.<minor>.<patch> on github.com/writeitai/remember-stack. Up to 0.16.0 the Python package was published as rememberstack.

The engine is pre-1.0. A minor version can change the API; changes that need action from you are marked Action needed.

0.21.0 (November 2026)

Action needed (self-hosted): PostgreSQL 18. PostgreSQL 18 is now the reference server (it replaces the PostgreSQL 19 release candidate). Compose uses ghcr.io/writeitai/remember-stack-postgres:18-0.21.0. A PostgreSQL 19 data directory cannot be opened by 18: start from fresh PostgreSQL 18 storage and re-ingest. See PostgreSQL server versions.

Document tags. Register tags, assign them at ingest or later, rename and delete them, find them in document lists, search results and SQL, and filter search and search_documents by tag, and the three context operations (facts_context, claims_and_sources_context, combined_context) through their documents filter. See Tag documents.

Corpus folders. Served document versions are published as type/topic/title folders through ordinary processing work, with a verifying reconcile and durable deletion. Setup migrates to p9_53_0074.

Corpus consumption

Document search's p3_path resolves a type/topic/title folder only when the selected version is served and its nullable publication marker matches current export inputs. Readiness uses the same guard per requested version. Pending, raw-only, updating, failed and historical results have no browse path. Only the suffix remains stable across folder moves; the consumption skill and MCP descriptions teach re-resolution and offline find. Corpus originals and reader derivatives remain independent of claims/facts switches, and K stays a separate repository.

The benchmark harness's fresh Full-v47 protocol attests publication markers, ready-folder identities and frozen file inventories. This change establishes no new benchmark result and does not reinterpret stored evidence.

0.20.0 (November 2026)

Retrieval SQL and online schema upgrade

Native fact and entity-scoped claim/chunk retrieval share visibility work inside each database statement. Source, version, deletion, identity and time rules still apply before a result counts toward top-k. Existing stored content and vectors are reused; this upgrade does not run ingestion or change model settings.

Action needed (operators). Run the native online migration to p9_48_0069. Its preceding revision, p9_47_0068, adds a mention-to-chunk B-tree on existing data: it builds partition indexes concurrently, then attaches them. It also replaces the existing document-entity index online with a deployment-aware ordered shape, preventing absent-member bridge checks from scanning unrelated documents under skew. Allow disk space and I/O/WAL for the new mention index and temporary coexistence of both document-index shapes. An interrupted own index build is checked and completed on rerun; a colliding index with a different definition causes setup to fail. Offline alembic upgrade --sql is unsupported for this catalog-driven revision.

Concurrent migration processes wait on one database-scoped session lock before reading revision state. It survives concurrent-index commits; ordinary reads and ingestion do not acquire it. Each revision commits separately, so index-attachment locks are released before the view update. A later migration failure leaves earlier revisions committed; returning to an earlier release requires its pre-upgrade backup. The acquisition wait defaults to 60 seconds and is configurable through migration_lock_timeout_seconds in alembic.ini; an expired wait fails setup explicitly. The new view definitions also change the query-space manifest identity, so saved-query revalidation uses that new identity.

0.19.1 (November 2026)

Database migrations and the processing receipt contract stay at 0.19.0.

Native storage evidence for operators. The engine provides a read-only capture integration with an original PostgreSQL view, in-guard allocated relation/index/TOAST/fork records, exact provider-origin matching, classified component amounts, and complete committed terminal membership. Operators supply qualified source/store/clock profiles, dedicated ordinary collector connections, provider transport and durable evidence storage. One bounded batch captures Projects at the same cut; immutable canonical pages support exact replay. See the repository's storage-capture development documentation for the callable boundary and functional validation limits.

Processing and concurrency.

  • Entity resolution preserves valid matches from its original snapshot while guarding concurrent creation. Fact projection reserves bounded pending batches, allowing unrelated work to proceed concurrently.
  • Image descriptions request explicit visual detail, defaulting to high. Existing description checkpoints refresh once under the changed fingerprint; matching OCR checkpoints remain reusable. Set REMEMBERSTACK_IMAGE_DESCRIPTION_DETAIL to an explicitly supported provider value when choosing another observation resolution.
  • Explicit provider-unavailable rejection envelopes follow the existing bounded OpenRouter retry policy.

LoCoMo development harness. Answer-model and prompt trials have explicit provider policies and bounded parallel question budgets. Development subsets and judge models are pinned in run identities. Evidence reads preserve complete constraints, initiating dialogue and attachment context; historical semantic grading and grounded negative answers are restored.

0.19.0 (November 2026)

A stock self-hosted deployment needs no action. Its new migration, p9_46_0067, reshapes the managed-metering tables, which are empty unless the deployment is metered, and adds the admission defer reason. The Compose file changes only its release image tags. The changes below matter to metered deployments (a control plane that approves usage before work runs) and to code that reads readiness or worker outcomes.

Managed metering moves to the convert stage (D150).

  • Action needed (metered deployments). Migration p9_46_0067 refuses to run while managed_ingest_measurements still holds staged originals, because those bytes exist nowhere else. On 0.18.x, drain the meter outbox until no measurement holds staged bytes, then upgrade. A measurement releases its bytes when its control plane accepts it or when its document is hard-forgotten; a parked or refused one keeps them.

  • Action needed (control planes). The meter's wire contract is now v3:

    • rememberstack.ingest_measurement.v3 carries cost_class, native_quantity, unit and format_family. This release emits these classes:
      • doc-scan, counted in pages, for every PDF page;
      • doc-text, counted in normalized characters, for other readable files.
    • rememberstack.document_version_outcome.v3 is succeeded or failed.
    • Processing profiles are named <cost class>-<standard|claims|sources>-v1.

    A control plane must accept v3 before any deployment runs 0.19.0.

  • Behaviour change. A metered deployment no longer refuses files at ingest. It stores every file, measures it in the convert stage, before any paid model call, and waits for approval:

    • a PDF is counted by its pages, before OCR;
    • a file read locally is counted by the characters of its reading;
    • a card is free;
    • a file whose route can't be measured fails with rate_class_unavailable.

    The ingest-time 409 rate_class_unavailable, 422 rate_class_ambiguous and 413 source_bytes_limit_exceeded refusals, and the 10 MB text cap, are gone. A metered deployment now keeps each file's own type, so CSV, code and logs take their own routes. A document first ingested under the old text-only classifier is processed again once, at its next version.

  • Unmetered deployments are unchanged.

Readiness and worker outcomes.

  • defer_reason on a pipeline stage has a new value, admission. The metered deployment has measured the file and is waiting for its control plane's approval. See Wait for readiness.
  • A worker run can end with the new outcome admission_parked.
  • Code that matches these values exhaustively must handle the new ones.

0.18.3 (November 2026)

A stock self-hosted deployment needs no action: its database migrations are unchanged, and its Compose file changes only the release image tags. The Action needed item applies only to programs that embed the engine and call ingest_stored.

Processing.

  • A PDF over the OCR provider's per-request limits (about 50 MB or 1,000 pages) is no longer refused. It is split into page-range batches that each fit, every batch is OCR'd, and the pages are stitched back in order, so every page is still OCR'd and metered once. Below both limits the request and the result are unchanged. The engine's own 100 MB PDF reading limit still applies when it reads the file itself (the stock in-process path); within that, only a single page over the byte limit is refused. PdfConverter.convert_path and MistralOcrConverter.convert_path convert a PDF from a file on disk without reading it whole.

Integration.

  • Action needed. UploadIngestor.ingest_stored deletes an object it refuses (size, content type, metering, a forgotten source), unless a content already keeps that key, and raises StoredObjectRefusedError. Its refusal holds the original error and raw_object_deleted says whether the object was deleted. Code that caught ContentDetectionError, ManagedTextClassificationError or ForgottenSourceError from ingest_stored catches StoredObjectRefusedError and inspects refusal.
  • UploadIngestor.discard_unregistered deletes a directly uploaded object that never became a version, unless a content keeps its key, for sweeping abandoned uploads. Serialize it with ingest_stored of the same key.

0.18.2 (November 2026)

A stock self-hosted deployment needs no action. Its database migrations and its default conversion are unchanged, and its Compose file changes only the release image tags.

Processing.

  • Behaviour change. A file over its family's reading limit (100 MB for office documents and PDFs, 200 MB for spreadsheets) is no longer refused or carded when its route's converter fetches the file by a signed URL from S3 storage. The engine reads nothing, so only the converter's own input limit applies. With the stock in-process converters the limits stay as before: an oversized PDF is refused and other oversized files become a card. See File types.
  • An oversized file is carded without reading it into the worker's memory. The card itself is unchanged.

Embedding the engine.

  • Conversion by reference. A converter can declare that it accepts a URL (UrlConverter). The worker then signs a short-lived GET URL for the raw object (PresignedReadPort, implemented by the S3 store) and never reads the bytes itself.
  • UploadIngestor.ingest_stored registers a raw object that a client uploaded directly under uploads/<id>. The engine streams it once to hash and classify it, and keeps it at that key. If the same content is already stored under another key, the earlier version answers and the engine deletes the new copy. ingest now does the same, so each content keeps one raw object, the one a hard forget purges. On a deployment with managed text metering a stored object is measured exactly as an upload is.
  • ingest_scope_routes lets an ingest-scoped credential call named host routes.
  • Route scopes and the health check now work for an API mounted under a path prefix. Before, narrow credentials there got 403.

0.18.1 (November 2026)

Version 0.18.0 was never released. Its PostgreSQL image failed to build, so it has no PyPI package and no GitHub release. Its engine image ghcr.io/writeitai/remember-stack:0.18.0 is on GHCR; do not use it. 0.18.1 has the same changes.

Self-hosted upgrades need action. Read Upgrades and migrations before moving an existing deployment. A 0.17 deployment upgrades in place: its data is kept and setup migrates it. PostgreSQL is the exception (below).

PostgreSQL 19 release candidate 1.

  • Action needed. The database image is now ghcr.io/writeitai/remember-stack-postgres:19rc1-0.18.1. Releases up to 0.17.2 ran PostgreSQL 19 Beta 3, and a Beta 3 data directory does not open under RC 1. Move in two steps:

    1. Upgrade the engine to 0.18.1 while it still runs on the Beta 3 image. setup drops the Beta 3 property graphs.
    2. Dump the database and restore it into a new RC 1 volume.

    The order matters: a dump taken before step 1 holds definitions RC 1 cannot restore. Upgrades has the commands.

  • The graph no longer uses SQL/PGQ, which RC 1 removed. One-hop neighbourhoods are plain joins over the same views, and they return the same results.

  • Action needed. Readiness reasons are renamed: graph_pgq_smoke_failed is now graph_one_hop_smoke_failed, and graph_pgq_guard_smoke_failed is now graph_one_hop_guard_smoke_failed. Update any alerting that matches the old names.

  • Action needed. The JSON output of remember ops graph-catalog ensure no longer has a definitions field. It no longer checks property graphs, and it checks the graph views instead.

Workers.

  • Action needed. Workers run by class, not by stage. worker --stage <stage> is replaced by worker --class convert|llm with --concurrency. convert converts files one at a time. llm runs every other stage, with 20 tasks in flight by default. The Compose file now has two worker services, worker-convert and worker-llm, in place of one per stage. Stop the old stack with docker compose down --remove-orphans, so the per-stage worker containers are removed. Size with REMEMBERSTACK_SELFHOST_LLM_CONCURRENCY and REMEMBERSTACK_SELFHOST_CONVERT_CONCURRENCY, or --scale; see Scaling.
  • A claimed task is a lease that its worker renews. If the worker dies, the task goes back to the queue once the lease expires, instead of staying running forever.
  • Several deployments can run their migrations against one PostgreSQL server at the same time.
  • Each worker item's log records object_bytes_read and object_bytes_written (Observability).

HTTP API.

  • Behaviour change. A request whose decoded path contains a control character, such as %0A, gets 400 invalid_path. It is refused before authentication and routing.
  • POST /documents/search finds documents by name, metadata and text. documents filters on POST /search/claims and POST /search/chunks limit a search to chosen documents. source_path on POST /ingest records where a file came from.
  • Effective periods, version keys, section history and cross-references: read a document as it was in force on a date. See Read a document as of a date.

Processing.

  • Behaviour change. Every page of every PDF is OCR'd. A deployment without a Mistral OCR key parks PDFs as no_route. REMEMBERSTACK_SELFHOST_CONVERSION_ROUTES now adds to the stock route table instead of replacing it. It cannot route PDFs to a text-layer converter.
  • Many more file types are ingested: office documents, HTML, e-books, email, notebooks, spreadsheets, delimited data and datasets. Code, logs and file cards are searchable, and claims are not extracted from them. See File types.
  • The claims and facts layers can be switched off per deployment (REMEMBERSTACK_SELFHOST_CLAIMS_LAYER, REMEMBERSTACK_SELFHOST_FACTS_LAYER) and per request. Turning one back on processes the versions it skipped.
  • Claims that refer to their own document by a phrase such as "this agreement" name the document.
  • REMEMBERSTACK_SELFHOST_RETRIEVAL_DATABASE_BUDGET_S sets one retrieval operation's database time budget.
  • setup accepts a database URL whose password is percent-encoded.

Clients.

  • The adjacent_chunks MCP tool.
  • A TypeScript client, @rememberdev/client, with the same methods as the Python client. It is available as repository source and is not published to npm.

Embedding the engine. A program can build an engine for a deployment from explicit settings and run several in one process. It can run a named task with run_task. Other options:

  • one API app serving several deployments, which resolves, authenticates and admits each request against its own deployment;
  • replaceable conversion routes;
  • a forget-manifest bucket, so no deployment state is kept on local disk;
  • credentials per bucket;
  • engine_options for the database connection pool;
  • a separate host, port and TLS settings for the SQL query role.

0.17.0 (22 September 2026)

Existing deployments must be recreated. The migrations for mutable fact windows and multi-span claim evidence refuse a database that already holds claims. Start from an empty deployment and send your sources again; see Upgrades and migrations.

One package: remember.

  • Action needed. The Python client, the CLI and the MCP server ship in one PyPI package, remember. The old rememberstack package is deprecated: its final version, 0.17.0, only forwards to remember and warns on import. Run pip install remember and change import rememberstack to import remember.
  • Action needed. The engine is no longer installed with pip. Run it from the container image ghcr.io/writeitai/remember-stack.
  • The remember package depends only on httpx, pydantic and pydantic-settings.
  • New client class remember.Client (also remember.RememberClient) with an api_key argument, from_env(), ingest_file() and path support in ingest().

Assured operations renamed.

  • Action needed. testimony_context is now claims_and_sources_context, fact_context is now facts_context, and answer_context is now combined_context. resolve_entity is unchanged. The combined result is now ContextBundle/v2, whose evidence part is called claims_and_sources. Update names in HTTP calls, SDK calls, CLI commands and agent prompts.

CLI.

  • New commands: remember setup (writes MCP configuration for Cursor, Claude Code, Claude Desktop, Codex and Antigravity), remember doctor.
  • remember query "<question>" is short for remember query text, which runs facts_context (or combined_context with --combined).
  • remember query adjacent-chunks.
  • remember review and remember budget are retired.

Retrieval.

  • New adjacent_chunks: read the passages immediately before and after a chunk (GET /chunks/{id}/adjacent, POST /chunks/adjacent, SDK, CLI).
  • Name resolution at query time tries exact aliases, then fuzzy name matches, then profile similarity, and returns no candidate, one, or an explicit ambiguity.
  • Fact labels no longer carry a bracketed date suffix; dates stay in the structured validity fields.

Processing.

  • Claims can cite several separate spans of their source (multi-span evidence).
  • In conversations, answers such as "Yep, that one" are resolved to what the question referred to, keeping ordinals and specific names.
  • Relative dates ("last Friday") are written into the claim text as resolved dates.
  • Images always get OCR and a visual description.
  • Originals are kept, and documents whose media type has no converter are parked instead of failing; remember ops resume-no-route releases them once a route exists.
  • Fact adjudication engine is configurable; OpenRouter requests rotate between providers when one is overloaded.

0.16.0 (2026-09-03)

  • A narrow ingest-only token scope for write access without read access.
  • The deployment publishes its OpenAPI schema.
  • Behaviour change. Dated events never merge across different dates.
  • Claim validity windows use half-open bounds ([from, until)).

0.15.0 (2026-09-03)

  • GET /documents lists what the deployment holds.
  • POST /search/claims and POST /search/chunks take the query in the request body, so it does not appear in URLs or access logs.
  • A deployment can name the browser origins allowed to call it.

0.14.0 (2026-09-02)

Internal changes only; no changes to the self-hosted engine or the client.

0.13.0 (2026-09-01)

Internal changes only; no changes to the self-hosted engine or the client.

0.12.0 (2026-09-01)

  • The API can verify signed tokens, not only compare shared secrets.

0.11.0 (2026-09-01)

  • Version bump; no user-visible change recorded.

0.10.0 (2026-09-01)

  • Behaviour change. Entity resolution no longer holds back names that look like generic identifiers.
  • Exact matches found earlier in the same document are reused.

0.9.0 (2026-08-31)

  • Each document version records who ingested it.

0.8.1 (2026-08-31)

  • Entity matching makes one yes-or-no decision per candidate, biased toward matching.

0.8.0 (2026-08-29)

  • Conversion routes (media type to converter) are configurable, including a mistral_ocr route for scanned documents.
  • An optional ingest body size limit, enforced before the body is buffered.

0.7.0 to 0.7.3 (2026-08-28)

  • Uncertain entity identities are kept as uncertain and converge later instead of being guessed. The patch releases fix lock contention in that process.

0.6.0 (2026-08-27)

  • The default facts context is built from the entity's neighbourhood plus fact text.

0.5.0 (2026-08-27)

  • The graph moves to PostgreSQL 19 SQL/PGQ and is read live instead of from snapshots.
  • Entity profiles backed by evidence.

0.4.0 to 0.4.3 (2026-08-13 to 2026-08-26)

  • Cost export for operators.
  • Claim and fact search runs in PostgreSQL (0.4.2).
  • text/plain passes through the stock converter routes (0.4.2).
  • The MCP server keeps its write tools when a deployment serves no operation list (0.4.1).

0.3.0 (2026-08-11)

  • SQL queries over the memory_v1 query space, with saved queries.
  • The assured context operations.
  • MCP tools ingest and pipeline_readiness.

0.2.0 (2026-07-30) and 0.1.0 (2026-07-23)

  • First public releases: the full processing pipeline in Docker Compose, optional error tracking and tracing, and the LoCoMo benchmark harness.