memorysync

Official Python client for the MemorySync API. Sync and async, no surprises.

pip install memorysync

Quick start

from memorysync import MemorySyncClient

ms = MemorySyncClient(
    api_key="...",
    base_url="https://api.memorysync.io",
    project_id="proj_xxxxxxxxxxxxxxxx",   # optional
    end_user_id="user_42",                 # optional
)

ms.add("User prefers dark mode.")

result = ms.query("ui preferences", k=5)
for m in result.memories:
    print(m.id, m.text)

Async usage

import asyncio
from memorysync import AsyncMemorySyncClient

async def main():
    async with AsyncMemorySyncClient(api_key="...", base_url="...") as ms:
        result = await ms.query("ui preferences", k=5)
        print(result.memories)

asyncio.run(main())

Use MemorySyncClient as a context manager when you want deterministic connection cleanup:

with MemorySyncClient(api_key="...", base_url="...") as ms:
    ms.add("...")

Configuration

end_user_id can also be passed per-call on add() to override the client default.

Methods

Every method maps 1:1 to a real HTTP route. The two clients share the same surface; only the call style differs (sync vs await).

add returns one of two shapes

add() runs through MemorySync's extraction pipeline, so input that carries no high-value content is intentionally skipped. Branch on the type of the result:

from memorysync import AddSkippedResponse, Memory

result = ms.add("User prefers dark mode.")
if isinstance(result, AddSkippedResponse):
    print("skipped:", result.reason)
else:
    assert isinstance(result, Memory)
    print(result.id, result.text)

Control-plane client

Dashboard and administrative routes use bearer authentication, not the memory client's API key. Tokens are never persisted or refreshed automatically. Responses are typed dictionaries with snake_case keys, including routes whose wire response uses camelCase.

import os
from memorysync import ControlPlaneClient

with ControlPlaneClient(
    "https://api.memorysync.io",
    access_token=os.environ["MEMORYSYNC_ACCESS_TOKEN"],
    project_id="project_abc123",  # optional X-Project-ID default
) as control:
    members = control.list_team_members()
    hooks = control.list_webhooks()

# Login is the only operation that does not require a configured token.
with ControlPlaneClient("https://api.memorysync.io") as control:
    login = control.login("developer@example.com", os.environ["MEMORYSYNC_PASSWORD"])

AsyncControlPlaneClient exposes the same methods with await and aclose(). Both clients accept base_url, optional access_token, optional project_id, timeout, and an injectable sync/async httpx transport. Project-scoped operations accept a per-call project_id override.

Errors

Every non-2xx response raises a typed subclass of MemorySyncError:

Every error carries status_code, response, and the server-issued request_id (when present) for support escalation.

import time
from memorysync import RateLimitError

try:
    ms.add("...")
except RateLimitError as e:
    time.sleep(e.retry_after_seconds)

License

MIT