Sessions

A session tracks one conversation or one agent interaction for a single patient. It stores the messages exchanged during that conversation, and can be analyzed on demand to produce memories.

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 Patient Memory session has no close or delete operation. It stays open indefinitely, accumulating messages for as long as messages keep being appended to it. Memory generation is a separate, on-demand step you trigger explicitly. It does not require, and is not triggered by, ending the session.

This means there is no "session end" event to build workflows around. It's the calling application, not the endpoint, that decides when to call generate memories: a common trigger is the user leaving the conversation or switching context, even if the underlying session is never explicitly closed. Messages can still be appended to the same session afterward if the conversation continues.

Opening a session

Two endpoints open a session:

The PUT form is useful when the caller already has a natural conversation ID (for example, from its own chat infrastructure) and wants to open-or-resume that session without first checking whether it exists.

Appending messages

POST /v1/patients/{patientId}/sessions/{sessionId}/messages appends user and assistant messages, in order, to the session's transcript. Call it once per turn as the conversation progresses.

Generating memories

POST /v1/patients/{patientId}/sessions/{sessionId}/memories analyzes the messages appended since the last run, extracts memories, and infers memory-to-fact relationships for the clinically-anchored ones.

Two things to keep in mind:

• The session stays active. Nothing about calling this endpoint closes or locks the session. More messages can be appended afterward, and memories can be generated again later.
• It's append-only. Re-running it extracts memories from messages added since the last extraction, and appends whatever new memories that produces. It does not deduplicate against memories from a previous run. Call it intentionally, at a point your application considers the current interaction window over (such as the user leaving or switching context), rather than after every single message.

Use GET /v1/patients/{patientId}/sessions/{sessionId}/memories to page through the memories a session has produced so far.

Typical interactive flow

1. POST or PUT a session to open it.
2. POST .../messages as each conversation turn happens.
3. POST .../memories when your application considers the current interaction window over, for example the user leaving the conversation or switching context, repeating as the conversation continues.
4. GET .../memories to inspect what's been extracted so far.

See Manage a Session for a worked example of this flow.