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
| Field | Type | Contract |
|---|---|---|
tenant_id | string | Required tenant identifier. |
user_id | string | Required end-user identifier. |
text | string | Required. What was said in this turn. A user turn is sent to fact extraction; the text itself is never stored. Empty text is refused. |
role | string | Optional 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. |
speaker | string | Optional attribution. Together with occurred_at and the text it identifies the turn, so a retry is recognised. |
occurred_at | string | Optional ISO-8601 timestamp of when the turn happened. Part of the same replay key. |
metadata | object | Optional. 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. |
source | string | Optional integration label stored on the extracted facts. Defaults to chat. |
sync_embed | boolean | Optional. Accepted and has no effect. |
Add a turn
import osfrom memorysync import MemorySyncClientclient = 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 |
|---|---|
distilling | A user turn was accepted; facts are being extracted. |
completed / failed | Extraction ran inline and finished, or could not run. |
skipped_non_user_turn | An assistant, system or tool turn. Nothing is stored. |
skipped_low_value | Filler such as “ok” or “thanks”. Nothing is stored. |
skipped_replay | The same speaker + occurred_at + text was sent for this user within 30 days. It is not extracted again, and already_exists is true. |
skipped | The 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
Related reference
Was this page helpful?