Skip to main content

Syntarus Python SDK

The official Python client for the project-scoped Syntarus memory API.

Install

pip install syntarus

The smallest useful integration

The common path is three calls: remember a turn, resolve it, and inspect the evidence behind the result. Ingestion is asynchronous by default; use wait=True when the next read must see the new turn.

from syntarus import MemoryClient

with MemoryClient("sk_mem_...") as memory:
    memory.remember("The customer prefers email.", user_id="customer_123", wait=True)
    context = memory.resolve("preferred contact channel", user_id="customer_123")
    evidence = memory.inspect_provenance("preferred contact channel", user_id="customer_123")

resolve keeps the ranked raw results for citations and returns a labeled resolution.context state card for answer generation. Current claims appear under CURRENT STATE; older claims remain available under HISTORICAL EVIDENCE instead of being silently discarded. search remains available when an application explicitly needs the raw retrieval contract.

For LangChain/LangGraph applications:

pip install "syntarus[langchain]"
from syntarus.adapters.langchain import SyntarusMemory

memory = SyntarusMemory(user_id="customer_123", api_key="sk_mem_...")
context = memory.load_memory_variables({"input": "What channel should we use?"})
memory.save_context({"input": "Use email."}, {"output": "Understood."})
memory.close()

The adapter returns memory under syntarus_memory by default. If your prompt uses {history} or {chat_history}, match that variable explicitly:

memory = SyntarusMemory(
    user_id="customer_123",
    api_key="sk_mem_...",
    memory_key="history",
)

LangGraph can use make_recall_node(memory) and make_remember_node(memory) from syntarus.adapters.langgraph; these helpers return ordinary async graph nodes and do not require LangChain or LangGraph at runtime.

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. capture_contract accepts "user_profile_v1" (default, facts about the user) or "agent_records_v1" (structured records about third parties; keeps named parties, dates and changes as written). Any other value raises ValueError before a request is sent. metadata={"trust": "untrusted"} marks a claim made by someone other than the account owner: it is stored and searchable but never marks an existing fact as outdated. "trusted" is the default; any other value raises ValueError.

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.

For imported support transcripts or other authoritative source records, use native hybrid ingestion. One request first stores every role-marked message as lossless evidence, then derives facts, graph edges, and configured canonical state with lineage back to that evidence:

accepted = memory.add(
    user_id="customer_123",
    run_id="ticket_456",
    ingestion_mode="hybrid",
    source_id="ticket-456",
    source_version="1",
    event_time="2026-06-14T10:00:00Z",
    messages=[
        {"role": "user", "content": "Please move us off Scale."},
        {"role": "assistant", "content": "Business is active at $450 plus $50 SSO."},
    ],
)

Use resolve() for answer context. search() intentionally retains raw and historical evidence for audit and debugging.

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.

Deterministic action-policy check

Before a consequential external action, ask Continuum to check direct user-stated memory constraints immediately before execution:

check = memory.check_action_policy(
    user_id="customer_123",
    action_type="food_order",
    action_description="Order Thai satay for David",
    arguments={"item": "Thai satay", "diner": "David"},
)
if check["blocked"] or not check["memory_policy_clear"]:
    raise RuntimeError(f"Stop action: {check['reason_codes']}")
# Run your own authorization, ingredient verification, and approval checks too.
execute_order()

The async client provides await memory.check_action_policy(...). Treat request errors, timeouts, blocked results, and inconclusive results as stop signals. A clear memory-policy result is not application authorization: the endpoint never executes the action and always returns execution_authorized: false. Apply your own ACLs, transaction limits, and human-confirmation requirements.

For a single fail-closed integration point, pass the side effect to execute_guarded. It calls /actions/authorize immediately before invoking your callable and raises ActionExecutionBlocked for blocked, stale/review, untrusted, inconclusive, unavailable, unauthorized, or unconfirmed actions:

from syntarus import ActionExecutionBlocked

try:
    result = memory.execute_guarded(
        user_id="customer_123",
        action_type="send_email",
        action_description="Send the approved support reply",
        executor=lambda: mailer.send(...),
        application_authorized=acl.allows("send_email"),
        confirmation_received=human_confirmed,
    )
except ActionExecutionBlocked:
    # Do not retry the side effect; request a fresh policy/confirmation.
    result = {"status": "stopped"}

Current-state labels are conservative: `current` is backed by an explicitly
configured single-valued project slot; `historical` is superseded evidence;
`unversioned` means Continuum has no proof either way. Historical evidence is
kept for past-tense retrieval.

## Webhooks

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

  • AuthenticationError
  • PermissionDenied
  • RateLimitError (retry_after is available when the API sends it)
  • APIConnectionError
  • APITimeoutError
  • EventFailedError (event contains the terminal event record)

Syntarus resources

Metadata

Release files for syntarus 0.4.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for syntarus 0.4.1
File Size Uploaded Provenance Actions
syntarus-0.4.1.tar.gz 28.2 kB With provenance Details for syntarus-0.4.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for syntarus 0.4.1
File Interpreter ABI Platform Actions
syntarus-0.4.1-py3-none-any.whl Python 3 none any Details for syntarus-0.4.1-py3-none-any.whl

Total release size: 50.8 kB

Release files / syntarus-0.4.1.tar.gz

Download URL syntarus-0.4.1.tar.gz
Size 28.2 kB
Tags Source
SHA-256 checksum
How to use checksums
b5e46aceceef4a9801cfc1fa4a867c6270f47ebbb73e48e8b34c6c09b8781e66
BLAKE2b-256 checksum
How to use checksums
39e46e7b1a95376292318f6df4d4f143bd4f54e1637fb6953dc7e0d99c94f234
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 14, 2026.

Transparency log

Release files / syntarus-0.4.1-py3-none-any.whl

Download URL syntarus-0.4.1-py3-none-any.whl
Size 22.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
bce9c72c3f8be178ca69c2d227aa4d980b12e967d60e31698d0d633eda557194
BLAKE2b-256 checksum
How to use checksums
57b8c12f150831643ce336174212dd62ea2e37e6f31cf0a534343ad39ab0778d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 14, 2026.

Transparency log

Security for syntarus 0.4.1

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.

Select from 2 files

Attestation for syntarus-0.4.1.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 Nov 14, 2026.

Transparency log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page