Developer documentation > API reference > Memory

Memory¶

MemorySpace¶

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

Attribute	Type	Description
`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.
`deduplication_key`	`str` or `None`	Optional key supplied at create time to prevent duplicate memory spaces. Echoed back by the server and used to detect repeat memory space creations by the same user. `None` when the memory space was created without a key.

create()¶

classmethod create()

Create a new memory space.

Added in version v3.15.

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

Parameters

Parameter	Type	Description
`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).
`deduplication_key`	`str` or `None`	Optional. A 1-72 character key that prevents duplicate memory spaces. If a live memory space with the same key already exists for this user, the server returns `409 Conflict` and the SDK raises `MemorySpaceDeduplicationError`, which carries `existing_memory_space_id` so callers can adopt the winning memory space. `None` keys do not collide; soft-deleting a memory space frees the key.

Returns

Returns	Description
The newly created memory space.

Return type: MemorySpace

Raises

Exception	Description
MemorySpaceDeduplicationError	When `deduplication_key` is supplied and a live memory space with the same key already exists for this user.

list()¶

classmethod list()

List memory spaces accessible to the current user.

Added in version v3.15.

Changed in version v3.17: Added optional deduplication_key filter.

Parameters

Parameter	Type	Description
`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.
`deduplication_key`	`str` or `None`	Optional. Filter to the memory space with this exact deduplication key.

Returns

Returns	Description
The available memory spaces.

Return type: list of MemorySpace

get()¶

classmethod get()

Get a memory space by its ID.

Added in version v3.15.

Parameters

Parameter	Type	Description
`memory_space_id`	`str`	The ID of the memory space to retrieve.

Returns

Returns	Description
The requested memory space.

Return type: MemorySpace

update()¶

method update()

Update the memory space.

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

Added in version v3.15.

Parameters

Parameter	Type	Description
`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()¶

method delete()

Delete the memory space.

Added in version v3.15.

Return type: None

Session¶

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

Attribute	Type	Description
`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}},
]

create()¶

classmethod create()

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

Parameter	Type	Description
`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

Returns	Description
The newly created session.

Return type: Session

Raises

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

list()¶

classmethod list()

List sessions within a single memory space.

Added in version v3.15.

Parameters

Parameter	Type	Description
`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

Returns	Description
The matching sessions.

Return type: list of Session

get()¶

classmethod get()

Get a session by its ID.

Added in version v3.15.

Parameters

Parameter	Type	Description
`memory_space_id`	`str`	The ID of the memory space.
`session_id`	`str`	The ID of the session to retrieve.

Returns

Returns	Description
The requested session.

Return type: Session

update()¶

method update()

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

Parameter	Type	Description
`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()¶

method delete()

Delete the session.

Added in version v3.15.

Return type: None

post_event()¶

method post_event()

Create an event in this session.

Added in version v3.15.

Parameters

Parameter	Type	Description
`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

Returns	Description
The newly created event.

Return type: Event

events()¶

method events()

List events in this session.

Provide either offset or last_n, but not both.

Added in version v3.15.

Parameters

Parameter	Type	Description
`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

Returns	Description
The matching events.

Return type: list of Event

update_event()¶

method update_event()

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

Parameter	Type	Description
`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

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

Return type: Event or None

post_events()¶

method post_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

Parameter	Type	Description
`events`	`list` of `NewEvent`	Events to append, in order. Each item requires `body` and `emitter` and may include an `event_type`.

Returns

Returns	Description
The newly created events, in the same order as the input.

Return type: list of Event

update_events()¶

method update_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

Parameter	Type	Description
`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

Returns	Description
The updated events.

Return type: list of Event

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

Attribute	Type	Description
`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.