Memory

class datarobot.models.memory.MemorySpace

A container for chat sessions and their events.

A memory space groups related sessions and memories together, providing an isolation boundary for conversational, semantic, and episodic memories in agentic applications.

Added in version v3.15.

Variables:

id (str) – The ID of the memory space.
user_id (str) – The ID of the user who owns the memory space.
tenant_id (str) – The ID of the tenant.
description (str or None) – Optional. A human-readable description.
llm_model_name (str or None) – Optional. An LLM model name associated with the memory space (maximum 200 characters). Non-reasoning models such as gpt-4o are recommended. Reasoning-capable models are significantly slower for fact extraction without producing meaningfully better results.
llm_base_url (str or None) – Optional. The chat API URL used for memory extraction. The memory service uses the DataRobot LLM gateway by default; set this only when the default does not work — for example, in air-gapped environments or when the required LLM model is not provided by the gateway and cannot be added.
custom_instructions (str or None) – Optional. Custom prompt instructions for fact extraction (maximum 10,000 characters). None means the default memory extraction prompt is used.
created_at (datetime.datetime) – The timestamp when the memory space was created.

classmethod create(description=None, llm_model_name=None, llm_base_url=None, custom_instructions=None)

Create a new memory space.

Added in version v3.15.

Parameters:

description (str or None) – Optional. A human-readable description for the memory space.
llm_model_name (str or None) – Optional. An LLM model name to associate with the memory space (maximum 200 characters). Non-reasoning models such as gpt-4o are recommended. Reasoning-capable models are significantly slower for fact extraction without producing meaningfully better results.
llm_base_url (str or None) – Optional. Chat API URL used for memory extraction. The memory service uses the DataRobot LLM gateway by default; set this only when the default does not work — for example, in air-gapped environments or when the required LLM model is not provided by the gateway and cannot be added.
custom_instructions (str or None) – Optional. Custom prompt instructions for fact extraction (maximum 10 000 characters).

Returns:

The newly created memory space.

Return type:

MemorySpace

classmethod list(offset=None, limit=None)

List memory spaces accessible to the current user.

Added in version v3.15.

Parameters:

offset (int or None) – Optional number of events to skip from the beginning.
limit (int or None) – Optional. The maximum number of items to return.

Returns:

The available memory spaces.

Return type:

list of MemorySpace

classmethod get(memory_space_id)

Get a memory space by its ID.

Added in version v3.15.

Parameters:: memory_space_id (str) – The ID of the memory space to retrieve.
Returns:: The requested memory space.
Return type:: MemorySpace

update(description=<object object>, llm_model_name=<object object>, llm_base_url=<object object>, custom_instructions=<object object>)

Update the memory space.

If called without arguments, there is no effect. Pass None to clear a field.

Added in version v3.15.

Parameters:

description (str or None) – The new description. Pass None to clear the existing description.
llm_model_name (str or None) – The new LLM model name (maximum 200 characters). Pass None to clear an existing LLM. Non-reasoning models such as gpt-4o are recommended. Reasoning-capable models are significantly slower for fact extraction without producing meaningfully better results.
llm_base_url (str or None) – The new chat API URL used for memory extraction. Pass None to clear and fall back to the DataRobot LLM gateway (the default). Set this only when the gateway does not work — for example, in air-gapped environments or when the required LLM model is not provided by the gateway and cannot be added.
custom_instructions (str or None) – The new custom instructions (maximum 10 000 characters). Pass None to revert to the default memory extraction prompt.

Return type:

None

delete()

Delete the memory space.

Added in version v3.15.

Return type:: None

class datarobot.models.memory.Session

A chat session within a MemorySpace.

Sessions track conversations between participants and store the sequence of Event objects that reflect either a single message or a state.

Added in version v3.15.

Variables:

id (str) – The session ID.
participants (list of str) – IDs of the participants in this session.
description (str or None) – Optional. A human-readable description.
metadata (dict or None) – Optional. Application-defined metadata.
created_at (datetime.datetime) – The timestamp when the session was created.
lifecycle_strategies (list of dict) – The lifecycle strategy configurations attached to this session. See the Notes section below for the dict shape, allowed values, and examples.
version (int or None) – A monotonic counter incremented by the server on every successful update. Populated when the session is loaded from the server; None for manually constructed instances or older servers that do not return it. Used as the default If-Match precondition on update().
deduplication_key (str or None) – Optional key supplied at create time to prevent duplicate sessions. Echoed back by the server and used to detect repeat session creations within the same memory space. None when the session was created without a key.
memory_space_id (str or None) – The ID of the parent memory space. This value is set automatically.

Notes

Lifecycle strategies

Each entry in lifecycle_strategies is a dict with three keys:

type (str, required) - one of:
- "soft_delete" - mark the session as deleted when the trigger fires. Soft-deleted sessions are excluded from listings and their events become unreadable, but the record is retained for audit.
- "extract_memories" - run memory extraction over the session’s events and persist the resulting memories into the parent memory space when the trigger fires.
trigger (dict, required) - exactly one key, all integer-valued:
- {"ttl": <seconds>} - elapsed time since session creation. 1 <= ttl <= 63_072_000 (2 years).
- {"eventCount": <n>} - cumulative event count in the session. 1 <= n <= 1_000_000.
- {"tokenCount": <n>} - cumulative token count over event message content. 1 <= n <= 100_000_000.
- {"idle": <seconds>} - time since the last event (falls back to session creation time when there are no events). 1 <= idle <= 63_072_000.
opts (dict or None, optional) - strategy-specific options:
- "soft_delete" - no options; pass None or omit.
- "extract_memories":
  softDelete (bool, default True) - also soft-delete the session after extracting memories.
  
  agentId (str or None) - agent ID attached to extracted memories.
  
  metadata (dict or None) - metadata attached to extracted memories.

When lifecycle_strategies is omitted or empty on Session.create(), the server attaches a default "soft_delete" strategy with a 180-day TTL. A session may have at most 5 strategies.

Examples

# Delete the session after 7 days.
[{"type": "soft_delete", "trigger": {"ttl": 604800}}]

# Extract memories after 100 events; keep the session live afterwards.
[{
    "type": "extract_memories",
    "trigger": {"eventCount": 100},
    "opts": {"softDelete": False, "agentId": "support-bot"},
}]

# Combine strategies: extract once idle for an hour, hard-cap with a 30-day TTL.
[
    {"type": "extract_memories", "trigger": {"idle": 3600}},
    {"type": "soft_delete", "trigger": {"ttl": 2592000}},
]

classmethod create(memory_space_id, participants, lifecycle_strategies=None, description=None, metadata=None, deduplication_key=None)

Create a new session in a memory space.

Every session must have at least one lifecycle strategy. If lifecycle_strategies is not provided or is an empty list, the server attaches a default strategy.

Added in version v3.15.

Changed in version v3.17: Added optional deduplication_key parameter to prevent duplicate session creations.

Parameters:

memory_space_id (str) – The ID of the memory space to create the session in.
participants (list of str) – IDs of the participants in the session.
lifecycle_strategies (list of dict or None) – Optional. The lifecycle strategy configurations. Each item is a dict with type, trigger, and optional opts keys - see the Notes section on Session for the full shape, allowed values, and working examples. When omitted or empty, the server attaches a default "soft_delete" strategy with a 180-day TTL. At most 5 strategies may be attached to a session.
description (str or None) – Optional. A human-readable description.
metadata (dict or None) – Optional. Application-defined metadata.
deduplication_key (str or None) – Optional. A 1-72 character key that prevents duplicate sessions. If a live session with the same key already exists in this memory space, the server returns 409 Conflict and the SDK raises MemorySessionDeduplicationError, which carries existing_session_id so callers can adopt the winning session. None keys do not collide; the same key may be reused across different memory spaces; soft-deleting a session frees the key.

Returns:

The newly created session.

Return type:

Session

Raises:

MemorySessionDeduplicationError – When deduplication_key is supplied and a live session with the same key already exists in this memory space.

classmethod list(memory_space_id, offset=None, limit=None, participants=None, description=None)

List sessions within a single memory space.

Added in version v3.15.

Parameters:

memory_space_id (str) – The ID of the memory space.
offset (int or None) – Optional number of events to skip from the beginning.
limit (int or None) – Optional maximum number of items to return.
participants (list of str or None) – Optional filter by participant IDs.
description (str or None) – Optional filter by description.

Returns:

The matching sessions.

Return type:

list of Session

classmethod get(memory_space_id, session_id)

Get a session by its ID.

Added in version v3.15.

Parameters:

memory_space_id (str) – The ID of the memory space.
session_id (str) – The ID of the session to retrieve.

Returns:

The requested session.

Return type:

Session

update(description=<object object>, metadata=<object object>, if_match=<object object>)

Update the session.

If called without arguments, there is no effect. Pass None to clear a field.

By default the SDK uses version (set by a prior load) as an optimistic-concurrency precondition. If the server’s stored version no longer matches, it returns 409 (surfaced as datarobot.errors.ClientError). The caller is expected to reload the session via get() and retry.

Added in version v3.15.

Parameters:

description (str or None) – The new description. Pass None to clear.
metadata (dict or None) – The new metadata. Pass None to clear.
if_match (int or None) – Optimistic-concurrency precondition. When omitted, the SDK uses version automatically. Pass None to opt out (legacy last-writer-wins). Pass an integer to override the version.

Return type:

None

delete()

Delete the session.

Added in version v3.15.

Return type:: None

post_event(body, emitter, event_type=None)

Create an event in this session.

Added in version v3.15.

Parameters:

body (dict) – The event payload.
emitter (dict) – Identifies the entity that produced the event, which typically contains "type" and "id" keys.
event_type (str or None) – Optional. An application-defined event-type label.

Returns:

The newly created event.

Return type:

Event

events(offset=None, limit=None, last_n=None, event_type=None)

List events in this session.

Provide either offset or last_n, but not both.

Added in version v3.15.

Parameters:

offset (int or None) – Optional . The number of events to skip from the beginning.
limit (int or None) – Optional. The maximum number of events to return.
last_n (int or None) – Optional. The number of most recent events to return. This value is mutually exclusive with offset.
event_type (str or None) – Optional. An event-type label.

Returns:

The matching events.

Return type:

list of Event

update_event(sequence_id, body=<object object>, event_type=<object object>, emitter=<object object>, created_at=None)

Update an event by its sequence ID.

When created_at is provided, the server uses it for optimistic concurrency control. Specifically, if the event has been modified since that timestamp, the server rejects the update. The caller must handle this error and reload the event before retrying.

Added in version v3.15.

Parameters:

sequence_id (int) – The ordinal position of the event to update.
body (dict or None) – The new event payload.
event_type (str or None) – The new event-type label.
emitter (dict or None) – The new emitter information; the type of entity that emitted the event (e.g. "agent" or "user").
created_at (datetime.datetime or None) – Optional timestamp for optimistic concurrency control.

Returns:

The updated event, or None if called with no changes.

Return type:

Event or None

post_events(events)

Append a batch of events to this session atomically.

The entire batch is appended in a single transaction; if any item fails validation, no events are created. Server-side limit is 200 events per request.

Added in version v3.17.

Parameters:: events (list of NewEvent) – Events to append, in order. Each item requires body and emitter and may include an event_type.
Returns:: The newly created events, in the same order as the input.
Return type:: list of Event

update_events(events)

Update a batch of events in this session atomically.

Each item identifies the target event by sequence_id and must set at least one of body, event_type, emitter. Duplicate sequence_id values are rejected. The whole batch is applied in a single transaction; any failure rolls back every change. Server-side limit is 200 events per request.

created_at is per-item optimistic concurrency: if provided and the target event has been modified since that timestamp, the update is rejected and the batch rolls back.

Added in version v3.17.

Parameters:: events (list of EventUpdate) – Events to update. Each item requires sequence_id and at least one of body, event_type, emitter. created_at is an optional per-item version check.
Returns:: The updated events.
Return type:: list of Event

class datarobot.models.memory.Event

A single action or chat message within a Session.

Events are always scoped to a session. Use Session.post_event(), Session.events(), and Session.update_event() to manage them.

Added in version v3.15.

Variables:

body (dict or None) – The event payload.
event_type (str or None) – An application-defined event-type label.
emitter_type (str or None) – The type of entity that emitted the event (e.g., "agent" or "user").
emitter_id (str or None) – The ID of the entity that generated the event.
sequence_id (int or None) – The ordinal position of the event within its session.
created_at (datetime.datetime or None) – The timestamp when the event was created.