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 rememberThe 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:
| Name | Kind | Section |
|---|---|---|
Client | class | Client |
RememberClient | alias of Client | Client |
MemoryClient | class | MemoryClient |
resolve_connection | function | Connecting |
MemoryApiError | exception | Errors |
RateLimited | exception | Errors |
StoredKeyRefused | exception | Errors |
PipelineDeadLettered | exception | Errors |
LayerUnavailable | exception | Errors |
UnknownTag | exception | Errors |
ConnectorNotFoundError | exception | Errors |
CapabilityReadiness | model | Models |
ClaimOccurrence | model | Models |
ClaimValidPrecision | enum | Models |
ConnectorCreate | model | Models |
ConnectorDescriptor | model | Models |
ContextBundleV2 | model | Models |
DeclaredEffectivePeriod | model | Models |
DeploymentBuildInfo | model | deployment_build_info |
DocumentDeletion | model | Models |
DocumentPage | model | Models |
DocumentReference | model | Models |
DocumentReferenceSource | model | Models |
DocumentReferencesPage | model | Models |
DocumentReferencesRequest | model | Models |
DocumentReferencesTooBroad | model | Models |
DocumentReferenceTarget | model | Models |
DocumentSearchFilters | model | Models |
DocumentSearchPage | model | Models |
DocumentSearchRequest | model | Models |
DocumentSearchResult | model | Models |
DocumentSummary | model | Models |
DocumentTagFilter | model | Models |
DocumentTags | model | Models |
DocumentVersionSummary | model | Models |
EffectiveInterval | model | Models |
EffectivePeriodInput | model | Models |
EffectivePeriodsSet | model | Models |
EffectiveTimeCleared | model | Models |
Envelope | model | Models |
IngestedVersion | model | Models |
MatchingEdition | model | Models |
NamedReferenceTarget | model | Models |
NegativeKind | enum | Result types |
PipelineReadinessReport | model | Models |
PipelineStageReadiness | model | Models |
ProcessingLayer | enum | Models |
ProcessingLayerStates | model | Models |
QueryResultDict | dict subclass | Models |
ReadinessRequirements | model | Models |
ReadTime | type alias | Models |
ReferenceGeneration | model | Models |
ReferenceGenerations | model | Models |
ReferenceInput | model | Models |
ReferenceItemError | model | Models |
ReferencesSet | model | Models |
ReferenceTarget | model | Models |
ReferenceWindow | model | Models |
ScopePending | model | Models |
SectionAmendment | model | Models |
SectionHistoryPage | model | Models |
SectionHistoryRequest | model | Models |
SectionHistoryRow | model | Models |
SectionHistorySection | model | Models |
Tag | model | Models |
TagList | model | Models |
TemporalMatch | enum | Models |
ToolDescriptor | model | Models |
VersionPipelineReadiness | model | Models |
__version__ | string | The 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 to | Use |
|---|---|
| Store and retrieve memory (the usual case) | Client (same as RememberClient) |
The same, without the file-path ingest shortcut | MemoryClient |
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:
| Setting | 1. Argument | 2. Environment | 3. Credential file | 4. Otherwise |
|---|---|---|---|---|
| Key | api_key | REMEMBER_API_KEY | key | no key |
| Address | base_url | REMEMBER_API_URL | api_url | http://127.0.0.1:8000 |
| Project | project | REMEMBER_PROJECT | default_project | none |
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.ClientThe 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.
| Parameter | Meaning |
|---|---|
api_key | The API key. A bare key or a full Bearer … value. |
base_url | The deployment address. |
project | Which project to use, by id or name, when the key covers several. |
timeout | Seconds per HTTP request. Default 300. |
client | An 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. |
transport | An 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:
ValueErrorwhenclientis combined with another parameter.ValueErrorwhen the key is empty, is the bare wordBearer, or contains a line break.remember.credentials.CredentialErrorwhen 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,
) -> IngestedVersionReads 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.MemoryClientThe 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
| Method | HTTP route | Returns |
|---|---|---|
ingest | POST /ingest | IngestedVersion |
pipeline_readiness | POST /readiness | PipelineReadinessReport |
wait_for_readiness | POST /readiness, repeated | PipelineReadinessReport |
deployment_build_info | GET /deployment | DeploymentBuildInfo |
processing_layers | GET /processing-layers | ProcessingLayerStates |
list_documents | GET /documents | DocumentPage |
search_documents | POST /documents/search | DocumentSearchPage |
delete_document | DELETE /documents/{doc_id} | DocumentDeletion |
list_tags | GET /tags | TagList |
create_tag | POST /tags | Tag |
update_tag | PATCH /tags/{tag_id} | Tag |
delete_tag | DELETE /tags/{tag_id} | Tag |
update_document_tags | POST /documents/{doc_id}/tags | DocumentTags |
set_effective_periods | PUT /documents/{doc_id}/versions/{version_id}/effective-periods | EffectivePeriodsSet |
clear_effective_time | DELETE /documents/{doc_id}/effective-periods | EffectiveTimeCleared |
set_references | PUT /documents/{doc_id}/versions/{version_id}/references | ReferencesSet |
reference_generations | GET /documents/{doc_id}/versions/{version_id}/references | ReferenceGenerations |
section_history | GET /documents/{doc_id}/sections/{section_key}/history | SectionHistoryPage |
document_references | POST /documents/references | DocumentReferencesPage |
list_operations | GET /operations | tuple[ToolDescriptor, ...] |
run_operation | POST /operations/{name} | Envelope or ContextBundleV2 |
facts_context | POST /operations/facts_context | Envelope |
claims_and_sources_context | POST /operations/claims_and_sources_context | Envelope |
combined_context | POST /operations/combined_context | ContextBundleV2 |
resolve_entity | POST /operations/resolve_entity | Envelope |
resolve | GET /resolve | Envelope |
lookup_relations | GET /lookup/relations | Envelope |
lookup_observations | GET /lookup/observations | Envelope |
transcript_relation | GET /transcript/relation/{id} | Envelope |
hydrate_relation | GET /hydrate/relation/{id} | Envelope |
search_claims | GET /search/claims | Envelope |
search_chunks | GET /search/chunks | Envelope |
adjacent_chunks | GET /chunks/{id}/adjacent | Envelope |
graph_neighborhood | POST /graph/neighborhood | Envelope |
graph_path | POST /graph/path | Envelope |
graph_citation_path | POST /graph/citation-path | Envelope |
query_sql | POST /query/sql | dict |
open_query | POST /query/sql | QueryResultDict |
explain_sql | POST /query/sql/explain | dict |
explain_query | POST /query/sql/explain | QueryResultDict |
describe_query_space | GET /query/space | dict |
search_query_space | GET /query/space/search | list[dict] |
list_saved_queries | GET /query/saved | list[dict] |
describe_saved_query | GET /query/saved/{namespace}/{name} | dict |
run_saved_query | POST /query/saved/{namespace}/{name}/run | dict |
call_open_query | one of the /query/* routes | object |
| 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,
) -> IngestedVersionUploads 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.
| Parameter | Meaning |
|---|---|
source | A Path or str file path (read from disk), or bytes. |
content | Raw 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. |
filename | Required for bytes. Defaults to the file's name for a path. |
mime | Media 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. |
title | A human title for the document. |
source_kind, source_ref | The 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_at | When 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_ref | The source system's own revision label. Requires source_kind/source_ref. |
source_path | Where 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_key | Your 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_from | Start (included) of the period this version's text is in force. Timezone-aware UTC. Requires source_kind/source_ref and versioning_mode="snapshot". |
effective_until | End (excluded) of that period, later than effective_from. Timezone-aware UTC. Omitted: the period lasts until the next declared start. |
tags | Registered 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_kindandsource_refis given; source_modified_at,source_version_ref,versioning_mode="living",version_key,effective_fromoreffective_untilis given withoutsource_kind/source_ref;source_modified_at,effective_fromoreffective_untilis naive or not UTC;effective_untilis given withouteffective_from, or is not later than it, or a period is given withversioning_mode="living";- neither
sourcenorcontentis given; - bytes are given without
filename; tagsis 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
) -> PipelineReadinessReportAsks, 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,
) -> PipelineReadinessReportCalls 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:
PipelineDeadLetteredwhen any stage of any listed version isdead_letter;TimeoutErrorwhentimeoutseconds pass first;ValueErrorwhen 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() -> DeploymentBuildInfoReturns 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() -> ProcessingLayerStatesReturns 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,
) -> DocumentPageReturns 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_cursorsearch_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,
) -> DocumentSearchPageFinds 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) -> DocumentDeletionRemoves 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:
raiseTags
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) -> TagListReturns 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) -> TagRegisters 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,
) -> TagRenames 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) -> TagDeletes 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,
) -> DocumentTagsChanges 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],
) -> EffectivePeriodsSetReplaces 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) -> EffectiveTimeClearedWithdraws 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],
) -> ReferencesSetReplaces 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
) -> ReferenceGenerationsReturns 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,
) -> SectionHistoryPageFollows 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,
) -> DocumentReferencesPageLists 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 | ContextBundleV2layers 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,
) -> EnvelopeReturns the facts the memory holds true that match query, with their
evidence.
| Argument | Constraint (checked by the engine) |
|---|---|
query | 1 to 8,192 characters |
time | {"mode": "current"} (default), {"mode": "at", "at": "<ISO date-time>"}, {"mode": "overlap", "from": "…", "to": "…"} or {"mode": "history"} |
hops | 1 or 2; default 1 |
predicate | 1 to 200 characters |
entity_ids | 1 to 19 unique entity UUIDs |
documents | a 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,
) -> EnvelopeReturns 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,
) -> ContextBundleV2Runs 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) -> EnvelopeReturns 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 belowEntities and facts
resolve
MemoryClient.resolve(
*, name: str, context_entity_ids: tuple[UUID, ...] = ()
) -> EnvelopeResolves 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,
) -> EnvelopeReturns 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,
) -> EnvelopeReturns 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) -> EnvelopeReturns the recorded decisions that shaped one relation (the transcript
field of the envelope).
hydrate_relation
MemoryClient.hydrate_relation(*, relation_id: UUID) -> EnvelopeReturns 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
search_claims
MemoryClient.search_claims(
*,
query: str,
k: int = 10,
channel: Literal["semantic", "bm25"] = "semantic",
documents: DocumentSearchFilters | None = None,
time: ReadTime | None = None,
) -> EnvelopeSearches 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,
) -> EnvelopeSearches 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) -> EnvelopeReturns 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,
) -> EnvelopeReturns 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,
) -> EnvelopeReturns 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
) -> EnvelopeReturns 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
) -> QueryResultDictThe 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] = ()
) -> QueryResultDictexplain_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]) -> objectRuns 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.
| Attribute | Meaning |
|---|---|
retryable, request_id | Optional typed server diagnostics; they do not authorize automatic replay. |
status_code | HTTP status. 0 means the request never got an answer (connection refused, timeout, DNS). 200 means the answer did not match the expected shape. |
detail | The error text from the deployment. |
code | A 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. |
response | Not 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_allowedStatus 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.
| Attribute | Meaning |
|---|---|
dead_lettered | Every dead-lettered stage found, as (version_id, stage, status) tuples. |
report | The 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.
| Name | What it is |
|---|---|
Envelope | The result of every retrieval call: grain, temporal_scope, entities, facts, evidence, chunks, sources, graph fields, truncation, negative, freshness and more. |
ContextBundleV2 | The result of combined_context: contract ("ContextBundle/v2"), claims_and_sources (an evidence Envelope) and facts (a fact Envelope). |
IngestedVersion | The 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). |
DocumentPage | The result of list_documents: documents (tuple of DocumentSummary) and cursor. |
DocumentSummary | One document: doc_id, title, source_kind, source_uri, first_seen_at, latest (a DocumentVersionSummary), serving, tags (tuple of tag names). |
DocumentVersionSummary | version_id, version_no, status, ingested_at, error. |
DocumentDeletion | The result of delete_document: doc_id, deleted_at, claims_retired, relations_closed, observations_closed. |
Tag, TagList, DocumentTags | One 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). |
ReadinessRequirements | The capabilities a readiness check must confirm: pipeline, p1, live_graph, p3, all required booleans. |
PipelineReadinessReport | ready, versions (tuple of VersionPipelineReadiness), capabilities (dict of capability name to CapabilityReadiness), document_binding_generation, model_bindings, build_revision. |
VersionPipelineReadiness | version_id, ready, stages (tuple of PipelineStageReadiness). |
PipelineStageReadiness | stage, 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). |
ProcessingLayer | String enum: sources, claims, facts. |
ProcessingLayerStates | The result of processing_layers: claims and facts, each enabled, backfilling or disabled. |
CapabilityReadiness | required, ready, checked_at, reason, version, built_at, published_at. |
ToolDescriptor | One operation's descriptor: name, description, input_schema, result_schema, result_contract, output_grain, answer_intent, mutates, version, implementation_plan_hash. |
QueryResultDict | A 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). |
ClaimValidPrecision | String enum: how narrow a stated validity window is. unknown, instant, day, month, quarter, year, open. |
TemporalMatch | String enum: whether a fact confirmed or only possible overlapped the query window. |
ReadTime | The 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, EffectiveTimeCleared | Declaring effective periods and the results of set_effective_periods and clear_effective_time. |
EffectiveInterval | One in-force interval: from_ (sent as from), until, until_declared. |
MatchingEdition, ScopePending, ClaimOccurrence | Parts 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, ReferenceItemError | Supplying references and reading their generations. |
SectionHistoryRequest, SectionHistoryPage, SectionHistoryRow, SectionHistorySection, SectionAmendment | section_history. |
DocumentReferencesRequest, DocumentReferencesPage, DocumentReference, DocumentReferenceSource, DocumentReferenceTarget, NamedReferenceTarget, ReferenceWindow, DocumentReferencesTooBroad | document_references. |
ConnectorCreate, ConnectorDescriptor | Connector 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.