Sessions
How a session groups conversation turns against a patient, and how memories form from its turns as they arrive rather than at a session-close event.
A session tracks one conversation or one agent interaction for a single patient — if your application calls it a chat, that is a session here. It stores the messages exchanged during that conversation, and memories are formed from them as they arrive.
A session is always scoped to exactly one patient. It cannot span multiple patients, and a patient can have any number of sessions over time.
Sessions never close
Unlike some conversational session models, a session in the Clinia Context Engine has no close or delete operation. It stays open indefinitely, accumulating messages for as long as messages keep being sent to it. Memories do not wait for the session to end: every submission of new turns is an ingestion that forms memories from them.
This means there is no "session end" event to build workflows around, and no step to trigger memory formation.
Opening a session
A session is opened by its first write. Choose a sessionId — typically your own conversation id — and use it: submit the conversation under it. The first write creates the session; later writes add to it. A new sessionId has to fit the character set for identifiers you assign.
POST /v1/patients/{patientId}/sessions and PUT /v1/patients/{patientId}/sessions/{sessionId} still open a session explicitly, but are deprecated: a session no longer needs opening.
Recording a conversation
POST /v1/patients/{patientId}/ingestions/sessions stores user and assistant messages, in order, under the session. Call it after each turn with the conversation so far: turns already stored are recognised, and only the new ones are stored and analyzed. Each call returns an ingestion receipt to poll.
As the ingestion is processed, the new turns are analyzed, with the turns just before them as context, to extract memories, and memory-to-fact relationships are inferred for the clinically-anchored ones. A turn is analyzed once: later submissions only add memories for new turns, and are not deduplicated against memories already extracted.
Use GET /v1/patients/{patientId}/sessions/{sessionId}/memories to page through the memories a session has produced so far. While an ingestion is still being processed, it returns what has landed.
Typical interactive flow
POST .../ingestions/sessionswith the conversation so far, after each turn. The first call opens the session.- Poll the returned ingestion if your application needs the memories straight away.
GET .../sessions/{sessionId}/memoriesto inspect what's been extracted so far.
See Manage a Session for a worked example of this flow.
Importing conversations that already happened
To store transcripts after the fact rather than turn by turn, submit them to POST /v1/patients/{patientId}/ingestions/sessions. Several transcripts go in one call as one ingestion, each stored as a session under the id it declares or a generated one, and memories are formed from them as the ingestion is processed. Resending a session with new turns at the end continues it. See Ingest Sessions.
How Interactions Become Memory
How the Context Engine learns memories from conversations, keeps them apart from the structured record and links them to the facts they speak to.
Manage a Session
Record a conversation turn by turn under a session id, follow its ingestion, and read back what was extracted.