Agentic memory¶

The agentic memory SDK persists chat-style history for agentic applications. It exposes three types: a MemorySpace that groups related conversations, a Session that represents a single conversation, and an Event that records a message within a session.

Memory terminology¶

The agentic memory SDK uses the following terminology:

• MemorySpace: A container for sessions and their events. A memory space provides an isolation boundary for chat-style sessions and the events recorded in them.
• Session: A single chat conversation within a memory space. Each session tracks its participants, optional metadata, and the ordered stream of events.
• Event: A single message within a session. Each event is one message on the conversation stack—for example, a user message, an agent response, or a tool result. Events are ordered by sequence_id within their session.
• Lifecycle strategy: A server-side rule that governs how long a session and its events are retained. If you do not provide one when creating a session, the server attaches a default strategy.

The recommended workflow is:

1. Create a datarobot.models.memory.MemorySpace to hold related conversations.
2. Create one or more datarobot.models.memory.Session objects in that memory space, one per conversation.
3. Append datarobot.models.memory.Event records to a session as the conversation progresses, and update events when they need to be revised.

Memory space¶

A memory space is the top-level container. It holds sessions and is scoped to the calling user and tenant. You can access only memory spaces you own or that another user shared with you.

Your administrator must enable Enable Access to Agentic Memory API on your user profile before you can use MemorySpace or related APIs. Per-space sharing roles (Consumer, Editor, Owner) then determine what you can do on each memory space you own or that was shared with you.

See Enable access to the agentic memory API, Memory space roles, and Sharing and access control.

Create and modify a memory space¶

Use MemorySpace.create to create a memory space, then call update on the returned object to change its description or associated LLM model name. Pass None to clear an optional field.

>>> from datarobot.models.memory import MemorySpace
>>>
>>> # Create a new memory space
>>> memory_space = MemorySpace.create(
...     description="Customer support assistant memory",
...     llm_model_name="gpt-4o",
... )
>>> memory_space.id
'deadbeef-cafe-babe-feed-cafebabe0000'
>>>
>>> # Update the description; leave llm_model_name unchanged
>>> memory_space.update(description="Customer support assistant -- production")
>>> memory_space.description
'Customer support assistant -- production'
>>>
>>> # Clear the LLM model name by passing None
>>> memory_space.update(llm_model_name=None)
>>> memory_space.llm_model_name is None
True

Retrieve memory spaces¶

You can list memory spaces accessible to the current user, or fetch a specific one by ID. MemorySpace.list() returns only spaces you own or that have been shared with you.

Each memory space response includes permissions (your effective access) and may include rbacResourceId for platform sharing enforcement. To add or change collaborators, use the Registry Share dialog; sharing is not available through the Python SDK. See Manage sharing in Registry.

>>> from datarobot.models.memory import MemorySpace
>>>
>>> # Returns one server-paginated page; use offset and limit to walk further pages
>>> memory_spaces = MemorySpace.list()
>>> next_page = MemorySpace.list(offset=len(memory_spaces), limit=20)
>>>
>>> # Fetch a specific memory space by ID
>>> memory_space = MemorySpace.get("deadbeef-cafe-babe-feed-cafebabe0000")

Delete a memory space¶

Deleting a memory space removes all its sessions and events. The operation is not reversible.

>>> memory_space.delete()

Sessions and events¶

A session represents a single conversation. Events are appended to a session in order; each event has a server-assigned sequence_id that reflects its position within the session.

Create a session and append events¶

Create a Session with Session.create, passing the parent memory_space_id and the participants list. Use Session.post_event to append events as the conversation progresses. The emitter dictionary identifies the entity that produced the event -- typically {"type": "user", "id": <participant_id>} for a human turn and {"type": "agent", "id": <agent_id>} for an agent reply.

>>> from datarobot.models.memory import Session
>>>
>>> participant_id = "ba5eba11deadbeefcafebabe"
>>> agent_id = "agent-001"
>>>
>>> # Create a session in the memory space
>>> session = Session.create(
...     memory_space_id=memory_space.id,
...     participants=[participant_id],
...     description="Order status inquiry",
...     metadata={"channel": "web", "priority": "high"},
... )
>>>
>>> # Append a user message
>>> user_event = session.post_event(
...     body={"content": "Can you check the status of my order?"},
...     emitter={"type": "user", "id": participant_id},
...     event_type="message",
... )
>>> user_event.sequence_id
0
>>>
>>> # Append an agent reply
>>> agent_event = session.post_event(
...     body={"content": "Let me check that for you."},
...     emitter={"type": "agent", "id": agent_id},
...     event_type="message",
... )
>>> agent_event.sequence_id
1

Update an event¶

Use Session.update_event to revise an event's body, type, or emitter. Identify the target event by its sequence_id. To guard against concurrent writes, pass the event's created_at timestamp; the server rejects the update if the event has been modified since that timestamp, and the caller must reload the event before retrying.

>>> # The agent's answer needs to be replaced after fetching real data
>>> updated = session.update_event(
...     sequence_id=agent_event.sequence_id,
...     body={"content": "Your order has shipped and is scheduled to arrive within two business days."},
...     created_at=agent_event.created_at,  # Optimistic concurrency check
... )
>>> updated.body
{'content': 'Your order has shipped and is scheduled to arrive within two business days.'}

List events¶

Read events back with Session.events. Use last_n to fetch the most recent events, or offset and limit to page from the beginning. The two are mutually exclusive. Filter by event_type to retrieve only a specific kind of event.

>>> # Fetch the most recent 50 message events
>>> recent = session.events(last_n=50, event_type="message")
>>>
>>> # Read the first 100 events from the start of the session
>>> first_page = session.events(offset=0, limit=100)
>>>
>>> # Walk subsequent pages with offset
>>> next_page = session.events(offset=len(first_page), limit=100)

Update or delete a session¶

Update a session's description or metadata with Session.update. Pass None to clear a field. Delete a session and its events with Session.delete.

>>> session.update(metadata={"channel": "web", "priority": "low"})
>>> session.delete()