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
| Name | In | Type | Required | Default | Constraints |
|---|---|---|---|---|---|
filename | query | string | yes | At least 1 character. Its suffix is kept on the stored original; its stem is the title when title is absent. | |
mime | query | string | yes | At least 1 character. A format hint; recognizable bytes establish the content class first. | |
title | query | string | no | stem of filename | |
source_kind | query | string | no | At least 1 character. Must be sent together with source_ref. | |
source_ref | query | string | no | At least 1 character. Must be sent together with source_kind. | |
source_modified_at | query | date-time | no | UTC only (Z or +00:00). Requires source_kind and source_ref. | |
versioning_mode | query | snapshot | living | no | snapshot | living requires source_kind and source_ref. |
source_version_ref | query | string | no | The source system's own revision id. Requires source_kind and source_ref. | |
source_path | query | string | no | At 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_key | query | string | no | 1 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_from | query | date-time | no | UTC 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_until | query | date-time | no | UTC 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. | |
tags | query | string, repeatable | no | At 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-Kind | header | user | api_credential | service | no | Sent with X-Ingest-Principal-Ref. See Attribution. | |
X-Ingest-Principal-Ref | header | string | no | 1–255 printable ASCII characters. Sent with X-Ingest-Principal-Kind. | |
Content-Type | header | yes | application/octet-stream. | ||
Content-Length | header | integer | when 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
snapshotdocument. Alivingdocument refuses them with422effective_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
409effective_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
409version_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:
titleandversioning_modebelong 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-textcan be made Markdown by sending the same text bytes again astext/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
writescope.
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
| Status | detail | Cause |
|---|---|---|
411 | length_required | The deployment caps bodies and the request has no Content-Length. |
413 | body_too_large | The body is over the deployment's cap. |
409 | source_forgotten | A 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. |
422 | source_kind and source_ref must be supplied together | Only one of the pair was sent. |
422 | source timestamps, revisions, living mode, version keys and effective periods require source_kind/source_ref | source_modified_at, source_version_ref, versioning_mode=living, version_key or effective_from without a source identity. |
422 | source_modified_at must be timezone-aware UTC | The timestamp has no offset or a non-zero one. The same message names effective_from or effective_until for those parameters. |
422 | effective_until requires an earlier effective_from | effective_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. |
422 | X-Ingest-Principal-Kind and X-Ingest-Principal-Ref must be supplied together | Trusted attribution with only one header. |
422 | invalid_ingest_principal | Trusted attribution with an unknown kind or a malformed reference. |
422 | content_type_mismatch | The declared MIME contradicts a content class identified from the bytes. No original or catalog row is written. |
422 | ambiguous_office_format | Legacy Office container bytes have no declared Word, Excel or PowerPoint subtype. |
422 | validation list | filename 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.mdfrom 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
| Field | Type | Required | Constraints |
|---|---|---|---|
version_ids | array of UUID | yes | 1 to 1,000 items. Duplicates are collapsed. |
require | object | yes | All four fields below are required. |
require.pipeline | boolean | yes | Every expected stage has finished for every version. |
require.p1 | boolean | yes | The search index (claims, chunks, facts) is published. |
require.live_graph | boolean | yes | The live graph passes its health checks. |
require.p3 | boolean | yes | Every 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:
| Capability | reason when ready | reason when not ready |
|---|---|---|
pipeline | ready | stage_incomplete |
p1 | ready | search_channel_incomplete |
p3 | ready | corpus_publication_incomplete, p3_version_not_served |
live_graph | ready | graph_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
| Status | detail | Cause |
|---|---|---|
422 | validation list | Empty 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
| Name | In | Type | Required | Default | Constraints |
|---|---|---|---|---|---|
limit | query | integer | no | 50 | 1 to 200. |
cursor | query | string | no | The next_cursor from the previous page. Opaque. | |
status | query | ingesting | converting | structuring | ready | failed | no | Filters 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
| Status | detail | Cause |
|---|---|---|
400 | cursor is malformed | The cursor does not parse. |
422 | validation list | limit 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
| Field | Type | Required | Default | Constraints |
|---|---|---|---|---|
query | string | no | 1 to 4,096 characters. Words from the file name, title, source path or text. | |
filters | object | no | {} | See below. Every filter you give must hold. |
versions | current | all | no | current | Which versions of each document may match. |
time | object | no | {"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. |
k | integer | no | 20 | Ranked results with query: 1 to 200. |
limit | integer | no | 50 | Browse page size without query: 1 to 200. |
cursor | string | no | The next_cursor from the previous page. Only without query. |
filters:
| Field | Type | Meaning |
|---|---|---|
family | array of strings | The 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. |
authors | array of strings | A name or an address. Any listed term matches. |
recipients | array of strings | The same, for recipients. |
created_from, created_to | date-time with timezone | The date the document declares it was created or sent, inclusive. A document that declares no date does not match a range. |
modified_from, modified_to | date-time with timezone | The declared last-modified date, inclusive. |
language | string | Exact match. |
thread_ref | string | The conversation or thread key, exact match. |
doc_ids | array of UUIDs | Only these documents. |
tags | object | The 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:
| Field | Matches a document that carries |
|---|---|
all | every listed tag |
any | at least one listed tag |
none | none 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
| Status | detail | Cause |
|---|---|---|
400 | cursor is malformed | The cursor does not parse. |
422 | validation list | An 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
| Name | In | Type | Required | Constraints |
|---|---|---|---|---|
doc_id | path | UUID | yes | The 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
| Status | detail | Cause |
|---|---|---|
404 | document_not_found | No such document, or it is already deleted. Do not retry. |
403 | credential may not perform this operation | The credential has read or ingest scope. |
422 | validation list | doc_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:
raisePUT /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
| Name | In | Type | Required | Constraints |
|---|---|---|---|---|
doc_id | path | UUID | yes | A live document. |
version_id | path | UUID | yes | A version of that document that is not deleted. |
Request body
| Field | Type | Required | Constraints |
|---|---|---|---|
periods | array of objects | yes | 0 to 1,000 items, no two with the same effective_from. |
periods[].effective_from | date-time | yes | UTC (Z or +00:00). Included. |
periods[].effective_until | date-time | no | UTC. 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
livingdocument is refused with422.
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
| Status | detail | Cause |
|---|---|---|
404 | document_not_found | No such document, or it is deleted. |
404 | version_not_found | The 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. |
422 | validation list | A 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
| Name | In | Type | Required | Constraints |
|---|---|---|---|---|
doc_id | path | UUID | yes | A 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
| Status | detail | Cause |
|---|---|---|
404 | document_not_found | No such document, or it is deleted. |
422 | validation list | doc_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
| Name | In | Type | Required | Constraints |
|---|---|---|---|---|
doc_id | path | UUID | yes | A live document. |
version_id | path | UUID | yes | A version of that document that is not deleted. |
Content-Type | header | no | application/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:
| Field | Type | Required | Constraints |
|---|---|---|---|
kind | string | yes | refers_to, amends, implements, cites, links_to, attaches or replies_to. See Reference kinds. |
from_section_key | string | no | The 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_kind | string | yes | 1 to 128 characters. The target document's source_kind. |
target.source_ref | string | yes | 1 to 512 characters. The target document's source_ref. The target need not be ingested yet. |
target.version_key | string | with binding: pinned | 1 to 512 characters. The target version's version_key. |
target.section_key | string | no | A section key in the target; omitted, the whole document. Same syntax as from_section_key. |
binding | floating | pinned | no | Default 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_known | boolean | with kind: amends | Whether the source states when its change takes effect. Only for amends. |
change_effective_from | date-time | with change_date_known: true | UTC. When the change takes effect. Only for amends, and forbidden when change_date_known is false. |
source_label | string | no | 1 to 200 characters. Your own type code for the reference, returned as you sent it. |
context | string | no | 1 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
| Kind | Meaning |
|---|---|
refers_to | An in-text pointer to another passage or document: "see section 4.2", "as defined in section 3". |
amends | The source changes the target's text or force: an amendment to a contract clause. |
implements | The source elaborates or carries out the target: a procedure that implements a policy. |
cites | A bibliographic citation. |
links_to | A hyperlink. |
attaches | Container membership, such as an e-mail attachment. |
replies_to | Conversation 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:
outcomeisunchanged. - The set that is already active, sent while a newer set is still
pending, cancels the pending set:
outcomeispending_cancelled, and the active set stays. - Any other set is recorded as a new
pendinggeneration and replaces every older pending one:outcomeiscreated.
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
| Status | detail | Cause |
|---|---|---|
404 | document_not_found | No such document, or it is deleted. |
404 | version_not_found | The 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.ndjsonfrom 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
| Name | In | Type | Required | Constraints |
|---|---|---|---|---|
doc_id | path | UUID | yes | A live document. |
version_id | path | UUID | yes | A 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:
| Status | Meaning |
|---|---|
pending | Recorded, waiting for the pipeline to check and activate it. |
active | Its references are the ones readers see. At most one per version and origin. |
rejected | It 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. |
superseded | A 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
| Status | detail | Cause |
|---|---|---|
404 | document_not_found | No such document, or it is deleted. |
404 | version_not_found | The 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
| Name | In | Type | Required | Default | Constraints |
|---|---|---|---|---|---|
query | query | string | no | 1 to 200 characters. Keeps the tags whose name or description contains it, ignoring letter case. | |
name | query | string | no | 1 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
| Status | detail | Cause |
|---|---|---|
422 | validation list | query 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
| Field | Type | Required | Constraints |
|---|---|---|---|
name | string | yes | 1 to 128 characters after Unicode NFC normalization, with no whitespace or control characters. |
description | string | yes | At 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
| Status | detail | Cause |
|---|---|---|
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. |
422 | validation list | A 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
| Name | In | Type | Required | Constraints |
|---|---|---|---|---|
tag_id | path | UUID | yes | The 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
| Field | Type | Required | Constraints |
|---|---|---|---|
name | string | no | The new name, with the rules of POST /tags. |
description | string | no | The 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
| Status | detail | Cause |
|---|---|---|
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. |
422 | validation list | tag_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
| Name | In | Type | Required | Constraints |
|---|---|---|---|---|
tag_id | path | UUID | yes | The tag's id. |
Response
200 with the deleted Tag as it was.
Errors
| Status | detail | Cause |
|---|---|---|
404 | {"code": "unknown_tag", "message": …, "tags": […]} | No tag has this id, or it was already deleted. |
422 | validation list | tag_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
| Name | In | Type | Required | Constraints |
|---|---|---|---|---|
doc_id | path | UUID | yes | A live document. |
Request body
| Field | Type | Required | Default | Constraints |
|---|---|---|---|---|
add | array of strings | no | [] | At most 64. Tags to add, each by name (any letter case) or tag_id. |
remove | array of strings | no | [] | At most 64. Tags to remove. |
set | array of strings | no | At 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
| Status | detail | Cause |
|---|---|---|
404 | document_not_found | No 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. |
422 | validation list | set 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)