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 turn or 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 turn within a session. Events typically represent a user message, an agent response, or any application-defined action. 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.

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.

>>> 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()