MemorySync
API Reference

Add Conversation Turn

Send one conversation turn to fact extraction. The durable facts in a user turn become memories; the turn text itself is not stored.

Endpoint and request fields

POST/v1/memory/add_turn
201 Created
FieldTypeContract
tenant_idstringRequired tenant identifier.
user_idstringRequired end-user identifier.
textstringRequired. What was said in this turn. A user turn is sent to fact extraction; the text itself is never stored. Empty text is refused.
rolestringOptional user, assistant, system or tool. When omitted, a leading user: / assistant: prefix on the text (stripped), then the head of speaker (user@…), then metadata.role decide; otherwise the turn is the user’s.
speakerstringOptional attribution. Together with occurred_at and the text it identifies the turn, so a retry is recognised.
occurred_atstringOptional ISO-8601 timestamp of when the turn happened. Part of the same replay key.
metadataobjectOptional. Scalar values are copied onto the extracted facts; session_id groups the facts by conversation, so they can later be listed or forgotten per session.
sourcestringOptional integration label stored on the extracted facts. Defaults to chat.
sync_embedbooleanOptional. Accepted and has no effect.

Add a turn

import os
from memorysync import MemorySyncClient
client = 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",
)
result = client.add_turn(
tenant_id="acme",
user_id="usr_7f3a9c2e",
text="I always fly with the window seat.",
role="user",
speaker="user@thread-42",
occurred_at="2026-08-22T10:00:00Z",
metadata={"session_id": "thread-42"},
)
# result["memory_id"] is None; result["processing_status"] == "distilling"
response.json
{"memory_id":null,"status":"processing","processing_status":"distilling","embed_mode":"none","already_exists":false,"processing_error":null,"request_id":"9f3a51c0e2d84b7a"}

Result handling

The answer is a receipt for the extraction, not a stored record: memory_id is always null. The facts found in a user turn arrive asynchronously as memories with their own ids — read them with List Memories or Recall Context. request_id correlates the extraction job, and status is processing when extraction started, ok otherwise.

`processing_status`Meaning
distillingA user turn was accepted; facts are being extracted.
completed / failedExtraction ran inline and finished, or could not run.
skipped_non_user_turnAn assistant, system or tool turn. Nothing is stored.
skipped_low_valueFiller such as “ok” or “thanks”. Nothing is stored.
skipped_replayThe same speaker + occurred_at + text was sent for this user within 30 days. It is not extracted again, and already_exists is true.
skippedThe organization is over its monthly plan limit. Nothing is stored.

Errors and next action

A 422 means a missing tenant_id, user_id or empty text. The endpoint takes exactly one turn as text; a messages array is refused, and the SDKs refuse it client-side. For 429 or 5xx, keep the turn and send it again: the replay key makes a retry safe.

Safety notes

Was this page helpful?