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)

Conversation turns

add_turn() sends one conversation turn to fact extraction. Only the durable facts in a user turn are stored, as memories with their own ids; the turn text itself is not stored, so memory_id in the response is always None. A user turn sent to extraction counts as one add. Assistant, system and tool turns store nothing and are not counted, so when you capture a conversation, sending only the user turns saves the round trips.

receipt = ms.add_turn(
    tenant_id="acme",
    user_id="user_42",
    text="I always fly with the window seat.",
    role="user",              # "user" | "assistant" | "system" | "tool"
    session_id="thread-42",   # copied onto the extracted facts
)
receipt["status"]             # "processing" when extraction started, else "ok"
receipt["processing_status"]  # "distilling", "skipped_non_user_turn", "skipped_low_value", ...
receipt["request_id"]         # correlates the extraction job

Sending the same speaker, occurred_at and text for the same user again within 30 days is recognised: the response has already_exists: True and nothing is extracted twice.

Conversation history

A transcript your agent reads back, such as chat history, has its own store. Turns are kept as given and are never memories: they do not show up in memory lists, search or recall. With extract=True (the default) the user turns are also sent to fact extraction.

ms.append_history(
    tenant_id="acme",
    user_id="user_42",
    session_id="thread-42",
    source="my-app",
    turns=[
        {"role": "user", "content": "I prefer window seats.", "seq": 0},
        {"role": "assistant", "content": "Noted.", "seq": 1},
    ],
)

history = ms.list_history(tenant_id="acme", user_id="user_42", session_id="thread-42")
for turn in history["items"]:  # oldest first
    print(turn["role"], turn["content"])

ms.delete_history(tenant_id="acme", user_id="user_42", session_id="thread-42")

A retried turn with the same seq, role and content, or the same idempotency_key, is not stored twice. delete_history takes exactly one of session_id or ids; delete_derived_facts=True also deletes the facts extracted from those turns.

Framework state

Namespaced key/value state a framework keeps between runs, such as a store item or a saved record. Values are never memories either.

ns = ["memories", "user_42"]
ms.put_state(tenant_id="acme", user_id="user_42", namespace=ns, key="diet",
             value={"diet": "vegan"}, source="my-app")
item = ms.get_state(tenant_id="acme", user_id="user_42", namespace=ns,
                    key="diet", source="my-app")["item"]
hits = ms.search_state(tenant_id="acme", user_id="user_42", query="what does the user eat",
                       namespace_prefix=["memories"], source="my-app")
ms.delete_state(tenant_id="acme", user_id="user_42", namespace=ns, keys=["diet"],
                source="my-app")

A put replaces the key's previous value, and putting the identical value again returns created: False. Omitting keys on delete_state deletes the whole namespace. Rows are scoped by source, and the state reads default to "api", so pass the same source on every call.

These return the server's JSON as a dict. An append counts one add for each user turn it sends to fact extraction, or one add when it stores new turns and extracts none; a put counts one add when it stores a new value. A retry that stores nothing new is not counted, reads count one retrieval, and deletes are free. Over the plan limit they return normally and store nothing: writes answer status: "skipped" and reads come back empty.

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