API Reference

Add Conversation Turn

Store one conversational turn verbatim so a transcript can be replayed word for word — the episodic sibling of the extraction-gated fact store.

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. The turn, stored exactly as supplied — no extraction, no rewriting, no value gate. Empty text is the only refusal.
`speaker`	string	Optional attribution (who said it). Joins the idempotency seed, so the same sentence from two speakers stores twice.
`occurred_at`	string	Optional ISO-8601 timestamp of when the turn happened. Also joins the idempotency seed.
`metadata`	object	Optional metadata persisted with the row.
`source`	string	Optional origin label. Defaults to `chat`.
`sync_embed`	boolean	Optional. When true, embedding runs inline so the row is immediately queryable; default is async.

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.",
    speaker="user",
    occurred_at="2026-08-22T10:00:00Z",
)

Result handling

The answer carries memory_id, a processing_status, and already_exists. Nothing is judged or rewritten — the text is stored as-is and embedded for retrieval. Replaying an identical payload (same text, speaker and occurred_at) answers already_exists: true with the original id instead of storing a duplicate, which is what makes a retry safe. To distill a conversation into curated facts instead, use Add Memory.

Errors and next action

A 422 means a missing tenant_id, user_id or empty text. SDKs 1.9.1 and later also refuse the retired messages array client-side — this endpoint stores exactly one turn, so format it as a string and pass text. For 429 or 5xx, keep the turn so it can be replayed; the idempotency seed makes the replay safe.

Safety notes

Add Memory

Distill input into curated facts instead of storing it verbatim.

Recall Context

Read the turn back as prompt context.

Was this page helpful?

← Previous

Submit Feedback