RememberStackremember.dev/docs

Python SDK

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

The remember package is the Python client for RememberStack. You use it to store documents, wait until they are processed, and ask the memory what it knows.

This page lists every public name the package exports. For the fields inside a result (facts, claims, validity windows, negatives), see Result types.

Install

pip install remember

The package needs Python 3.12 or newer. It depends only on httpx, pydantic and pydantic-settings; it does not contain the engine. To run the engine, see Install with Docker Compose.

pip install remember also installs the remember command. See CLI.

The client is synchronous. There is no async client yet (What is not built yet).

Public names

remember.__all__ contains these names:

NameKindSection
ClientclassClient
RememberClientalias of ClientClient
MemoryClientclassMemoryClient
resolve_connectionfunctionConnecting
MemoryApiErrorexceptionErrors
RateLimitedexceptionErrors
StoredKeyRefusedexceptionErrors
PipelineDeadLetteredexceptionErrors
LayerUnavailableexceptionErrors
UnknownTagexceptionErrors
ConnectorNotFoundErrorexceptionErrors
CapabilityReadinessmodelModels
ClaimOccurrencemodelModels
ClaimValidPrecisionenumModels
ConnectorCreatemodelModels
ConnectorDescriptormodelModels
ContextBundleV2modelModels
DeclaredEffectivePeriodmodelModels
DeploymentBuildInfomodeldeployment_build_info
DocumentDeletionmodelModels
DocumentPagemodelModels
DocumentReferencemodelModels
DocumentReferenceSourcemodelModels
DocumentReferencesPagemodelModels
DocumentReferencesRequestmodelModels
DocumentReferencesTooBroadmodelModels
DocumentReferenceTargetmodelModels
DocumentSearchFiltersmodelModels
DocumentSearchPagemodelModels
DocumentSearchRequestmodelModels
DocumentSearchResultmodelModels
DocumentSummarymodelModels
DocumentTagFiltermodelModels
DocumentTagsmodelModels
DocumentVersionSummarymodelModels
EffectiveIntervalmodelModels
EffectivePeriodInputmodelModels
EffectivePeriodsSetmodelModels
EffectiveTimeClearedmodelModels
EnvelopemodelModels
IngestedVersionmodelModels
MatchingEditionmodelModels
NamedReferenceTargetmodelModels
NegativeKindenumResult types
PipelineReadinessReportmodelModels
PipelineStageReadinessmodelModels
ProcessingLayerenumModels
ProcessingLayerStatesmodelModels
QueryResultDictdict subclassModels
ReadinessRequirementsmodelModels
ReadTimetype aliasModels
ReferenceGenerationmodelModels
ReferenceGenerationsmodelModels
ReferenceInputmodelModels
ReferenceItemErrormodelModels
ReferencesSetmodelModels
ReferenceTargetmodelModels
ReferenceWindowmodelModels
ScopePendingmodelModels
SectionAmendmentmodelModels
SectionHistoryPagemodelModels
SectionHistoryRequestmodelModels
SectionHistoryRowmodelModels
SectionHistorySectionmodelModels
TagmodelModels
TagListmodelModels
TemporalMatchenumModels
ToolDescriptormodelModels
VersionPipelineReadinessmodelModels
__version__stringThe installed package version, for example "0.17.0".

remember.credentials.CredentialError, raised when the credential file is unreadable or not in the current format, lives outside __all__. See Errors.

Which client to use

You want toUse
Store and retrieve memory (the usual case)Client (same as RememberClient)
The same, without the file-path ingest shortcutMemoryClient

Client is a subclass of MemoryClient. Every method listed under MemoryClient is available on Client.

Connecting

Client and MemoryClient resolve their connection the way the CLI does, with one function, remember.resolve_connection(). Each setting is resolved on its own; first match wins:

Setting1. Argument2. Environment3. Credential file4. Otherwise
Keyapi_keyREMEMBER_API_KEYkeyno key
Addressbase_urlREMEMBER_API_URLapi_urlhttp://127.0.0.1:8000
ProjectprojectREMEMBER_PROJECTdefault_projectnone

The credential file is the one the CLI writes (CLI: credential file). It is read only when a setting is not given as an argument or in the environment.

A key read from the credential file is only sent to the address stored beside it. When base_url or REMEMBER_API_URL names another address, the first request raises StoredKeyRefused; pass the key explicitly to use it there. A key you pass as an argument or in REMEMBER_API_KEY is sent wherever you point it.

export REMEMBER_API_URL=http://localhost:8000
export REMEMBER_API_KEY=<the key your engine accepts, if any>
import remember
 
with remember.Client() as memory:
    print(memory.deployment_build_info().build_revision)

Client

class remember.Client(MemoryClient)
remember.RememberClient = remember.Client

The client for one deployment. It talks directly to the deployment's own address.

Constructor

Client(
    *,
    api_key: str | None = None,
    base_url: str | None = None,
    project: str | None = None,
    timeout: float = 300.0,
    client: httpx.Client | None = None,
    transport: httpx.BaseTransport | None = None,
)

All parameters are keyword-only.

ParameterMeaning
api_keyThe API key. A bare key or a full Bearer … value.
base_urlThe deployment address.
projectWhich project to use, by id or name, when the key covers several.
timeoutSeconds per HTTP request. Default 300.
clientAn httpx.Client you built yourself, with its own address and headers. It cannot be combined with any other parameter, and nothing is resolved. The SDK does not close a client you pass in.
transportAn httpx transport to use instead of the network (for tests or a proxy).

How each setting is chosen: Connecting. Creating a client makes no network call.

Raises:

  • ValueError when client is combined with another parameter.
  • ValueError when the key is empty, is the bare word Bearer, or contains a line break.
  • remember.credentials.CredentialError when the credential file has to be read and is unreadable or not in the current format.

Client.ingest

Inherited unchanged from MemoryClient.ingest.

Client.ingest_file

Client.ingest_file(
    file_path: str | Path,
    *,
    filename: str | None = None,
    mime: str | None = None,
    title: str | None = None,
    source_kind: str | None = None,
    source_ref: str | None = None,
    source_modified_at: datetime | None = None,
    versioning_mode: Literal["snapshot", "living"] = "snapshot",
    source_version_ref: str | None = None,
    source_path: str | None = None,
    version_key: str | None = None,
    effective_from: datetime | None = None,
    effective_until: datetime | None = None,
    tags: Sequence[str] | None = None,
) -> IngestedVersion

Reads one file and ingests it. It calls ingest(file_path, …) with the same arguments.

version = memory.ingest_file("notes/billing-migration-kickoff.md")

Context manager

with remember.Client() as memory: returns the client and closes its HTTP connection pool when the block ends. Outside a with block, call memory.close() yourself. close() closes only a connection pool the SDK created; a client= you injected stays open.

MemoryClient

class remember.MemoryClient

The typed client every other memory client builds on.

Constructor

MemoryClient takes the same parameters as Client and resolves its connection the same way (Connecting).

MemoryClient supports with and close() the same way Client does.

Method summary

MethodHTTP routeReturns
ingestPOST /ingestIngestedVersion
pipeline_readinessPOST /readinessPipelineReadinessReport
wait_for_readinessPOST /readiness, repeatedPipelineReadinessReport
deployment_build_infoGET /deploymentDeploymentBuildInfo
processing_layersGET /processing-layersProcessingLayerStates
list_documentsGET /documentsDocumentPage
search_documentsPOST /documents/searchDocumentSearchPage
delete_documentDELETE /documents/{doc_id}DocumentDeletion
list_tagsGET /tagsTagList
create_tagPOST /tagsTag
update_tagPATCH /tags/{tag_id}Tag
delete_tagDELETE /tags/{tag_id}Tag
update_document_tagsPOST /documents/{doc_id}/tagsDocumentTags
set_effective_periodsPUT /documents/{doc_id}/versions/{version_id}/effective-periodsEffectivePeriodsSet
clear_effective_timeDELETE /documents/{doc_id}/effective-periodsEffectiveTimeCleared
set_referencesPUT /documents/{doc_id}/versions/{version_id}/referencesReferencesSet
reference_generationsGET /documents/{doc_id}/versions/{version_id}/referencesReferenceGenerations
section_historyGET /documents/{doc_id}/sections/{section_key}/historySectionHistoryPage
document_referencesPOST /documents/referencesDocumentReferencesPage
list_operationsGET /operationstuple[ToolDescriptor, ...]
run_operationPOST /operations/{name}Envelope or ContextBundleV2
facts_contextPOST /operations/facts_contextEnvelope
claims_and_sources_contextPOST /operations/claims_and_sources_contextEnvelope
combined_contextPOST /operations/combined_contextContextBundleV2
resolve_entityPOST /operations/resolve_entityEnvelope
resolveGET /resolveEnvelope
lookup_relationsGET /lookup/relationsEnvelope
lookup_observationsGET /lookup/observationsEnvelope
transcript_relationGET /transcript/relation/{id}Envelope
hydrate_relationGET /hydrate/relation/{id}Envelope
search_claimsGET /search/claimsEnvelope
search_chunksGET /search/chunksEnvelope
adjacent_chunksGET /chunks/{id}/adjacentEnvelope
graph_neighborhoodPOST /graph/neighborhoodEnvelope
graph_pathPOST /graph/pathEnvelope
graph_citation_pathPOST /graph/citation-pathEnvelope
query_sqlPOST /query/sqldict
open_queryPOST /query/sqlQueryResultDict
explain_sqlPOST /query/sql/explaindict
explain_queryPOST /query/sql/explainQueryResultDict
describe_query_spaceGET /query/spacedict
search_query_spaceGET /query/space/searchlist[dict]
list_saved_queriesGET /query/savedlist[dict]
describe_saved_queryGET /query/saved/{namespace}/{name}dict
run_saved_queryPOST /query/saved/{namespace}/{name}/rundict
call_open_queryone of the /query/* routesobject
Connector methods/connectors…not served

Every method raises MemoryApiError when the deployment answers with an error status, when the network fails (status_code 0), or when a success response does not match the expected shape (status_code 200). Methods also raise ValueError for the client-side checks listed with each one.

The HTTP routes are documented in the HTTP API reference.

Store

ingest

MemoryClient.ingest(
    source: bytes | Path | str | None = None,
    *,
    content: bytes | None = None,
    filename: str | None = None,
    mime: str | None = None,
    title: str | None = None,
    source_kind: str | None = None,
    source_ref: str | None = None,
    source_modified_at: datetime | None = None,
    versioning_mode: Literal["snapshot", "living"] = "snapshot",
    source_version_ref: str | None = None,
    source_path: str | None = None,
    version_key: str | None = None,
    effective_from: datetime | None = None,
    effective_until: datetime | None = None,
    tags: Sequence[str] | None = None,
) -> IngestedVersion

Uploads one document. The call returns as soon as the engine has stored the bytes; processing runs afterwards. Wait with wait_for_readiness before you expect the content in results.

ParameterMeaning
sourceA Path or str file path (read from disk), or bytes.
contentRaw bytes. Wins over source when both are given; source then only supplies the fallback filename. For a string path this is str(Path(source)), which normalizes redundant separators and ./. Set filename explicitly to control the name.
filenameRequired for bytes. Defaults to the file's name for a path.
mimeMedia type; an explicit value always wins. Defaults to the type of the extension of the file's real name (for a path) or of filename (for bytes): .md is text/markdown, .pdf is application/pdf, on every Python installation; the full table is in Ingest files. An extension outside that table takes the type your Python installation's MIME database gives it, or application/octet-stream if it has none. The engine converts only media types it has a converter for; see File formats and converters.
titleA human title for the document.
source_kind, source_refThe document's stable identity: what kind of source it is and its id within that kind. Always together. Ingesting again with the same pair creates a new version of the same document when the bytes differ. See Documents, versions and sources.
source_modified_atWhen the source itself last changed. Must be timezone-aware UTC. Requires source_kind/source_ref.
versioning_mode"snapshot" (default) or "living". "living" requires source_kind/source_ref. See Updating a source.
source_version_refThe source system's own revision label. Requires source_kind/source_ref.
source_pathWhere the file lives at its source, such as a folder path or a URL. Recorded with the version's names; sending the same bytes again with a different filename, title or source_path records the new name without creating a version. See File names, titles and paths.
version_keyYour permanent name for this version, unique within the document (1 to 512 characters). A key new to the document always creates a version; the latest version's key is accepted again only with the same bytes. Requires source_kind/source_ref. See Versions in force.
effective_fromStart (included) of the period this version's text is in force. Timezone-aware UTC. Requires source_kind/source_ref and versioning_mode="snapshot".
effective_untilEnd (excluded) of that period, later than effective_from. Timezone-aware UTC. Omitted: the period lasts until the next declared start.
tagsRegistered tags, each a name (any letter case) or tag_id, added to the document's tags; at most 64. Ingest only adds tags and they never decide whether a version is created. See Tags.

Raises ValueError when:

  • only one of source_kind and source_ref is given;
  • source_modified_at, source_version_ref, versioning_mode="living", version_key, effective_from or effective_until is given without source_kind/source_ref;
  • source_modified_at, effective_from or effective_until is naive or not UTC;
  • effective_until is given without effective_from, or is not later than it, or a period is given with versioning_mode="living";
  • neither source nor content is given;
  • bytes are given without filename;
  • tags is a single string instead of a sequence.

Reading a path can raise OSError: FileNotFoundError when it does not exist, whether given as Path or str.

Returns IngestedVersion. created is False when these exact bytes were already stored for this document; no new processing starts. A version_key that names another version, or a start that another version already declares, raises MemoryApiError with status_code 409; a period on a living document raises it with 422. A tag that is not registered raises UnknownTag and nothing is stored.

from datetime import UTC, datetime
from pathlib import Path
 
version = memory.ingest(
    Path("specs/billing-migration.md"),
    title="Billing migration spec",
    source_kind="notes",
    source_ref="specs/billing-migration.md",
    source_modified_at=datetime(2026, 9, 21, 14, 0, tzinfo=UTC),
)
print(version.doc_id, version.version_id, version.created)

pipeline_readiness

MemoryClient.pipeline_readiness(
    *, version_ids: tuple[UUID, ...], require: ReadinessRequirements
) -> PipelineReadinessReport

Asks, once, whether the given versions have finished processing and whether the capabilities you name are ready. require must name all four capabilities (pipeline, p1, live_graph, p3) as True or False.

Raises ValueError when version_ids is empty.

report = memory.pipeline_readiness(
    version_ids=(version.version_id,),
    require=remember.ReadinessRequirements(
        pipeline=True, p1=True, live_graph=True, p3=False
    ),
)
for v in report.versions:
    print(v.version_id, v.ready, [(s.stage, s.status) for s in v.stages])

What each capability means: The pipeline and readiness.

wait_for_readiness

MemoryClient.wait_for_readiness(
    version_ids: Sequence[str | UUID],
    *,
    timeout: float = 1800.0,
    poll_interval: float = 15.0,
    require_p3: bool = False,
) -> PipelineReadinessReport

Calls pipeline_readiness at once and then every poll_interval seconds until the report says ready, requiring pipeline, p1 and live_graph (and p3 when require_p3=True). Returns the ready report. The defaults, 30 minutes and 15 seconds, are starting points sized for single documents; raise timeout for bulk loads.

A stage that is failed has a retry scheduled, so the method keeps polling. A stage that is dead_letter has used all its attempts and never becomes ready, so the method stops at once.

Raises:

  • PipelineDeadLettered when any stage of any listed version is dead_letter;
  • TimeoutError when timeout seconds pass first;
  • ValueError when an id is not a UUID.

See Wait until a document is queryable.

memory.wait_for_readiness([version.version_id])

deployment_build_info

MemoryClient.deployment_build_info() -> DeploymentBuildInfo

Returns which engine build and which model bindings the deployment is serving: build_revision (str), model_bindings (dict of str to str), document_binding_generation (str or None), and tools (dict of MCP memory tool name to tool version). The class is remember.DeploymentBuildInfo.

info = memory.deployment_build_info()
print(info.build_revision, info.model_bindings.get("claim_extraction"))

processing_layers

MemoryClient.processing_layers() -> ProcessingLayerStates

Returns the state of each switchable processing layer: claims and facts, each "enabled", "backfilling" or "disabled".

layers = memory.processing_layers()
if layers.facts == "disabled":
    answer = memory.claims_and_sources_context("harbour tariff")

list_documents

MemoryClient.list_documents(
    *,
    limit: int = 50,
    cursor: str | None = None,
    status: Literal["ingesting", "converting", "structuring", "ready", "failed"] | None = None,
) -> DocumentPage

Returns one page of the deployment's documents, newest document first, as a DocumentPage. Pass the returned next_cursor as cursor to read the next page; it is None on the last page. status keeps only documents whose newest version has that status. limit is 1 to 200; the deployment answers 422 outside that range. Deleted documents are not listed. See GET /documents.

cursor = None
while True:
    page = memory.list_documents(cursor=cursor)
    for document in page.documents:
        print(document.doc_id, document.title, document.serving)
    if page.next_cursor is None:
        break
    cursor = page.next_cursor

search_documents

MemoryClient.search_documents(
    query: str | None = None,
    *,
    filters: DocumentSearchFilters | None = None,
    versions: Literal["current", "all"] = "current",
    k: int = 20,
    limit: int = 50,
    cursor: str | None = None,
    time: ReadTime | None = None,
) -> DocumentSearchPage

Finds documents by the names they were stored under, their general metadata and their text, and returns a DocumentSearchPage. filters is a DocumentSearchFilters (from remember import DocumentSearchFilters): family, authors, recipients, the created_*/modified_* ranges, language, thread_ref, doc_ids and tags, a DocumentTagFilter (all, any, none) of tag names or ids. With a query the results are ranked and not paged; without one they are newest ingested first and limit (default 50) / cursor pages them. Read next_cursor for continuation; ranked responses disclose truncated. Passing cursor with a query, a date without a timezone, k / limit outside 1 to 200, or an empty or repeating tag list raises pydantic.ValidationError before any request. A malformed cursor raises MemoryApiError with status_code 400; a tag that is not registered raises remember.UnknownTag, whose tags lists every one. time decides which editions of a document with declared effective periods are candidates (default: the ones in force now); it takes the same values as in search_chunks. What matches, and how, is in POST /documents/search.

The result's p3_path is relative to the corpus root and non-null only when that version is served and its nullable publication marker matches current export inputs. Historical, raw-only, unpublished, updating and failed publications return None. served_version describes currency independently. Resolve again with DocumentSearchFilters(doc_ids=(doc_id,)) after a folder move; suffix lookup works offline. Only the suffix is stable within a folder path.

from remember import Client, DocumentSearchFilters
 
memory = Client()
page = memory.search_documents("audit report")
emails = memory.search_documents(
    filters=DocumentSearchFilters(authors=("[email protected]",)), limit=50
)
if len(emails.people_matched) > 1:
    print("several people matched:", emails.people_matched)
 
from remember import DocumentTagFilter
 
decisions = memory.search_documents(
    filters=DocumentSearchFilters(
        tags=DocumentTagFilter(all=("kind:decision",), none=("project:ci-smoke",))
    )
)

delete_document

MemoryClient.delete_document(*, doc_id: UUID | str) -> DocumentDeletion

Removes one document, every version of it, from the memory and returns a DocumentDeletion with doc_id, deleted_at, claims_retired, relations_closed and observations_closed. Its claims stop counting as evidence, and facts that only it supported are closed with a recorded retraction. The claims and the stored original are kept as history. Needs a write credential. See DELETE /documents/{doc_id}.

Raises ValueError before sending anything when doc_id is not a UUID, and MemoryApiError with status_code 404 and detail "document_not_found" when the document does not exist or is already deleted.

from remember import MemoryApiError
 
try:
    deletion = memory.delete_document(doc_id=version.doc_id)
    print(f"{deletion.claims_retired} claims retired")
except MemoryApiError as error:
    if error.status_code != 404:
        raise

Tags

Tags are names you register, such as project:billing-migration, each with a description, and assign to documents. A walkthrough is in Tag documents. Wherever a method takes a tag, it accepts the name in any letter case or the tag_id. Every method here except list_tags needs a write credential.

list_tags

MemoryClient.list_tags(*, query: str | None = None) -> TagList

Returns every registered tag, ordered by name ignoring letter case, as a TagList whose tags are Tag models (tag_id, name, description, created_at, updated_at). query (1 to 200 characters) keeps the tags whose name or description contains it, ignoring letter case.

create_tag

MemoryClient.create_tag(*, name: str, description: str) -> Tag

Registers a tag. The name is normalized to Unicode NFC and must be 1 to 128 characters with no whitespace or control characters; the description is at most 2,000 characters. Raises pydantic.ValidationError for a name or description that breaks these rules, before any request, and MemoryApiError with status_code 409 and code "conflict" when the name is already registered in any letter case, or code "tag_limit_exceeded" when the deployment has 10,000 tags.

update_tag

MemoryClient.update_tag(
    *,
    tag: UUID | str,
    name: str | None = None,
    description: str | None = None,
) -> Tag

Renames a tag, changes its description, or both; give at least one (pydantic.ValidationError otherwise). Documents keep the tag, and the old name stops resolving at once. A name is first looked up with GET /tags?name=…, which the engine matches the way it matches every tag name; a tag that is not registered raises UnknownTag with status_code 404. A new name another tag has raises MemoryApiError 409 with code "conflict".

delete_tag

MemoryClient.delete_tag(*, tag: UUID | str) -> Tag

Deletes the tag and removes it from every document that carries it, and returns the deleted Tag. An unregistered tag raises UnknownTag with status_code 404.

update_document_tags

MemoryClient.update_document_tags(
    *,
    doc_id: UUID | str,
    add: Sequence[str] | None = None,
    remove: Sequence[str] | None = None,
    set: Sequence[str] | None = None,
) -> DocumentTags

Changes one document's tags in one step and returns a DocumentTags with the tags afterwards. Give add and remove, or set to replace the whole set (set=[] removes every tag); each list holds at most 64 tags. Removing a registered tag the document does not carry is not an error. Changing tags starts no processing.

Raises ValueError before sending anything when doc_id is not a UUID or a list is a single string, pydantic.ValidationError when set is combined with add or remove, UnknownTag when a tag is not registered (nothing changes), and MemoryApiError with status_code 404 for an unknown or deleted document, or 409 with code "tag_limit_exceeded" past 64 tags.

tags = memory.update_document_tags(
    doc_id=version.doc_id, add=["project:billing-migration", "kind:decision"]
)
print(tags.tags)

Versions in force, sections and references

What these methods are for, with a worked example: Read a document as of a date.

set_effective_periods

MemoryClient.set_effective_periods(
    *,
    doc_id: UUID | str,
    version_id: UUID | str,
    periods: Sequence[EffectivePeriodInput],
) -> EffectivePeriodsSet

Replaces the periods during which one version's text is in force. periods is the version's complete set: each EffectivePeriodInput has effective_from and an optional effective_until, both timezone-aware UTC datetime values (or ISO 8601 strings with a zero offset). Periods not listed are withdrawn and new ones declared, in one step. An empty sequence leaves the version with no period while the document keeps reading by period. Needs a write credential. Raises pydantic.ValidationError before any request for an end not after its start, two periods with the same start, or more than 1,000 periods; MemoryApiError with status_code 409 when another version declares the same start, 422 for a living document, 404 for an unknown document or version. See PUT …/effective-periods.

clear_effective_time

MemoryClient.clear_effective_time(*, doc_id: UUID | str) -> EffectiveTimeCleared

Withdraws every declared period of a document and returns it to "the newest processed version is current". cleared_at is None when the document had no declared periods. Needs a write credential. Raises MemoryApiError with status_code 404 for an unknown or deleted document.

set_references

MemoryClient.set_references(
    *,
    doc_id: UUID | str,
    version_id: UUID | str,
    references: Sequence[ReferenceInput],
) -> ReferencesSet

Replaces one version's supplied references, sent as NDJSON. ReferenceInput has kind, from_section_key, target (a ReferenceTarget with source_kind, source_ref, version_key, section_key), binding, change_effective_from, change_date_known, source_label and context; its rules are checked when you build it. outcome is created, unchanged or pending_cancelled. Needs a write credential. Raises MemoryApiError with status_code 404, 413 (over 64 MiB) or 422. See PUT …/references.

reference_generations

MemoryClient.reference_generations(
    *, doc_id: UUID | str, version_id: UUID | str
) -> ReferenceGenerations

Returns the version's reference generations, newest first, each with its status (pending, active, rejected, superseded) and errors.

section_history

MemoryClient.section_history(
    *,
    doc_id: UUID | str,
    section_key: str,
    time: ReadTime | None = None,
    limit: int = 50,
    cursor: str | None = None,
) -> SectionHistoryPage

Follows one keyed section across the document's versions. time defaults to {"mode": "history"}. Each row is a version with its effective intervals and a status of present, absent, not_indexed or processing. Raises pydantic.ValidationError for a malformed key or limit outside 1 to 200, and MemoryApiError with status_code 404 for an unknown or deleted document. section_history_request(request=…) sends a prepared SectionHistoryRequest. See GET …/sections/{section_key}/history.

page = memory.section_history(doc_id=doc_id, section_key="per-diem")

document_references

MemoryClient.document_references(
    *,
    chunk_id: UUID | str | None = None,
    doc_id: UUID | str | None = None,
    section_key: str | None = None,
    direction: Literal["outgoing", "incoming", "both"] = "both",
    kinds: Sequence[ReferenceKind] | None = None,
    time: ReadTime | None = None,
    limit: int = 50,
    cursor: str | None = None,
) -> DocumentReferencesPage

Lists what a passage (chunk_id) or a document or section (doc_id, with an optional section_key) references, and what references it, each reference resolved against the target versions in force during its source window. Give exactly one of chunk_id and doc_id; pydantic.ValidationError otherwise. Raises MemoryApiError with status_code 404 for an unknown document or passage. document_references_request(request=…) sends a prepared DocumentReferencesRequest. See POST /documents/references.

page = memory.document_references(doc_id=doc_id, section_key="approvals", direction="outgoing")
for row in page.rows:
    print(row.kind, row.status, row.named_target.source_ref)

Assured operations

The four assured operations are the recommended way to ask the memory a question. Their full contracts are in Assured operations.

list_operations

MemoryClient.list_operations() -> tuple[ToolDescriptor, ...]

Returns the descriptors of the deployment's operations: resolve_entity, claims_and_sources_context, facts_context, combined_context. Each descriptor carries the operation's input schema.

for op in memory.list_operations():
    print(op.name, op.version, op.input_schema.get("required"))

run_operation

MemoryClient.run_operation(
    *,
    name: str,
    arguments: Mapping[str, object] | None = None,
    layers: Sequence[str] | None = None,
) -> Envelope | ContextBundleV2

layers narrows the processing layers the operation may read (any of "sources", "claims", "facts"; default every layer the deployment serves). See Narrowing a read to layers.

Runs one operation by name with its JSON arguments. Returns a ContextBundleV2 when the response is a combined bundle, otherwise an Envelope. Use it for arguments the convenience methods below do not expose (k, evidence_per_fact, candidate_k, entity_ids on claims_and_sources_context).

The engine validates arguments and answers with an error (raised as MemoryApiError) for an unknown name, a missing required argument, an unknown argument or a value outside its bounds.

result = memory.run_operation(
    name="facts_context",
    arguments={"query": "Who owns the billing migration?", "k": 25},
)

facts_context

MemoryClient.facts_context(
    query: str,
    *,
    k: int | None = None,
    candidate_k: int | None = None,
    time: Mapping[str, object] | None = None,
    hops: int | None = None,
    predicate: str | None = None,
    entity_ids: Sequence[str | UUID] | None = None,
    documents: DocumentSearchFilters | Mapping[str, object] | None = None,
) -> Envelope

Returns the facts the memory holds true that match query, with their evidence.

ArgumentConstraint (checked by the engine)
query1 to 8,192 characters
time{"mode": "current"} (default), {"mode": "at", "at": "<ISO date-time>"}, {"mode": "overlap", "from": "…", "to": "…"} or {"mode": "history"}
hops1 or 2; default 1
predicate1 to 200 characters
entity_ids1 to 19 unique entity UUIDs
documentsa documents filter, as DocumentSearchFilters or a dict; tags must be registered (remember.UnknownTag otherwise)
facts = memory.facts_context(
    "billing migration owner", time={"mode": "history"}
)
billing = memory.facts_context(
    "cutover date", documents={"tags": {"all": ["project:billing-migration"]}}
)
for link in billing.fact_evidence:
    print(link.stance, link.claim_id, link.in_documents_filter)
for fact in facts.facts:
    print(fact.label, fact.validity.valid_from, fact.validity.valid_until)

k controls confirmed results per type (default 50, range 1–100). candidate_k controls internal search depth (1–400, at least k); omitted depth is max(4*k, 60), which is 200 at the default k.

claims_and_sources_context

MemoryClient.claims_and_sources_context(
    query: str,
    *,
    k: int | None = None,
    candidate_k: int | None = None,
    time: Mapping[str, object] | None = None,
    layers: Sequence[str] | None = None,
    documents: DocumentSearchFilters | Mapping[str, object] | None = None,
) -> Envelope

Returns what sources said about query (claims) and the matching source passages (chunks). query is 1 to 8,192 characters. time takes the same values as in facts_context; for documents with declared effective periods it reads only the text in force for that scope (default: now). documents returns only what matching documents say. See Assured operations.

said = memory.claims_and_sources_context("Why was the cutover date moved?")
for claim in said.evidence:
    print(claim.claim_text, claim.asserted_at, claim.document_title)

k controls confirmed results per type (default 50, range 1–100). candidate_k controls internal search depth (1–400, at least k); omitted depth is max(4*k, 60), which is 200 at the default k.

combined_context

MemoryClient.combined_context(
    query: str,
    *,
    k: int | None = None,
    candidate_k: int | None = None,
    time: Mapping[str, object] | None = None,
    layers: Sequence[str] | None = None,
    documents: DocumentSearchFilters | Mapping[str, object] | None = None,
) -> ContextBundleV2

Runs claims_and_sources_context and facts_context together and returns both results in one bundle: bundle.claims_and_sources and bundle.facts. time and documents take the same values as in facts_context and apply to both.

bundle = memory.combined_context("What did John decide about invoicing?")
print(len(bundle.facts.facts), len(bundle.claims_and_sources.evidence))

k controls confirmed results per type (default 50, range 1–100). candidate_k controls internal search depth (1–400, at least k); omitted depth is max(4*k, 60), which is 200 at the default k.

resolve_entity

MemoryClient.resolve_entity(name: str) -> Envelope

Returns the ranked candidate entities for a name. It never picks one silently. name must be at least one character.

people = memory.resolve_entity("Dana")
for candidate in people.entities:
    print(candidate.entity_id, candidate.canonical_name)
 
dana_id = people.entities[0].entity_id   # reused by the examples below

Entities and facts

resolve

MemoryClient.resolve(
    *, name: str, context_entity_ids: tuple[UUID, ...] = ()
) -> Envelope

Resolves a name, using up to 8 already-known entities as context to rank the candidates. More than 8 is refused by the engine.

memory.resolve(name="the migration", context_entity_ids=(dana_id,))

lookup_relations

MemoryClient.lookup_relations(
    *,
    subject_entity_id: UUID | None = None,
    predicate: str | None = None,
    object_entity_id: UUID | None = None,
    valid_at: datetime | None = None,
    limit: int = 50,
    cursor: str | None = None,
) -> Envelope

Returns the relations (facts between two entities) that match the pattern. With valid_at, returns the relations that were valid at that instant; without it, the current ones. limit is 1–200 (default 50). Pass the envelope's next_cursor as cursor until it is None.

memory.lookup_relations(subject_entity_id=dana_id, predicate="leads")

lookup_observations

MemoryClient.lookup_observations(
    *, entity_id: UUID, property_query: str | None = None, k: int = 10,
    limit: int = 50, cursor: str | None = None,
) -> Envelope

Returns the current observations (facts about one entity), optionally narrowed by property_query text. With a property query, k bounds ranked results and truncation.truncated discloses the cap; a cursor is refused. Without a property query, limit (default 50, range 1–200) / cursor pages through next_cursor.

memory.lookup_observations(entity_id=dana_id, property_query="role")

transcript_relation

MemoryClient.transcript_relation(*, relation_id: UUID) -> Envelope

Returns the recorded decisions that shaped one relation (the transcript field of the envelope).

hydrate_relation

MemoryClient.hydrate_relation(*, relation_id: UUID) -> Envelope

Returns one relation with its evidence and the source documents behind it.

relation = next(f for f in facts.facts if f.kind == "relation")
cited = memory.hydrate_relation(relation_id=relation.fact_id)
print([s.title for s in cited.sources])

search_claims

MemoryClient.search_claims(
    *,
    query: str,
    k: int = 10,
    channel: Literal["semantic", "bm25"] = "semantic",
    documents: DocumentSearchFilters | None = None,
    time: ReadTime | None = None,
) -> Envelope

Searches claims by meaning ("semantic") or by keywords ("bm25"). The result is evidence, not facts. The engine accepts k from 1 to 400. documents keeps only claims found in matching document versions (each still cites the passage it was first extracted from), with the same fields as search_documents, tags included; a filtered search is sent as POST /search/claims. A tag that is not registered raises remember.UnknownTag. time reads only text in force for the scope; a search with time is sent as POST too. See Limiting search to certain documents and Reading text as of a date.

from remember import Client, DocumentSearchFilters
 
memory = Client()
hits = memory.search_claims(
    query="Project X",
    channel="bm25",
    documents=DocumentSearchFilters(authors=("[email protected]",)),
)

search_chunks

MemoryClient.search_chunks(
    *,
    query: str,
    k: int = 10,
    channel: Literal["semantic", "bm25"] = "semantic",
    documents: DocumentSearchFilters | None = None,
    time: ReadTime | None = None,
) -> Envelope

Searches source passages. Same arguments and bounds as search_claims; documents keeps passages whose document matches, and time passages of versions in force for the scope.

time is a ReadTime: a dict or model with mode current, at (with at), overlap (with from and to) or history, for example {"mode": "at", "at": "2026-02-01T00:00:00Z"}. Omitted, it is current. A document without declared effective periods reads its served version under every mode.

hits = memory.search_chunks(query="invoice numbering", k=5, channel="bm25")
for chunk in hits.chunks:
    print(chunk.chunk_id, chunk.chunk_text[:80])

adjacent_chunks

MemoryClient.adjacent_chunks(*, chunk_id: UUID | str, window: int = 1) -> Envelope

Returns the passages immediately before and after one chunk in the same document version, in document order. window is 1 or 2.

Raises ValueError when window is outside 1–2 or chunk_id is not a UUID.

around = memory.adjacent_chunks(chunk_id=hits.chunks[0].chunk_id, window=2)

Graph

Details and limits: Graph.

graph_neighborhood

MemoryClient.graph_neighborhood(
    *,
    entity_id: UUID,
    hops: int = 2,
    predicates: tuple[str, ...] = (),
    valid_at: datetime | None = None,
    believed_at: datetime | None = None,
    limit: int = 100,
    cursor: str | None = None,
    include_paths: bool = False,
) -> Envelope

Returns the entities and relations around one entity. The engine accepts hops 1–4, limit 1–500 and at most 100 predicates. Pass the envelope's next_cursor back as cursor to read the next page.

around_dana = memory.graph_neighborhood(entity_id=dana_id, hops=1)
print(len(around_dana.nodes), len(around_dana.edges))

graph_path

MemoryClient.graph_path(
    *,
    from_entity_id: UUID,
    to_entity_id: UUID,
    max_hops: int = 4,
    predicates: tuple[str, ...] = (),
    valid_at: datetime | None = None,
    believed_at: datetime | None = None,
) -> Envelope

Returns the shortest paths between two entities. The engine accepts max_hops 1–6.

graph_citation_path

MemoryClient.graph_citation_path(
    *, from_doc_id: UUID, to_doc_id: UUID, max_hops: int = 6
) -> Envelope

Returns citation paths from one document to another. max_hops 1–6.

SQL and saved queries

SQL queries run over the query space (memory_v1): prepared, read-only views and functions. The engine parses every statement and validates it against the query space before it runs; anything outside it is rejected. See Query space memory_v1 and Explore memory with SQL. Failures carry a code on MemoryApiError.code (for example relation_not_allowed, statement_timeout); the list is in Errors.

query_sql

MemoryClient.query_sql(
    *,
    sql: str,
    parameters: list[object] | tuple[object, ...] = (),
    max_rows: int | None = None,
    layers: Sequence[str] | None = None,
) -> dict[str, object]

Runs one statement with positional parameters ($1, $2, …). Returns the QueryResult/v1 object as a dict. max_rows must be between 0 and 1,000; larger values are refused.

open_query

MemoryClient.open_query(
    sql: str, *, parameters: Sequence[object] = (), max_rows: int | None = None
) -> QueryResultDict

The same call, returning a QueryResultDict with .rows, .columns and .truncated attributes.

res = memory.open_query(
    "SELECT predicate, count(*) AS n FROM facts_current GROUP BY 1 ORDER BY 2 DESC LIMIT $1",
    parameters=[10],
)
for row in res.rows:
    print(row)

explain_sql

MemoryClient.explain_sql(
    *,
    sql: str,
    parameters: list[object] | tuple[object, ...] = (),
    layers: Sequence[str] | None = None,
) -> dict[str, object]

Checks and plans a statement without running it. Returns QueryResult/v1 as a dict.

explain_query

MemoryClient.explain_query(
    sql: str, *, parameters: Sequence[object] = ()
) -> QueryResultDict

explain_sql returning a QueryResultDict.

describe_query_space

MemoryClient.describe_query_space(
    *, pattern: str | None = None, include_examples: bool = False
) -> dict[str, object]

Returns the query space's views, functions, comments and limits. pattern is a shell-style filter over view names.

space = memory.describe_query_space(pattern="facts_*")

search_query_space

MemoryClient.search_query_space(*, query: str, k: int = 10) -> list[dict[str, object]]

Searches the query space's own documentation (never your data). Each hit has kind, name, score, purpose, tags. The engine accepts k 1–25.

list_saved_queries

MemoryClient.list_saved_queries(
    *, namespace: str | None = None, status: str | None = None
) -> list[dict[str, object]]

Lists saved queries. Without status, only active versions are listed.

describe_saved_query

MemoryClient.describe_saved_query(
    *, namespace: str, name: str, version: int | None = None
) -> dict[str, object]

Returns one saved query's SQL, parameters and declared columns. namespace and name must match ^[a-z][a-z0-9_]*$, otherwise ValueError.

run_saved_query

MemoryClient.run_saved_query(
    *,
    namespace: str,
    name: str,
    parameters: list[object] | tuple[object, ...] = (),
    version: int | None = None,
    max_rows: int | None = None,
    layers: Sequence[str] | None = None,
) -> dict[str, object]

Runs one active saved query. Same identifier rule as describe_saved_query. Returns QueryResult/v1 as a dict. See Saved queries.

call_open_query

MemoryClient.call_open_query(*, name: str, arguments: Mapping[str, object]) -> object

Runs one of the seven SQL query tools by its MCP tool name (query_sql, explain_sql, describe_query_space, search_query_space, list_saved_queries, describe_saved_query, run_saved_query) with MCP tool arguments. The remember mcp server uses it. Arguments are checked strictly: unknown keys, wrong types and out-of-range numbers are refused.

Connector methods

connectors(), add_connector(*, connector), pause_connector(*, connector_id) and connector_status(*, connector_id) exist in the SDK, but no deployment serves the /connectors routes today; every call raises MemoryApiError with status_code 404. See What is not built yet.

Errors

RuntimeError
├── MemoryApiError                 every memory call
│   ├── RateLimited                429 from the deployment's admission limits
│   ├── LayerUnavailable           409 layer_unavailable
│   ├── UnknownTag                 unknown_tag
│   └── StoredKeyRefused           the stored key may not go to that address
└── PipelineDeadLettered           wait_for_readiness
Exception
└── ConnectorNotFoundError         exported, not raised today
ValueError
└── CredentialError                remember.credentials (the credential file)

MemoryApiError

Raised by every memory-client method when a request fails.

AttributeMeaning
retryable, request_idOptional typed server diagnostics; they do not authorize automatic replay.
status_codeHTTP status. 0 means the request never got an answer (connection refused, timeout, DNS). 200 means the answer did not match the expected shape.
detailThe error text from the deployment.
codeA machine code, set for SQL and saved-query routes (for example parse_error, quota_exceeded, saved_query_not_found), for a 429 (rate_limited or concurrency_limited), and for the tag refusals unknown_tag, conflict and tag_limit_exceeded; otherwise None.
responseNot set by the SDK (None).

str(error) reads API <status_code>: <detail>.

try:
    memory.query_sql(sql="SELECT * FROM pg_catalog.pg_class")
except remember.MemoryApiError as error:
    print(error.status_code, error.code)   # 422 relation_not_allowed

Status codes and their meaning: Errors and status codes.

RateLimited

Raised when the deployment refuses a request with 429 because a key or the deployment has reached its request-rate or in-flight limit. code is rate_limited or concurrency_limited; retry_after is the Retry-After the deployment sent, in seconds (a float), or None. The client does not retry by itself.

import time
 
try:
    memory.facts_context("Who owns the billing migration?")
except remember.RateLimited as error:
    time.sleep(error.retry_after or 1)

StoredKeyRefused

Raised on the first request when the key came from the credential file and the address came from base_url or REMEMBER_API_URL and is not an address that key may be sent to (Connecting). Pass the key as api_key or in REMEMBER_API_KEY to use it there.

LayerUnavailable

A MemoryApiError (status_code 409, code layer_unavailable) raised when a read needs a processing layer the deployment does not process. layer is "claims" or "facts". Check processing_layers and use a read the deployment serves.

UnknownTag

A MemoryApiError (code unknown_tag) raised when a call names a tag the deployment has not registered. tags is a tuple of every unregistered tag as the call gave it. status_code is 422 for tags in ingest or update_document_tags, and 404 when update_tag or delete_tag cannot find the tag. Nothing was stored or changed. Register the tag with create_tag, or check the spelling with list_tags.

try:
    memory.ingest("notes/billing-sync.md", tags=["project:biling-migration"])
except remember.UnknownTag as error:
    print("not registered:", error.tags)

PipelineDeadLettered

Raised by wait_for_readiness when a stage of a version it waits on is dead_letter: the stage used all its retry attempts and will not finish by waiting.

AttributeMeaning
dead_letteredEvery dead-lettered stage found, as (version_id, stage, status) tuples.
reportThe PipelineReadinessReport that showed them.

str(error) names each version and stage. On a self-hosted deployment the operator can replay the work after fixing the cause. See When a version fails.

CredentialError

remember.credentials.CredentialError (a ValueError) is raised when the credential file cannot be read or written safely: it is a symlink, it is readable by group or others, it is not a version-2 file, or the lock cannot be taken. remember setup --self-hosted replaces the file.

ConnectorNotFoundError

Exported for the connector methods; nothing raises it today.

Models

Field-level detail for results is in Result types. The models below are Pydantic models (frozen) unless noted.

NameWhat it is
EnvelopeThe result of every retrieval call: grain, temporal_scope, entities, facts, evidence, chunks, sources, graph fields, truncation, negative, freshness and more.
ContextBundleV2The result of combined_context: contract ("ContextBundle/v2"), claims_and_sources (an evidence Envelope) and facts (a fact Envelope).
IngestedVersionThe result of ingest: deployment_id, doc_id, version_id (UUIDs), content_hash (str), created (bool), and the settings in force: mime (str), title (str or None), versioning_mode ("snapshot" or "living"), version_key (str or None).
DocumentPageThe result of list_documents: documents (tuple of DocumentSummary) and cursor.
DocumentSummaryOne document: doc_id, title, source_kind, source_uri, first_seen_at, latest (a DocumentVersionSummary), serving, tags (tuple of tag names).
DocumentVersionSummaryversion_id, version_no, status, ingested_at, error.
DocumentDeletionThe result of delete_document: doc_id, deleted_at, claims_retired, relations_closed, observations_closed.
Tag, TagList, DocumentTagsOne registered tag (tag_id, name, description, created_at, updated_at), the result of list_tags (tags), and the result of update_document_tags (doc_id, tags).
ReadinessRequirementsThe capabilities a readiness check must confirm: pipeline, p1, live_graph, p3, all required booleans.
PipelineReadinessReportready, versions (tuple of VersionPipelineReadiness), capabilities (dict of capability name to CapabilityReadiness), document_binding_generation, model_bindings, build_revision.
VersionPipelineReadinessversion_id, ready, stages (tuple of PipelineStageReadiness).
PipelineStageReadinessstage, component_version, status (missing, pending, running, succeeded, failed, dead_letter, skipped), finished_at, defer_reason (why waiting work waits: no_route, admission, budget, scheduled, retry_backoff, or None).
ProcessingLayerString enum: sources, claims, facts.
ProcessingLayerStatesThe result of processing_layers: claims and facts, each enabled, backfilling or disabled.
CapabilityReadinessrequired, ready, checked_at, reason, version, built_at, published_at.
ToolDescriptorOne operation's descriptor: name, description, input_schema, result_schema, result_contract, output_grain, answer_intent, mutates, version, implementation_plan_hash.
QueryResultDictA dict holding a QueryResult/v1 response, with three read-only attributes: rows (list of rows; each row is a list of column values in column order), columns (list of {"name", "type", "nullable"} dicts) and truncated (bool).
ClaimValidPrecisionString enum: how narrow a stated validity window is. unknown, instant, day, month, quarter, year, open.
TemporalMatchString enum: whether a fact confirmed or only possible overlapped the query window.
ReadTimeThe time scope of a text read: CurrentReadTime, AtReadTime, OverlapReadTime or HistoryReadTime (in remember.models), chosen by mode. A dict such as {"mode": "at", "at": "2026-02-01T00:00:00Z"} is accepted wherever a ReadTime is.
EffectivePeriodInput, EffectivePeriodsSet, DeclaredEffectivePeriod, EffectiveTimeClearedDeclaring effective periods and the results of set_effective_periods and clear_effective_time.
EffectiveIntervalOne in-force interval: from_ (sent as from), until, until_declared.
MatchingEdition, ScopePending, ClaimOccurrenceParts of time-scoped results: an edition that matched search_documents, the documents whose edition in force is still processing, and where a claim occurs in a selected version.
ReferenceInput, ReferenceTarget, ReferencesSet, ReferenceGeneration, ReferenceGenerations, ReferenceItemErrorSupplying references and reading their generations.
SectionHistoryRequest, SectionHistoryPage, SectionHistoryRow, SectionHistorySection, SectionAmendmentsection_history.
DocumentReferencesRequest, DocumentReferencesPage, DocumentReference, DocumentReferenceSource, DocumentReferenceTarget, NamedReferenceTarget, ReferenceWindow, DocumentReferencesTooBroaddocument_references.
ConnectorCreate, ConnectorDescriptorConnector configuration models. No deployment serves connectors today. ConnectorCreate refuses a configuration key that looks like a secret (token, password, api_key …) and asks for credential_ref instead.

Note

QueryResultDict.rows is annotated as a list of dicts, but each row arrives as a list of values. Pair it with columns to get names: [dict(zip([c["name"] for c in res.columns], row)) for row in res.rows].

Windows credential files

Automatic credential-file reads are refused on Windows because the SDK cannot prove owner-only access with its current file reader. Supply an explicit API key and engine URL instead; no stored file is read when both are supplied. An argument or environment signed key without a URL also works: it bypasses the unavailable store and discovers its engine through its own issuer.