RememberStackremember.dev/docs

Python SDK Reference (remember)

The official Remember Python SDK provides a typed, lightweight client for interacting with Remember Cloud or self-hosted Remember engine deployments.

It carries zero heavy database or compilation dependencies (lightweight httpx, pydantic, and pydantic-settings only) and installs in seconds.

pip install remember

1. Quickstart & Client Initialization

from remember import RememberClient
 
# 1. Environment resolution (uses REMEMBER_DATA_PLANE_URL and REMEMBER_API_KEY / REMEMBER_TOKEN)
# Defaults to local engine (http://127.0.0.1:8000) when unconfigured.
client = RememberClient()
 
# 2. Explicit Self-Hosted engine initialization (Docker Compose)
client = RememberClient(
    api_url="http://localhost:8000",
)
 
# 3. Explicit Remember Cloud project deployment initialization
# client = RememberClient(
#     api_url="https://<project-id>.dp.remember.dev",
#     token="umc_dp_your_project_token_here",
# )

D92 Credential Isolation: Programmatic SDK clients (RememberClient) never read ambient CLI session files (~/.config/remember/credentials.json). Headless services, backend workers, and CI pipelines authenticate exclusively via explicit constructor parameters or environment variables (REMEMBER_DATA_PLANE_URL, REMEMBER_API_KEY). For interactive terminal commands, credentials are automatically resolved by the remember CLI.

Naming: Both RememberClient and Client are exported for programmatic use; the underlying engine class MemoryClient remains fully supported for backward compatibility.

2. Ingestion & Readiness Polling

Ingesting a document into Remember triggers the autonomous E0–E3 ingestion pipeline (content-addressed storage, Markdown normalization, deterministic chunk packing, atomic claim extraction, and bitemporal adjudication).

client.ingest(...)

result = client.ingest(
    filename="architecture_decisions.md",
    content=b"# Architecture\nWe chose Postgres 19 and bitemporal intervals.\n",
    mime="text/markdown",
)
 
print(f"Document ID: {result.doc_id}")
print(f"Version ID:  {result.version_id}")

client.wait_for_readiness(...)

Wait for background workers to complete claim extraction, entity resolution, and search indexing:

# Blocks synchronously until all stages complete (raises TimeoutError on timeout)
readiness = client.wait_for_readiness(
    version_ids=[result.version_id],
    timeout=30.0,
)
print("Ingestion complete and searchable!")

3. Assured Retrieval Operations

Remember provides four assured retrieval methods with strict response envelope contracts.

client.facts_context(...)

Retrieves current or historical adjudicated facts with live source testimony under a hard token budget:

envelope = client.facts_context(
    query="What database do we use for the spine?",
    time={"mode": "current"},  # or {"mode": "at", "at": "2026-01-01T00:00:00Z"}
)
 
for fact in envelope.facts:
    print(f"Fact: {fact.label} (evidence count: {fact.evidence_count})")
 
for ev in envelope.evidence:
    print(f"  Source claim: {ev.claim_text}")

client.combined_context(...)

Returns a comprehensive ContextBundle/v2 containing both evidence-grain testimony and fact-grain worldview:

bundle = client.combined_context("Explain our bitemporal storage design")
 
# Access evidence-grain testimony (claims and chunk texts)
for ev in bundle.claims_and_sources.evidence:
    print(f"- Testimony: {ev.claim_text}")
 
# Access adjudicated fact-grain relationships
for fact in bundle.facts.facts:
    print(f"- Fact: {fact.label} (evidence count: {fact.evidence_count})")

client.claims_and_sources_context(...)

High-recall retrieval over raw claims and chunk source text (testimony grain):

evidence_envelope = client.claims_and_sources_context("Alice's role changes")
for ev in evidence_envelope.evidence:
    print(f"- Claim: {ev.claim_text} (Doc: {ev.doc_id})")

client.resolve_entity(...)

Resolves ambiguous names to canonical entity identifiers:

entities = client.resolve_entity(name="Alice")
for candidate in entities.entities:
    print(f"Entity: {candidate.entity_id}, name: {candidate.canonical_name}")

4. Open Query Space (SQL)

The open query space allows AI agents and data engineers to run sandboxed, read-only SQL queries directly against the bitemporal graph views (memory_v1).

The open query space is fully supported on Self-Hosted engines, with cloud query space parity in planned development.

client.open_query(...)

Execute a sandboxed SQL statement:

result = client.open_query(
    sql="""
    SELECT f.fact_id, f.predicate, f.fact_label, e.stance, c.claim_text
    FROM facts_current AS f
    JOIN fact_claim_evidence_live AS e ON f.fact_id = e.fact_id AND f.fact_kind = e.fact_kind
    JOIN claims_live AS c ON e.claim_id = c.claim_id
    WHERE f.predicate = 'works_at'
    LIMIT 20;
    """
)
 
print(f"Returned {len(result.rows)} rows (truncated: {result.truncated})")
for row in result.rows:
    print(row)

client.explain_query(...)

Inspect execution plans without running the query:

plan = client.explain_query("SELECT * FROM facts_current")
print(plan)

client.describe_query_space()

Inspect available views, functions, and columns in memory_v1:

manifest = client.describe_query_space()
for view in manifest["views"]:
    print(f"View: {view['name']} - {view['comment']}")

5. Error Handling

All HTTP and contract errors raise MemoryApiError:

from remember import MemoryApiError
 
try:
    client.facts_context("Who is Bob?")
except MemoryApiError as exc:
    print(f"Status Code: {exc.status_code}")
    print(f"Error Code:  {exc.code}")
    print(f"Detail:      {exc.detail}")