TotalRecall Python SDK

The official Python client for the TotalRecall REST API. Standard-library only — no third-party dependencies.

from totalrecall import TotalRecall

# base_url defaults to hosted TotalRecall Cloud; pass it to override (e.g. local dev)
tr = TotalRecall(api_key="tr_demo_...")

# 1. Store a memory
# importance/confidence are OPTIONAL: omit them and the LLM ranks the memory
# in the background (store() returns immediately). Provide them to override —
# your values are never overwritten.
tr.store({
    "statement": "The stack uses CockroachDB.",
    "memoryType": "semantic",
    "scopeType": "project",
    "entities": [{"name": "CockroachDB", "type": "technology"}],
    "sensitivity": "normal",
    "requiresConfirmation": False,
})
tr.store({"statement": "The launch deadline is Friday.", "importance": 0.9, "confidence": 0.95})

# 2. Retrieve / search
tr.get_memory("<memory-id>")
tr.list_memories(type="semantic", limit=20)
# Filter by provenance source (connector memories carry their connector kind)
tr.list_memories(source="github")
tr.search("what database do we use", limit=5)
tr.search("launch date", filters={"sourceTypes": ["github", "slack"]})

# 3. Update / delete
tr.update_memory("<memory-id>", {"importance": 0.9})
tr.set_status("<memory-id>", "deleted")  # soft delete (reversible)

# 4. Sessions
session = tr.create_session(title="My session")
tr.close_session(session["sessionId"])
tr.get_messages(session["sessionId"])

# 5. Historical (as-of) memory
tr.as_of("2026-07-20")

# 6. Attribution / provenance
tr.provenance("<memory-id>")

# 7. Memory intelligence
tr.summarize("<memory-id>")
tr.cluster()
tr.list_clusters()

# 8. External AI agent: run the sandbox agent
tr.run_agent("<agent-id>", "research the best deployment option")

Authentication: pass api_key (Bearer) or cookie (session cookie). Demo mode (no key) works against a locally running server with TR_AUTH_MODE unset.