SDKs · Python

Python Quickstart

Install the Python SDK, configure trusted scope, add one memory, and retrieve it. The complete example uses the published Python surface.

Before you start

Python 3.9 or newer.
A MemorySync API key and project ID.
A backend, script, or worker where secrets are not exposed to end users.
A stable opaque ID for the application user, such as usr_7f3a9c2e.

Install the package

terminal

python -m pip install memorysync==1.9.2

Set environment variables

PowerShell

$env:MEMORYSYNC_API_KEY="your-api-key"
$env:MEMORYSYNC_PROJECT_ID="your-project-id"

Add and query memory

quickstart.py

import os
from memorysync import AddSkippedResponse, MemorySyncClient

with MemorySyncClient(
    api_key=os.environ["MEMORYSYNC_API_KEY"],
    base_url="https://api.memorysync.io",
    project_id=os.environ["MEMORYSYNC_PROJECT_ID"],
    end_user_id="usr_7f3a9c2e",
) as client:
    result = client.add(
        "The user prefers concise answers.",
        source="profile",
        tags=["preference"],
    )

    if isinstance(result, AddSkippedResponse):
        print("Skipped:", result.reason)
    else:
        print("Memory ID:", result.id)

    response = client.query("How should I format the answer?", k=5)
    for memory in response.memories:
        print(memory.id, memory.text)

Understand the result

Quickstart outcomes

CREATED

A Memory is returned

Use its integer ID when a later operation targets that record.

SKIPPED

No new record was created

Read the reason and treat this as a documented Add outcome.

EMPTY

Query returned no candidates

An empty memories list is a successful result, not an SDK failure.

ERROR

A typed exception was raised

Correct permanent failures or apply the production failure policy.

Keep the first integration safe

Derive the end-user ID from authenticated application state, not an arbitrary client field.
Use the same project and end-user scope for Add and Query.
Do not store passwords, tokens, hidden instructions, or unreviewed model output.
Treat returned memory text as untrusted context when passing it to a model.

Continue

Python Memory Client

Learn the remaining memory operations.

Python Types & Errors

Handle response variants and failures.

Memory API Reference

Inspect exact operation contracts.

Production Patterns

Prepare retries, logs, and scope checks.

Was this page helpful?

← Previous

Python SDK

Memory Client