Python SDK

Overview

The memorysync package on PyPI gives you two clients in one import: MemorySyncClient for synchronous code and AsyncMemorySyncClient for async / await. Both expose the same ten methods over the same REST routes.

What the package exposes

Everything you need is on the top-level package. There is no nested namespace to memorise.

PYTHON

from memorysync import (
    MemorySyncClient,        # blocking client
    AsyncMemorySyncClient,   # async client
    __version__,
)
from memorysync.errors import (
    MemorySyncError, AuthError, NotFoundError,
    ValidationError, RateLimitError, ServerError,
)
from memorysync.types import (
    Memory, AddResult, AddSkippedResponse,
    BulkAddItem, BulkAddItemResult, BulkAddResponse,
    QueryResponse, ComposeResponse,
    Relation, RelationshipType, ExportResponse,
)

Every method on the sync client

Method	Returns	HTTP route
`add(text, *, source, tags, importance, session_id, metadata, end_user_id)`	AddResult	POST /memory/add
`bulk_add(items, *, deduplicate=True)`	BulkAddResponse	POST /memory/bulk-add
`query(query, *, k, filters, session_id, traversal_depth)`	QueryResponse	POST /memory/query
`get(memory_id)`	Memory	GET /memory/{id}
`update(memory_id, *, tags, importance, metadata, source, event_type)`	Memory	PATCH /memory/{id}
`forget(memory_ids, *, reason)`	list[int]	DELETE /memory/forget
`summarize(memory_ids, *, lossless=False)`	Memory	POST /memory/summarize
`compose(prompt_template, *, recall_k, max_tokens)`	ComposeResponse	POST /memory/compose
`export_all()`	ExportResponse	GET /memory/export
`create_relation(from_memory_id, *, to_memory_id, relationship_type, confidence, metadata)`	Relation	POST /memory/{id}/relations

Async mirror of the same surface

AsyncMemorySyncClient has every method above, with identical signatures, except the cleanup hook is aclose() instead of close().

Don\u2019t mix the two

Pick one client per process. Sharing connections between a sync and an async client is unsupported.

A minimal program, end to end

PYTHON

import os
from memorysync import MemorySyncClient
from memorysync.errors import RateLimitError, AuthError

client = MemorySyncClient(
    api_key=os.environ["MEMORYSYNC_API_KEY"],
    base_url="https://api.memorysync.io",
    end_user_id="user_123",   # required for API-key auth
)

try:
    created = client.add(text="The launch is on Friday.", tags=["plan"])
    hits = client.query("when is launch", k=3)
    for m in hits.memories:
        print(m.id, m.text, m.score)
except AuthError:
    print("API key invalid or revoked")
except RateLimitError as e:
    print(f"Slow down for {e.retry_after_seconds}s")
finally:
    client.close()

Typed responses, never raw dicts

Every method returns a typed object — a Memory dataclass, a QueryResponse, a BulkAddResponse. Field names mirror the JSON exactly so you can move between the cURL guide and Python code without guessing. add can return either a Memory or an AddSkippedResponse; check the status attribute to branch.

Lifecycle hooks

Both clients are context managers. Use with for the sync client and async with for the async client when you want deterministic cleanup; the explicit close methods are there for cases where a with block doesn’t fit (long-lived workers, ASGI startup/shutdown hooks).

PYTHON

# Sync — context manager handles close() automatically
with MemorySyncClient(api_key=..., base_url=..., end_user_id="user_123") as ms:
    ms.add("Saved a decision.")

# Async — use async with + aclose()
async with AsyncMemorySyncClient(api_key=..., base_url=...) as ms:
    await ms.add("Saved a decision.")

client.close() on the sync client. Safe to call multiple times.
await client.aclose() on the async client. Safe to call multiple times.
Use with / async with whenever you can — you can’t forget to clean up.

Read these next

Install & Auth — pin a version and configure the constructor.
Add & Query — the two methods you will use most.
Async Usage — running concurrent calls.
Error Handling — the six error classes and how to react to each.

← Previous

Language-Agnostic Patterns

Install & Auth