Syntarus Python SDK
The official Python client for the project-scoped Syntarus memory API.
Install
pip install syntarus
Continuum CLI
The package also installs the syntarus command for local development,
automation, and coding agents. It reads a project key only from
SYNTARUS_API_KEY (or a one-off --api-key flag); it never saves secrets to
the local profile.
export SYNTARUS_API_KEY="sk_mem_..."
syntarus doctor
syntarus memory add "The customer prefers vegetarian food." --user customer_123 --wait
syntarus memory search "food preference" --user customer_123
syntarus graph show --user customer_123 --json
syntarus event get evt_... --json
Use syntarus config set-endpoint https://... only for a self-hosted or test
endpoint. syntarus --help lists every command. Add --json to receive a
stable { "ok", "data" } response suitable for agents and CI.
Python 3.10 or newer is required. Keep project API keys in a server-side secret manager; never ship them in browser or mobile applications.
Add and search memory
from syntarus import MemoryClient
with MemoryClient(api_key="sk_mem_...") as memory:
accepted = memory.add(
user_id="customer_123",
agent_id="support_agent",
run_id="ticket_456",
# Anchor relative dates such as "next Friday" to the source event.
event_time="2023-05-07T12:00:00Z",
messages=[
{"role": "user", "content": "I prefer vegetarian food."},
{"role": "assistant", "content": "I will remember that."},
],
metadata={"channel": "voice"},
idempotency_key="call-456-final",
)
memory.wait_for_event(accepted["event_id"])
result = memory.search(
"What food does the customer prefer?",
user_id="customer_123",
agent_id="support_agent",
)
print(result["context"])
agent_id creates an isolated memory namespace. Omit it for a user profile
shared by every agent in the project. run_id groups the conversation history
used during ingestion. metadata is event metadata and is returned by event
status and webhook payloads; it is not currently a memory-search filter.
event_time is optional, but use it for replayed or delayed conversations so
relative dates are resolved against when the interaction occurred rather than
when Syntarus processes it. It accepts an ISO-8601 string or a Python
datetime.
Bounded bulk import
Bulk imports are source-identified and run on a lower-priority queue. Estimate
first, then explicitly start the manifest; the same (source_id, source_version) cannot be accepted twice in a project.
records = [{
"source_id": "ticket-123",
"source_version": "2026-09-09",
"user_id": "customer_123",
"messages": [{"role": "user", "content": "I prefer email."}],
}]
estimate = memory.bulk_estimate(records)
manifest = memory.bulk_start(records)
memory.bulk_pause(manifest["manifest"]["id"])
memory.bulk_resume(manifest["manifest"]["id"])
status = memory.bulk_status(manifest["manifest"]["id"])
errors = memory.bulk_errors(manifest["manifest"]["id"])
Each record keeps its original turn order and event timestamp. Failed records are exported separately; cancelling a manifest does not erase its audit-safe status.
Async client
from syntarus import AsyncMemoryClient
async with AsyncMemoryClient(api_key="sk_mem_...") as memory:
accepted = await memory.add(
user_id="customer_123",
messages=[{"role": "user", "content": "Call me after 5 PM."}],
)
await memory.wait_for_event(accepted["event_id"])
Production transport behavior
Clients reuse an HTTP connection pool, send a correlation header on every request, and retry up to two times by default for temporary network errors and retryable HTTP responses. Reads are safe to replay. Memory writes and deletion jobs are also safe to retry because the SDK always sends an idempotency key. Other state-changing calls are deliberately not retried automatically.
Tune this per client, or make a short-lived override for a special operation:
from syntarus import MemoryClient, APIStatusError, RateLimitError
with MemoryClient("sk_mem_...", timeout=30.0, max_retries=3) as memory:
try:
result = memory.search("current preference", user_id="customer_123")
except RateLimitError as error:
# Respect an API-supplied delay when present.
print(error.retry_after, error.request_id)
except APIStatusError as error:
print(error.status_code, error.request_id)
# The new client must be closed if it is used.
with memory.with_options(timeout=5.0, max_retries=0) as fast_fail:
fast_fail.search("health probe", user_id="customer_123")
APIStatusError exposes status_code, request_id, and a parsed response
body. It never contains your API key. The SDK does not retry non-idempotent
state transitions such as webhook creation or bulk pause/resume/cancel.
For a large import, wait on the manifest rather than writing a polling loop:
manifest = memory.bulk_start(records)
result = memory.wait_for_manifest(manifest["manifest"]["id"], timeout=3600)
Lifecycle operations
memory.export(user_id="customer_123", agent_id="support_agent")
memory.delete("memory-uuid")
memory.delete_user(user_id="customer_123", agent_id="support_agent")
Deleting a user without agent_id deletes only the shared user namespace.
Delete each agent namespace separately when an application uses agent-scoped
memory.
Enterprise isolation and governance
Use a project key with tokens:write to mint a short-lived credential for one
end user and, optionally, one agent. Subject tokens can only read or write
their bound namespace; they cannot export, delete, manage keys, or read audit
logs.
issued = memory.create_subject_token(
user_id="customer_123",
agent_id="support_agent",
scopes=["memories:read", "memories:write"],
ttl_seconds=900,
)
with MemoryClient(api_key=issued["token"]) as delegated:
delegated.search("What does this customer prefer?", user_id="customer_123")
Verified deletion is a durable cross-store job. Poll it with the normal event method to receive the per-store completion receipt:
deletion = memory.request_user_deletion(
user_id="customer_123",
agent_id="support_agent",
idempotency_key="erase-customer-123-support",
)
receipt = memory.wait_for_event(deletion["event_id"])
print(receipt["result"]["stores"])
audit = memory.audit_events(user_id="customer_123", limit=50)
The project owner must enable delegated tokens in the developer console first. Audit records intentionally exclude memory text and secret values.
Webhooks
created = memory.create_webhook("https://example.com/syntarus/events")
signing_secret = created["signing_secret"] # returned once
memory.list_webhooks()
memory.webhook_deliveries(webhook_id=created["webhook"]["id"])
memory.delete_webhook(created["webhook"]["id"])
Deliveries include X-Syntarus-Timestamp, X-Syntarus-Delivery, and
X-Syntarus-Signature-256. Verify the signature as HMAC-SHA256 over
<timestamp>.<raw_request_body> and reject timestamps outside a five-minute
window. A non-2xx response is retried durably and eventually becomes a
dead-letter delivery visible through webhook_deliveries.
Errors
The SDK raises typed exceptions derived from SyntarusError:
AuthenticationErrorPermissionDeniedRateLimitError(retry_afteris available when the API sends it)APIConnectionErrorAPITimeoutErrorEventFailedError(eventcontains the terminal event record)
Syntarus resources
Metadata
Release files for syntarus 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| syntarus-0.3.0.tar.gz | 18.3 kB | With provenance | Details for syntarus-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| syntarus-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for syntarus-0.3.0-py3-none-any.whl |
Total release size: 33.2 kB
Release files / syntarus-0.3.0.tar.gz
| Download URL | syntarus-0.3.0.tar.gz |
|---|---|
| Size | 18.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6162653c2bc39d7820d1de7704b9d1a673a8eaaf22a16d938705482422f28bf7
|
|
BLAKE2b-256 checksum How to use checksums |
987ae60966fa67a6c8fe7bde2723510e533ed3e391af0d5590fbe7ff5b083ec8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 9, 2026.
Transparency logRelease files / syntarus-0.3.0-py3-none-any.whl
| Download URL | syntarus-0.3.0-py3-none-any.whl |
|---|---|
| Size | 14.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
22d449fa34b49e285ec03efe50abbcc69a30704e94c7a19ce9d58a660c97fd03
|
|
BLAKE2b-256 checksum How to use checksums |
d032b5844b28fd21b5510b6505cd21fc74bfa013650d603a5957d44a556a26f6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 9, 2026.
Transparency logSecurity for syntarus 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for syntarus-0.3.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 9, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.