Metadata-Version: 2.4
Name: totalrecall-sdk
Version: 0.1.3
Summary: Official Python SDK for TotalRecall, the memory operating system for AI agents.
License: MIT
Keywords: memory,ai,agents,vector,cockroachdb
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# TotalRecall Python SDK

The official Python client for the [TotalRecall](https://github.com/) REST API.
Standard-library only — no third-party dependencies.

```python
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.
