RememberStackremember.dev/docs

Ingest, readiness and documents

Pagination follows the shared Pagination and truncation contract (D154).

These routes cover the write side of memory. POST /ingest adds one file. POST /readiness tells you whether the versions you added are processed far enough to query. GET /documents lists what the deployment holds, newest document first. POST /documents/search finds documents by name, metadata and text. DELETE /documents/{doc_id} removes a document from the memory.

Four more routes describe versions after ingest. PUT /documents/{doc_id}/versions/{version_id}/effective-periods declares when a version's text is in force, and DELETE /documents/{doc_id}/effective-periods withdraws every such declaration of a document. PUT /documents/{doc_id}/versions/{version_id}/references supplies the references a version makes, and the GET of the same path reports what became of them. Reading sections and references across versions is on Section history and references.

Five routes manage document tags. GET /tags, POST /tags, PATCH /tags/{tag_id} and DELETE /tags/{tag_id} list, register, change and remove the deployment's tags, and POST /documents/{doc_id}/tags changes the tags one document carries. A walkthrough is in Tag documents.

Base URL, authentication and error shapes are described in HTTP API conventions.

POST /ingest

Add one file as a new document, or as a new version of an existing one.

Scope: ingest or write.

The body is the raw file. Everything else travels in the query string, except attribution, which travels in headers so that it never lands in access logs.

Parameters

NameInTypeRequiredDefaultConstraints
filenamequerystringyesAt least 1 character. Its suffix is kept on the stored original; its stem is the title when title is absent.
mimequerystringyesAt least 1 character. A format hint; recognizable bytes establish the content class first.
titlequerystringnostem of filename
source_kindquerystringnoAt least 1 character. Must be sent together with source_ref.
source_refquerystringnoAt least 1 character. Must be sent together with source_kind.
source_modified_atquerydate-timenoUTC only (Z or +00:00). Requires source_kind and source_ref.
versioning_modequerysnapshot | livingnosnapshotliving requires source_kind and source_ref.
source_version_refquerystringnoThe source system's own revision id. Requires source_kind and source_ref.
source_pathquerystringnoAt least 1 character. Where the file lives at its source, such as a folder path or a URL. Recorded with this version's names; see File names, titles and paths.
version_keyquerystringno1 to 512 characters. Your own permanent name for this version, unique within the document, such as edition-2. Requires source_kind and source_ref. See Versions in force.
effective_fromquerydate-timenoUTC only. The start (included) of the period during which this version's text is in force. Requires source_kind and source_ref, and a snapshot document.
effective_untilquerydate-timenoUTC only. The end (excluded) of that period. Requires effective_from, and must be later than it. Without it the period lasts until the next declared start.
tagsquerystring, repeatablenoAt most 64. Registered tags, each by name (any letter case) or tag_id, added to the document's tags. Repeat the parameter for several: tags=project:billing-migration&tags=kind:decision. See Tags.
X-Ingest-Principal-Kindheaderuser | api_credential | servicenoSent with X-Ingest-Principal-Ref. See Attribution.
X-Ingest-Principal-Refheaderstringno1–255 printable ASCII characters. Sent with X-Ingest-Principal-Kind.
Content-Typeheaderyesapplication/octet-stream.
Content-Lengthheaderintegerwhen the deployment caps bodies

Body: the file's bytes, application/octet-stream.

What identifies a document

Without source_kind and source_ref, the file's content is its identity: the document id is derived from the SHA-256 of the bytes. Sending the same bytes again is a no-op, and different bytes are a different document. After you delete a document, sending its bytes again adds it back as a new version ("created": true), processed from the start.

With source_kind and source_ref, the pair is the identity. Use it for anything that changes over time — a spec that gets edited, a page in another system — so that each change becomes a new version of the same document:

  • bytes identical to the document's latest version: no-op, "created": false;
  • changed bytes: a new version, "created": true;
  • bytes that match only an older version (a revert): a new version.

versioning_mode says what a new version means for the old one. snapshot (the default) keeps what earlier versions said as testimony. living treats the newest version as the source's current state: claims the new version no longer makes stop being current testimony. See Updating a source.

A MIME type the deployment has no converter for is still accepted. Its conversion waits until a converter route for that type exists, and the response says so with "parked": "no_route". See File formats and converters.

Versions in force

effective_from and effective_until declare when this version's text is in force, according to whoever publishes it: a policy edition, a price list, a contract version. The period is half-open: effective_from is included, effective_until is not. Without effective_until, the period ends where the next declared start of the same document begins, so declaring a new edition ends its predecessor without a second call. Periods are declared by you; the engine never infers them. They are a separate clock from source_modified_at; see Time.

  • Periods need a source identity and a snapshot document. A living document refuses them with 422 effective_time_requires_snapshot, because there the newest version is by definition the one that applies.
  • The period is recorded on the version this call created, or, when the bytes match the latest version and nothing is created, on that latest version. Declaring a period never reprocesses anything.
  • The same period declared again is a no-op. The same start with a different end replaces the earlier end.
  • A start that another version of the document already declares is refused with 409 effective_period_conflict, and nothing is stored.

Once a document has a declared period, every time-scoped read selects its versions by period instead of by "newest processed version"; see Read a document as of a date. Change or withdraw periods later with PUT …/effective-periods.

version_key names a version permanently, so that a pinned reference can point at exactly that edition. One version has at most one key, and a key names one version for good, even after that version is deleted:

  • a key the document has not used yet always creates a new version, even when the bytes equal the latest version's (two editions with identical text are two versions);
  • the key of the latest version, sent again with the same bytes, is a retry: "created": false;
  • any other use of an existing key (different bytes, or the key of an older version) is refused with 409 version_key_conflict, naming the version that owns the key. To put an older edition back in force, declare a period on that version instead.

Without version_key, ingest behaves as described above.

What the first ingest fixes

Some settings are taken from the first ingest and kept:

  • title and versioning_mode belong to the document and are set when it is first ingested. Later ingests of the same document do not change them.
  • The MIME type belongs to the bytes: identical bytes are stored once, with the first detected or compatible family type, and conversion uses that type. One exception: if that type has no converter route, so conversion is parked, sending the same bytes with a byte-compatible type that has a route replaces it and releases every parked conversion of those bytes. A file first sent as unrecognized text stored as text/x-other-text can be made Markdown by sending the same text bytes again as text/markdown. A binary file cannot be made Markdown by changing its MIME hint.

The response reports the values in force (mime, title, versioning_mode). Compare them with what you sent to see whether yours were taken.

File names, titles and paths

Each version records the names it was ingested under: filename, the title you sent (not the stem of filename), and source_path. A converter can add what the file itself declares, such as an HTML page's <title>.

Sending the same bytes again under a different filename, title or source_path is still a no-op ("created": false), but the engine records the new name next to the old ones. A parameter you leave out does not count as a change. The document's own title in the response does not change: it stays the one set by the first ingest.

POST /documents/search finds a document by any of these names.

Tags

tags adds registered tags to the document. Ingest only adds: a tag the document already carries stays, and a tag you leave out is not removed. One document can be reached by several callers (two people uploading the same file reach the same document), so each caller's tags are kept. Change or remove tags with POST /documents/{doc_id}/tags.

Tags never decide whether a version is created. Sending bytes identical to the latest version with new tags adds the tags and is still a no-op ("created": false); a new version_key or a document added back after a delete still creates a version, as without tags. Tags are not part of what is processed, so adding them starts no work.

Every tag must be registered first. If any is not, the whole ingest is refused with 422 unknown_tag, naming every unregistered tag, before the bytes or any record are stored. A document carries at most 64 tags; an ingest that would pass that is refused with 409 tag_limit_exceeded, also before anything is stored.

Attribution

X-Ingest-Principal-Kind and X-Ingest-Principal-Ref record who added the version. The engine believes them only when both hold:

  • the deployment declares its network trusted (REMEMBERSTACK_SELFHOST_TRUSTED_PRINCIPAL_SOURCE=true, off by default), and
  • when authentication is on, the credential has write scope.

Otherwise the headers are ignored, not rejected: the upload succeeds and no attribution is recorded. A browser ingest credential can never set attribution. Attribution belongs to the new version only; a no-op re-ingest does not change it.

Response

200 with an IngestedVersion:

{
  "deployment_id": "5d0c7a52-3b1e-4f55-9a8e-0e6c1f2b7a10",
  "doc_id": "a1f3e0b4-1c2d-5e6f-8a9b-0c1d2e3f4a5b",
  "version_id": "0f9e8d7c-6b5a-4c3d-2e1f-0a9b8c7d6e5f",
  "content_hash": "3b7c0e2d9f1a…",
  "created": true,
  "mime": "text/markdown",
  "title": "Q3 plan",
  "versioning_mode": "snapshot",
  "parked": null,
  "version_key": null
}

200 means the version is stored. version_key is the version's key, or null when it has none. "parked": null means only that it is not parked for no_route; poll POST /readiness with the version_id for its processing state. "parked": "no_route" means its conversion is parked waiting for a conversion route for the mime: the bytes are kept, but nothing reads them until an operator adds a route if needed and runs remember ops resume-no-route. Do not wait on readiness for it; it will not become ready on its own.

Errors

StatusdetailCause
411length_requiredThe deployment caps bodies and the request has no Content-Length.
413body_too_largeThe body is over the deployment's cap.
409source_forgottenA hard forget removed these bytes, or the document with this source_kind and source_ref. A forget is permanent; do not retry.
409{"code": "version_key_conflict", "message": …, "version_id": …, "version_key": …}The version_key already names another version of this document (version_id), or names the latest version but the bytes differ. Nothing was stored.
409{"code": "effective_period_conflict", "message": …, "version_id": …, "effective_from": …}Another version of this document (version_id) already declares this effective_from. Nothing was stored.
409{"code": "tag_limit_exceeded", "message": …}The document would carry more than 64 tags. Nothing was stored.
422{"code": "unknown_tag", "message": "unknown tags: …", "tags": […]}A tag in tags is not registered. tags lists every unregistered one as you sent it. Nothing was stored.
422source_kind and source_ref must be supplied togetherOnly one of the pair was sent.
422source timestamps, revisions, living mode, version keys and effective periods require source_kind/source_refsource_modified_at, source_version_ref, versioning_mode=living, version_key or effective_from without a source identity.
422source_modified_at must be timezone-aware UTCThe timestamp has no offset or a non-zero one. The same message names effective_from or effective_until for those parameters.
422effective_until requires an earlier effective_fromeffective_until without effective_from, or not later than it.
422{"code": "effective_time_requires_snapshot", "message": …}A period with versioning_mode=living, or for a document that was first ingested as living.
422X-Ingest-Principal-Kind and X-Ingest-Principal-Ref must be supplied togetherTrusted attribution with only one header.
422invalid_ingest_principalTrusted attribution with an unknown kind or a malformed reference.
422content_type_mismatchThe declared MIME contradicts a content class identified from the bytes. No original or catalog row is written.
422ambiguous_office_formatLegacy Office container bytes have no declared Word, Excel or PowerPoint subtype.
422validation listfilename or mime missing or empty, or another parameter malformed.
503{"code": "forget_in_progress"}A hard forget is running.

A self-hosted deployment has no body cap unless you set REMEMBERSTACK_SELFHOST_INGEST_BODY_MAX_BYTES, and accepts any file its converters handle.

Example

curl -s -X POST "$REMEMBER_API_URL/ingest?filename=billing-migration.md&mime=text/markdown&source_kind=notes&source_ref=specs/billing-migration.md&versioning_mode=living" \
  -H "Authorization: Bearer $REMEMBER_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @billing-migration.md
from remember import Client
 
memory = Client()
version = memory.ingest(
    "billing-migration.md",
    source_kind="notes",
    source_ref="specs/billing-migration.md",
    versioning_mode="living",
)
print(version.version_id, version.created)

Client.ingest accepts a path (string or Path) or bytes; with bytes, pass filename. It takes mime from the extension of the file's name (for bytes, of filename): .md is text/markdown on every Python installation; see the full table. An extension outside that table takes the type your Python installation's MIME database gives it, or application/octet-stream if it has none. Client.ingest_file(path, ...) is the same call.

POST /readiness

Report, for up to 1,000 versions, which pipeline stages have finished and whether the capabilities you need are ready. It only reads; it never waits.

Scope: read.

Request body

FieldTypeRequiredConstraints
version_idsarray of UUIDyes1 to 1,000 items. Duplicates are collapsed.
requireobjectyesAll four fields below are required.
require.pipelinebooleanyesEvery expected stage has finished for every version.
require.p1booleanyesThe search index (claims, chunks, facts) is published.
require.live_graphbooleanyesThe live graph passes its health checks.
require.p3booleanyesEvery requested served version's corpus publication marker matches its current export inputs.

Unknown fields are rejected (422).

Response

200 with a PipelineReadinessReport. ready is true when every capability you marked as required is ready. Each version lists one entry per expected stage with its status. A version is ready when every stage is succeeded or skipped and has a finished_at.

The stages a self-hosted deployment reports, in order: convert, structure, chunk, embed_chunk, extract_claims, ground_claims, normalize_relations, adjudicate_observations, adjudicate_supersession, embed_claim, reconcile, label_relation.

A failed stage has a retry scheduled and can still succeed; keep polling. If a stage is dead_letter, stop polling: it used all its attempts, and that version will not become ready without intervention.

Capability reason values:

Capabilityreason when readyreason when not ready
pipelinereadystage_incomplete
p1readysearch_channel_incomplete
p3readycorpus_publication_incomplete, p3_version_not_served
live_graphreadygraph_server_version_mismatch, graph_extension_version_mismatch, graph_role_contract_mismatch, graph_helper_contract_mismatch, graph_catalog_mismatch, graph_role_runtime_limits_mismatch, graph_smoke_identifier_collision, graph_one_hop_guard_smoke_failed, graph_one_hop_smoke_failed, graph_neighborhood_smoke_failed, graph_path_smoke_failed, graph_citation_smoke_failed, graph_database_or_permission_failed, graph_smoke_contract_failed

A version id the deployment does not know is not an error: every stage reads missing and the version is not ready.

Errors

StatusdetailCause
422validation listEmpty or oversized version_ids, a malformed UUID, a missing require field, or an unknown field.

Example

curl -s -X POST "$REMEMBER_API_URL/readiness" \
  -H "Authorization: Bearer $REMEMBER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"version_ids": ["0f9e8d7c-6b5a-4c3d-2e1f-0a9b8c7d6e5f"],
       "require": {"pipeline": true, "p1": true, "live_graph": true, "p3": false}}'
from remember import Client, ReadinessRequirements
 
memory = Client()
report = memory.pipeline_readiness(
    version_ids=(version.version_id,),
    require=ReadinessRequirements(pipeline=True, p1=True, live_graph=True, p3=False),
)
 
# Or poll until ready (pipeline, p1 and live_graph required; p3 optional):
report = memory.wait_for_readiness([version.version_id])

wait_for_readiness polls every poll_interval seconds (default 15) and raises TimeoutError after timeout seconds (default 1800). It keeps polling through a failed stage and raises PipelineDeadLettered at once on a dead_letter stage. See Wait until a document is queryable.

GET /documents

List the documents the deployment holds, one page at a time, newest document first.

Scope: read.

Parameters

NameInTypeRequiredDefaultConstraints
limitqueryintegerno501 to 200.
cursorquerystringnoThe next_cursor from the previous page. Opaque.
statusqueryingesting | converting | structuring | ready | failednoFilters on the newest version's status.

Documents are ordered by when each was first seen, then by id. Re-ingesting a document does not move it: it is the same document, first seen when it was first seen. Deleted documents and deleted versions are not listed.

The order is fixed on purpose. "Most recently changed first" would move a document every time a new version arrived, and a client paging through the list would skip it or see it twice. first_seen_at never changes, so the cursor stays exact while documents are being added. A new document still appears at the top of the first page.

Each row reports the newest surviving version (latest) and, separately, whether any version is being served (serving). A document whose newest upload failed can still be served from an older, working version.

A document status of ready means conversion and structuring finished. It does not mean the document is searchable yet; use POST /readiness for that.

Response

200 with a DocumentPage:

{
  "documents": [
    {
      "doc_id": "a1f3e0b4-1c2d-5e6f-8a9b-0c1d2e3f4a5b",
      "title": "billing-migration",
      "source_kind": "notes",
      "source_uri": "specs/billing-migration.md",
      "first_seen_at": "2026-09-21T09:14:03.201Z",
      "latest": {
        "version_id": "0f9e8d7c-6b5a-4c3d-2e1f-0a9b8c7d6e5f",
        "version_no": 3,
        "status": "ready",
        "ingested_at": "2026-09-23T08:02:11.540Z",
        "error": null
      },
      "serving": true,
      "tags": ["kind:decision", "project:billing-migration"]
    }
  ],
  "next_cursor": null
}

tags holds the names of the document's tags, ordered by name ignoring letter case; it is empty for an untagged document. next_cursor is null on the last page.

Errors

StatusdetailCause
400cursor is malformedThe cursor does not parse.
422validation listlimit out of range or an unknown status.

Example

curl -s "$REMEMBER_API_URL/documents?status=failed&limit=20" \
  -H "Authorization: Bearer $REMEMBER_API_KEY"
from remember import Client
 
memory = Client()
page = memory.list_documents(status="failed", limit=20)
for document in page.documents:
    print(document.doc_id, document.title, document.latest.error)
# page.next_cursor is None on the last page; pass it back to read the next one.

remember documents list prints the same page as JSON.

POST /documents/search

Find documents by the names they were stored under, by their general metadata, and by their text.

Scope: read.

Request body

A DocumentSearchRequest:

FieldTypeRequiredDefaultConstraints
querystringno1 to 4,096 characters. Words from the file name, title, source path or text.
filtersobjectno{}See below. Every filter you give must hold.
versionscurrent | allnocurrentWhich versions of each document may match.
timeobjectno{"mode": "current"}For documents with declared effective periods: which editions are candidates. {"mode": "current"}, {"mode": "at", "at": …}, {"mode": "overlap", "from": …, "to": …} or {"mode": "history"}; see Editions in force.
kintegerno20Ranked results with query: 1 to 200.
limitintegerno50Browse page size without query: 1 to 200.
cursorstringnoThe next_cursor from the previous page. Only without query.

filters:

FieldTypeMeaning
familyarray of stringsThe document's format family (the families): markdown, text, other_text, code, config, log, html, ebook, notebook, email, word, presentation, pdf, spreadsheet, delimited, dataset, image, media, archive or binary. Any listed family matches.
authorsarray of stringsA name or an address. Any listed term matches.
recipientsarray of stringsThe same, for recipients.
created_from, created_todate-time with timezoneThe date the document declares it was created or sent, inclusive. A document that declares no date does not match a range.
modified_from, modified_todate-time with timezoneThe declared last-modified date, inclusive.
languagestringExact match.
thread_refstringThe conversation or thread key, exact match.
doc_idsarray of UUIDsOnly these documents.
tagsobjectThe document's tags: {"all": [...], "any": [...], "none": [...]}. See below.

Unknown fields are rejected (422).

filters.tags selects documents by the tags they carry now. Each list holds tag names (any letter case) or tag_ids:

FieldMatches a document that carries
allevery listed tag
anyat least one listed tag
nonenone of the listed tags

Give at least one non-empty list. A list may hold up to 32 tags and may not name a tag twice. The lists combine with AND, and tags combines with the other filters with AND: {"family": ["email"], "tags": {"all": ["project:billing-migration"], "none": ["kind:draft"]}} finds billing migration emails that are not tagged as drafts. A document with no tags matches a none list and fails all and any. Tags belong to the document, not to a version, so with versions: all or a past time every version is tested against the document's current tags. Any tag that is not registered refuses the whole search with 422 unknown_tag, naming every one, before anything is searched.

What matches

Documents, judged by one version. Each result is a document. With versions: current and a query, a document is judged by its current version, or, while it has none yet because its first upload is still processing, by its newest version. Without a query (paged results), it is judged by its newest version that had arrived when the search started (see Order and paging). With versions: all any version may match, and the result is the newest version that did, with the others in other_matching_version_ids. Filters and names always use the returned version's own metadata. Deleted documents and deleted versions never match.

p3_path is the relative corpus folder only when the described version is served and its nullable publication marker matches the current export inputs. It is null before publication, during updates, after a failed publication, for raw-only versions and for historical editions, including non-periodised history. served_version describes authority currency independently of P3. Re-resolve by filters.doc_ids after a type/topic/title move, or use offline suffix lookup. A newer pending upload leaves the served folder intact. A temporal query that selects no edition returns no document; suffix lookup does not override it. Keep version_id and representation_id for exact source identity; no public source_open operation returns whole historical files yet.

query matches every name the version was stored under: the filename, title and source_path of the ingest that created it, and of each later ingest of the same bytes under another name (see File names, titles and paths). So a renamed file is found by its new and old names, and a partial or misspelled name still finds it. It also matches the document's text, by its best-matching passage. Names (matched by whole words and by similar spelling) and text are two equal channels combined by rank; each document counts once per channel, by its best match. matched_by says which matched. Text matching is by words; there is no semantic matching on this route.

People. A term matches a person when it equals their address, or when its words appear whole in their name, ignoring case and accents: alice matches "Alice Novák" but ali does not. Metadata such as authors comes from the format's converter. Today the only value read from inside a file is the title the markitdown converter reports (an HTML page's <title>, for example), so authors and recipients are empty, and a newly ingested version's only date is modified_at, from the source_modified_at you sent with it. When a people filter is given, people_matched lists each distinct person it matched, with the number of matching documents, so you can narrow an ambiguous filter (for example to an address) instead of guessing.

Editions in force

For a document with declared effective periods, time decides which of its versions are candidates: the ones in force now (current, the default), at an instant (at), at any point of a window (overlap, both ends included) or at any point up to now (history). An edition that is not in force for time never matches, even if it is the newest. Documents without declared periods are judged exactly as described above, whatever time says.

  • With versions: current, only the candidate whose period starts latest is judged, and the result describes it.
  • With versions: all, any candidate may match, and the result describes the matching candidate whose period starts latest.

Each such result carries effective (the described version's in-force intervals) and matching_editions: every candidate that matched, by period start, each with version_id, version_no, version_key, representation_id and effective, so you can open any of them without another call. When two editions are in force at once (overlapping periods), both are candidates; none is chosen silently.

scope_pending names the documents this search examined whose edition in force for time is still being processed, at most 50 ids with a count, so "nothing is in force" can be told from "the edition in force is not ready yet". A search with a query examines only the documents it returns; a search without one examines every document it walked for the page.

Order and paging

With query, results are ranked, and there is no next page: next_cursor is null. Raise k for more.

Without query, results are every document the filters match, newest first by the newest version ingested at or before the pinned instant, then by doc_id; the created_* range is a filter, not the order. Pass next_cursor back as cursor for the next page. The first page fixes an instant, returned as as_of, and every later page judges each document by its newest version ingested by then. A document added, a version promoted to current, or a date filled in by processing while you page therefore neither moves nor repeats a row. The same instant is used to read effective periods, so a period declared or corrected while you page does not move a row either. Start a new search to see what arrived since.

A browse page stops after walking ten times limit documents. It can then hold fewer than limit results and still return a next_cursor: keep paging until next_cursor is null.

Response

200 with a DocumentSearchPage:

{
  "documents": [
    {
      "doc_id": "a1f3e0b4-1c2d-5e6f-8a9b-0c1d2e3f4a5b",
      "version_id": "0f9e8d7c-6b5a-4c3d-2e1f-0a9b8c7d6e5f",
      "version_no": 1,
      "status": "ready",
      "lineage_title": "Q3_sales_2025",
      "tags": ["project:finance"],
      "file_name": "Q3_sales_2025.xlsx",
      "title": null,
      "source_path": "finance/2025",
      "p3_path": "spreadsheet/sales/q3-sales-2025--2a43bb03e2c419e141d5fbd9",
      "served_version": true,
      "representation_id": "7c2e4b1a-9d3f-4e8a-b6c5-2f1a0e9d8c7b",
      "effective": [],
      "matching_editions": [],
      "family": "spreadsheet",
      "created_at": null,
      "modified_at": null,
      "language": null,
      "thread_ref": null,
      "authors": [],
      "recipients": [],
      "extra": {},
      "overview": "Quarterly sales by region …",
      "other_matching_version_ids": [],
      "matched_by": ["name"],
      "score": 0.0328
    }
  ],
  "next_cursor": null,
  "as_of": "2026-09-24T10:12:03.117Z",
  "people_matched": [],
  "scope_pending": null
}

Each result's tags holds the names of the document's tags, as in GET /documents.

Errors

StatusdetailCause
400cursor is malformedThe cursor does not parse.
422validation listAn unknown field, k out of range, a date without a timezone, cursor together with query, or an empty, repeating or too long filters.tags list.
422{"code": "unknown_tag", "message": …, "tags": [...]}filters.tags names tags that are not registered; tags lists every one.

Example

curl -s -X POST "$REMEMBER_API_URL/documents/search" \
  -H "Authorization: Bearer $REMEMBER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "q3 sales", "filters": {"family": ["spreadsheet"]}, "k": 5}'
from remember import Client, DocumentSearchFilters
 
memory = Client()
page = memory.search_documents("q3 sales", filters=DocumentSearchFilters(family=("spreadsheet",)))
for result in page.documents:
    print(result.doc_id, result.file_name, result.matched_by)

remember documents search "q3 sales" --family spreadsheet prints the same page as JSON. --tag T (all), --any-tag T and --not-tag T, each repeatable, fill filters.tags.

DELETE /documents/{doc_id}

Remove one document from the memory: every version of it, all at once.

Scope: write.

Parameters

NameInTypeRequiredConstraints
doc_idpathUUIDyesThe doc_id that POST /ingest returned, or that a claim, chunk or GET /documents names.

There is no body.

What deleting does

When the call returns, the document is out of the memory:

  • it no longer appears in GET /documents, search, facts, the graph or SQL queries;
  • its claims stop counting as evidence (their reason becomes version_deleted);
  • a fact that only this document supported is closed, with a recorded retraction (retracted_source_removal); a fact other documents also support stays, with one supporter fewer.

Deleting is not erasing. The claims and the stored original stay in the deployment as history, and the retraction is recorded. Erasing a document's bytes and every trace of it is a separate operator operation that is not offered through the API.

Processing that was still running for the document stops publishing new claims. Anything it already produced is never visible and is retired when that version reaches the reconcile stage.

A pending review of whether the document's claims were extracted correctly is closed as moot, because the document is gone.

If you ingest the same file again later, it is added back as a new version and processed from the start, like any new document. The facts that closed stay closed; the new claims support facts as usual.

The route starts no pipeline work. Its one possible model call re-embeds the profile text of entities whose facts changed; that call is recorded with the deployment's other request-time model calls. If the model provider is down, the deletion still succeeds and those profiles catch up the next time the entity's evidence changes.

Response

200 with a DocumentDeletion:

{
  "doc_id": "a1f3e0b4-1c2d-5e6f-8a9b-0c1d2e3f4a5b",
  "deleted_at": "2026-09-23T10:41:07.318Z",
  "claims_retired": 12,
  "relations_closed": 2,
  "observations_closed": 1
}

The counts describe what this call changed.

Deleting twice

A deletion is all or nothing: the document is hidden and its evidence updated in one step, or nothing changes. A second DELETE of the same document answers 404 document_not_found, the same as an id the deployment never held, so retrying after a timeout is safe. The one exception is a document that was hidden some other way but whose evidence was never updated; deleting it finishes the job and answers 200 with what it finished.

If you ingest the document again while a DELETE of it is running, the ingest waits for the delete to finish and then adds the document back as a new version.

Errors

StatusdetailCause
404document_not_foundNo such document, or it is already deleted. Do not retry.
403credential may not perform this operationThe credential has read or ingest scope.
422validation listdoc_id is not a UUID.
503{"code": "forget_in_progress"}A hard forget is running, or started preparing just before the delete. Nothing was deleted; retry later.

Example

curl -s -X DELETE "$REMEMBER_API_URL/documents/a1f3e0b4-1c2d-5e6f-8a9b-0c1d2e3f4a5b" \
  -H "Authorization: Bearer $REMEMBER_API_KEY"
from remember import Client, MemoryApiError
 
memory = Client()
try:
    deletion = memory.delete_document(doc_id="a1f3e0b4-1c2d-5e6f-8a9b-0c1d2e3f4a5b")
    print(deletion.claims_retired, deletion.relations_closed)
except MemoryApiError as error:
    if error.status_code != 404:
        raise

PUT /documents/{doc_id}/versions/{version_id}/effective-periods

Replace the periods during which one version's text is in force. Use it to declare periods after ingest, to correct them, or to withdraw a version from force by giving it an end.

Scope: write.

Parameters

NameInTypeRequiredConstraints
doc_idpathUUIDyesA live document.
version_idpathUUIDyesA version of that document that is not deleted.

Request body

FieldTypeRequiredConstraints
periodsarray of objectsyes0 to 1,000 items, no two with the same effective_from.
periods[].effective_fromdate-timeyesUTC (Z or +00:00). Included.
periods[].effective_untildate-timenoUTC. Excluded; later than effective_from. Omitted: the period lasts until the next declared start in the document.

Unknown fields are rejected (422).

What it does

The body is the version's complete set. Periods already declared with the same start and end are kept; the version's other periods are withdrawn, and the new ones are declared, in one step. Nothing is reprocessed.

  • An empty set leaves the version with no period. The document still has declared effective time, so that version is not in force at any instant; it does not become "current" again.
  • A start that another version already declares is refused with 409, and nothing changes.
  • A living document is refused with 422.

Declarations are kept as a history: a replaced or withdrawn period is marked with the instant it stopped being believed, never deleted. A read that pages with a cursor keeps seeing the periods as they were when it started.

Response

200 with an EffectivePeriodsSet:

{
  "doc_id": "a1f3e0b4-1c2d-5e6f-8a9b-0c1d2e3f4a5b",
  "version_id": "0f9e8d7c-6b5a-4c3d-2e1f-0a9b8c7d6e5f",
  "periods": [
    {
      "period_id": "5e2d9c1b-0a3f-4b7e-8d6c-1f2e3a4b5c6d",
      "effective_from": "2026-01-01T00:00:00Z",
      "effective_until": "2027-06-30T00:00:00Z",
      "declared_at": "2027-06-30T09:12:44.081Z"
    }
  ],
  "declared": 1,
  "retracted": 1
}

periods lists the version's periods after the call, as declared (an effective_until of null means "until the next declared start"). declared and retracted count what this call changed.

Errors

StatusdetailCause
404document_not_foundNo such document, or it is deleted.
404version_not_foundThe version is not a live version of this document.
409{"code": "effective_period_conflict", "message": …, "version_id": …, "effective_from": …}Another version (version_id) already declares that start.
422{"code": "effective_time_requires_snapshot", "message": …}The document is living.
422validation listA timestamp without a zero UTC offset, an end not after its start, two periods with the same start, more than 1,000 periods, or an unknown field.

Example

curl -s -X PUT "$REMEMBER_API_URL/documents/$DOC_ID/versions/$VERSION_ID/effective-periods" \
  -H "Authorization: Bearer $REMEMBER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"periods": [{"effective_from": "2026-01-01T00:00:00Z", "effective_until": "2027-06-30T00:00:00Z"}]}'
from datetime import UTC, datetime
 
from remember import Client, EffectivePeriodInput
 
memory = Client()
memory.set_effective_periods(
    doc_id=doc_id,
    version_id=version_id,
    periods=[
        EffectivePeriodInput(
            effective_from=datetime(2026, 1, 1, tzinfo=UTC),
            effective_until=datetime(2027, 6, 30, tzinfo=UTC),
        )
    ],
)

DELETE /documents/{doc_id}/effective-periods

Withdraw every declared period of a document and return it to "the newest processed version is the current one". This is the only way back: a document with declared periods keeps reading by period, even with none left, until you call it.

Scope: write.

Parameters

NameInTypeRequiredConstraints
doc_idpathUUIDyesA live document.

There is no body.

Response

200 with an EffectiveTimeCleared:

{
  "doc_id": "a1f3e0b4-1c2d-5e6f-8a9b-0c1d2e3f4a5b",
  "retracted": 2,
  "cleared_at": "2027-07-01T08:00:00.412Z"
}

retracted counts the periods withdrawn. cleared_at is the instant the document left effective time; it is null when the document never had declared periods, and then nothing changed. The change is recorded, so a paged read that started earlier still sees the periods it started with.

Errors

StatusdetailCause
404document_not_foundNo such document, or it is deleted.
422validation listdoc_id is not a UUID.

Example

curl -s -X DELETE "$REMEMBER_API_URL/documents/$DOC_ID/effective-periods" \
  -H "Authorization: Bearer $REMEMBER_API_KEY"
cleared = memory.clear_effective_time(doc_id=doc_id)

PUT /documents/{doc_id}/versions/{version_id}/references

Supply the references one version makes: which sections of which other documents it points at, and how. The body replaces the version's complete supplied set.

Scope: write.

Parameters

NameInTypeRequiredConstraints
doc_idpathUUIDyesA live document.
version_idpathUUIDyesA version of that document that is not deleted.
Content-Typeheadernoapplication/x-ndjson by convention; the body is read as NDJSON whatever it says.

Request body

NDJSON: one JSON object per line, one reference per object, at most 64 MiB (67,108,864 bytes) in all. Blank lines are skipped; an empty body is a set with no references. Each object:

FieldTypeRequiredConstraints
kindstringyesrefers_to, amends, implements, cites, links_to, attaches or replies_to. See Reference kinds.
from_section_keystringnoThe section key in this version the reference is made from; omitted, the whole document. 1 to 200 characters from A–Z a–z 0–9 _ . : / -.
target.source_kindstringyes1 to 128 characters. The target document's source_kind.
target.source_refstringyes1 to 512 characters. The target document's source_ref. The target need not be ingested yet.
target.version_keystringwith binding: pinned1 to 512 characters. The target version's version_key.
target.section_keystringnoA section key in the target; omitted, the whole document. Same syntax as from_section_key.
bindingfloating | pinnednoDefault floating: the reference points at whichever target versions are in force when it is read. pinned points at the one version named by target.version_key.
change_date_knownbooleanwith kind: amendsWhether the source states when its change takes effect. Only for amends.
change_effective_fromdate-timewith change_date_known: trueUTC. When the change takes effect. Only for amends, and forbidden when change_date_known is false.
source_labelstringno1 to 200 characters. Your own type code for the reference, returned as you sent it.
contextstringno1 to 2,000 characters. Text around the reference, shown when it is read.

Unknown fields are rejected.

{"kind": "refers_to", "from_section_key": "approvals", "target": {"source_kind": "intranet", "source_ref": "policy/expense", "section_key": "approvals-process"}}
{"kind": "amends", "from_section_key": "per-diem", "target": {"source_kind": "intranet", "source_ref": "policy/travel-rates", "version_key": "2025"}, "binding": "pinned", "change_date_known": true, "change_effective_from": "2026-01-01T00:00:00Z"}

Reference kinds

KindMeaning
refers_toAn in-text pointer to another passage or document: "see section 4.2", "as defined in section 3".
amendsThe source changes the target's text or force: an amendment to a contract clause.
implementsThe source elaborates or carries out the target: a procedure that implements a policy.
citesA bibliographic citation.
links_toA hyperlink.
attachesContainer membership, such as an e-mail attachment.
replies_toConversation threading.

What it does

The latest call wins. Each call is compared with the version's current intent: its newest set that is neither rejected nor replaced.

  • The same set again (the same references in the same order; spacing and key order do not matter) is a retry and changes nothing: outcome is unchanged.
  • The set that is already active, sent while a newer set is still pending, cancels the pending set: outcome is pending_cancelled, and the active set stays.
  • Any other set is recorded as a new pending generation and replaces every older pending one: outcome is created.

A pending set is checked against the version's sections and then made active by the pipeline's crossref stage, in one step that also retires the previously active set. Readers never see half of a set. The check is all or nothing: one from_section_key the version does not have rejects the whole set (status: "rejected" with errors), and the previously active set stays active. When the version's sections already exist, this check runs during the call, so a created generation can come back already rejected. Section keys in target are not checked here; they are checked whenever the reference is read.

A target is named by its source_kind and source_ref, so a reference may point at a document you have not ingested yet. It starts working when that document is first ingested.

POST /readiness does not wait for references. Check a set with GET …/references, and read references with document_references.

Response

200 with a ReferencesSet:

{
  "doc_id": "a1f3e0b4-1c2d-5e6f-8a9b-0c1d2e3f4a5b",
  "version_id": "0f9e8d7c-6b5a-4c3d-2e1f-0a9b8c7d6e5f",
  "outcome": "created",
  "generation": {
    "generation_id": "3d1c0b9a-8e7f-4a6b-9c5d-4e3f2a1b0c9d",
    "doc_id": "a1f3e0b4-1c2d-5e6f-8a9b-0c1d2e3f4a5b",
    "version_id": "0f9e8d7c-6b5a-4c3d-2e1f-0a9b8c7d6e5f",
    "origin": "supplied",
    "status": "pending",
    "request_seq": 1,
    "input_hash": "9b1f…",
    "item_count": 2,
    "representation_id": null,
    "crossref_version": null,
    "errors": [],
    "created_at": "2025-11-15T10:02:31.551Z",
    "activated_at": null
  }
}

Errors

StatusdetailCause
404document_not_foundNo such document, or it is deleted.
404version_not_foundThe version is not a live version of this document.
413{"code": "reference_set_too_large", "limit_bytes": 67108864}The body is over 64 MiB.
422{"code": "invalid_reference_set", "line": 3, "message": "…"}A line is not a JSON object, or not a valid reference: a missing or unknown field, a pinned reference without target.version_key, an amends without change_date_known, or a date on another kind. line is the first failing line. Nothing was recorded.

Example

curl -s -X PUT "$REMEMBER_API_URL/documents/$DOC_ID/versions/$VERSION_ID/references" \
  -H "Authorization: Bearer $REMEMBER_API_KEY" \
  -H "Content-Type: application/x-ndjson" \
  --data-binary @references.ndjson
from remember import Client, ReferenceInput, ReferenceTarget
 
memory = Client()
result = memory.set_references(
    doc_id=doc_id,
    version_id=version_id,
    references=[
        ReferenceInput(
            kind="refers_to",
            from_section_key="approvals",
            target=ReferenceTarget(
                source_kind="intranet",
                source_ref="policy/expense",
                section_key="approvals-process",
            ),
        )
    ],
)
print(result.outcome, result.generation.status)

GET /documents/{doc_id}/versions/{version_id}/references

Report a version's reference generations, newest first: each supplied set and what became of it.

Scope: read.

Parameters

NameInTypeRequiredConstraints
doc_idpathUUIDyesA live document.
version_idpathUUIDyesA version of that document that is not deleted.

Response

200 with a ReferenceGenerations: doc_id, version_id and generations, newest first, at most 100 (an active generation is always included). Each generation's status is one of:

StatusMeaning
pendingRecorded, waiting for the pipeline to check and activate it.
activeIts references are the ones readers see. At most one per version and origin.
rejectedIt named a section the version does not have. errors lists up to 100 {item, field, reason} entries; item is the reference's 1-based position.
supersededA later set replaced it, or it was cancelled before it became active.

origin is supplied for sets sent through PUT. A generation with origin extracted would hold references the engine found in the text itself; this release finds none (What is not built yet).

Errors

StatusdetailCause
404document_not_foundNo such document, or it is deleted.
404version_not_foundThe version is not a live version of this document.

Example

curl -s "$REMEMBER_API_URL/documents/$DOC_ID/versions/$VERSION_ID/references" \
  -H "Authorization: Bearer $REMEMBER_API_KEY"
for generation in memory.reference_generations(doc_id=doc_id, version_id=version_id).generations:
    print(generation.status, generation.item_count, generation.errors)

GET /tags

List the deployment's registered tags. A tag is a name you declare, such as project:billing-migration, with a description of what it means; you assign tags to documents to say how you organize them. What tags are for and how to use them: Tag documents.

Scope: read.

Parameters

NameInTypeRequiredDefaultConstraints
queryquerystringno1 to 200 characters. Keeps the tags whose name or description contains it, ignoring letter case.
namequerystringno1 to 128 characters after Unicode NFC (at most 512 as sent). Keeps only the tag with exactly this name, matched the way the engine matches tag names (Unicode NFC, ignoring letter case); the list then has at most one tag. The Python and TypeScript clients use it to look up a tag's id from its name.

The list is ordered by name, ignoring letter case, and is not paged: a deployment registers at most 10,000 tags. It carries no document counts.

Response

200 with a TagList:

{
  "tags": [
    {
      "tag_id": "6b1d2f0e-8c4a-4f1e-9a3b-2d7c5e0f1a42",
      "name": "project:billing-migration",
      "description": "Documents about moving invoicing to the new billing provider: specs, decisions and meeting notes.",
      "created_at": "2026-11-13T09:12:44.102Z",
      "updated_at": "2026-11-13T09:12:44.102Z"
    }
  ]
}

Errors

StatusdetailCause
422validation listquery is empty or longer than 200 characters.

Example

curl -s "$REMEMBER_API_URL/tags?query=billing" \
  -H "Authorization: Bearer $REMEMBER_API_KEY"
for tag in memory.list_tags(query="billing").tags:
    print(tag.tag_id, tag.name, tag.description)

POST /tags

Register a tag. A tag must be registered before any document can carry it.

Scope: write.

Request body

FieldTypeRequiredConstraints
namestringyes1 to 128 characters after Unicode NFC normalization, with no whitespace or control characters.
descriptionstringyesAt most 2,000 characters. What the tag means and when to apply it, written for the agents that will choose it.

The name keeps the spelling you declare, and names are unique ignoring letter case: when project:billing-migration exists, Project:Billing-Migration finds it and cannot be registered again. The engine gives a name no structure; a key:value convention (project:…, kind:…) keeps a shared memory readable.

Response

200 with the new Tag, as in GET /tags.

Errors

StatusdetailCause
409{"code": "conflict", "message": …}A tag with this name, in any letter case, is already registered.
409{"code": "tag_limit_exceeded", "message": …}The deployment already has 10,000 tags.
422validation listA field is missing or unknown, the name is empty, too long or contains whitespace or a control character, or the description is over 2,000 characters.

Example

curl -s -X POST "$REMEMBER_API_URL/tags" \
  -H "Authorization: Bearer $REMEMBER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "project:billing-migration", "description": "Documents about moving invoicing to the new billing provider."}'
tag = memory.create_tag(
    name="project:billing-migration",
    description="Documents about moving invoicing to the new billing provider.",
)

PATCH /tags/{tag_id}

Rename a tag, change its description, or both. Every document that carries the tag keeps it.

Scope: write.

Parameters

NameInTypeRequiredConstraints
tag_idpathUUIDyesThe tag's id. Names can contain /, so the route takes the id; the SDK, CLI and MCP tools accept a name and look the id up first.

Request body

FieldTypeRequiredConstraints
namestringnoThe new name, with the rules of POST /tags.
descriptionstringnoThe new description, at most 2,000 characters.

Give at least one. A rename takes effect at once and keeps no alias: the old name stops resolving, so a call that still uses it gets unknown_tag.

Response

200 with the changed Tag; updated_at is the time of this change.

Errors

StatusdetailCause
404{"code": "unknown_tag", "message": …, "tags": […]}No tag has this id.
409{"code": "conflict", "message": …}Another tag already has the new name, in any letter case.
422validation listtag_id is not a UUID, the body has neither field or an unknown one, or a value breaks its rule.

Example

curl -s -X PATCH "$REMEMBER_API_URL/tags/6b1d2f0e-8c4a-4f1e-9a3b-2d7c5e0f1a42" \
  -H "Authorization: Bearer $REMEMBER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "project:billing"}'
memory.update_tag(tag="project:billing-migration", name="project:billing")

DELETE /tags/{tag_id}

Delete a tag and remove it from every document that carries it, in one step. The documents themselves are unchanged.

Scope: write.

Parameters

NameInTypeRequiredConstraints
tag_idpathUUIDyesThe tag's id.

Response

200 with the deleted Tag as it was.

Errors

StatusdetailCause
404{"code": "unknown_tag", "message": …, "tags": […]}No tag has this id, or it was already deleted.
422validation listtag_id is not a UUID.

Example

curl -s -X DELETE "$REMEMBER_API_URL/tags/6b1d2f0e-8c4a-4f1e-9a3b-2d7c5e0f1a42" \
  -H "Authorization: Bearer $REMEMBER_API_KEY"
memory.delete_tag(tag="project:billing")

POST /documents/{doc_id}/tags

Change the tags one document carries, in one atomic step: add and remove tags, or replace the whole set.

Scope: write.

Parameters

NameInTypeRequiredConstraints
doc_idpathUUIDyesA live document.

Request body

FieldTypeRequiredDefaultConstraints
addarray of stringsno[]At most 64. Tags to add, each by name (any letter case) or tag_id.
removearray of stringsno[]At most 64. Tags to remove.
setarray of stringsnoAt most 64. The document's complete set of tags. Excludes add and remove; [] removes every tag.

Each tag is 1 to 128 characters after Unicode NFC normalization, the rule tag names follow. Every tag named in any list must be registered; removing a registered tag the document does not carry is not an error. A call with none of the three fields changes nothing and returns the current tags. Changing tags starts no processing and creates no version.

Tags belong to the document, not to one version: every version carries the document's current tags.

Response

200 with a DocumentTags: the document's tags after the change, ordered by name ignoring letter case.

{
  "doc_id": "a1f3e0b4-1c2d-5e6f-8a9b-0c1d2e3f4a5b",
  "tags": ["kind:decision", "project:billing-migration"]
}

Errors

StatusdetailCause
404document_not_foundNo such document, or it is deleted.
409{"code": "tag_limit_exceeded", "message": …}The document would carry more than 64 tags. Nothing changed.
422{"code": "unknown_tag", "message": "unknown tags: …", "tags": […]}A tag in add, remove or set is not registered; tags lists every one. Nothing changed.
422validation listset together with add or remove, a list over 64 items, an empty or over-long tag, an unknown field, or doc_id not a UUID.

Example

curl -s -X POST "$REMEMBER_API_URL/documents/a1f3e0b4-1c2d-5e6f-8a9b-0c1d2e3f4a5b/tags" \
  -H "Authorization: Bearer $REMEMBER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"add": ["kind:decision"], "remove": ["kind:draft"]}'
result = memory.update_document_tags(
    doc_id="a1f3e0b4-1c2d-5e6f-8a9b-0c1d2e3f4a5b", set=["project:billing-migration"]
)
print(result.tags)