# Agentic memory

> Agentic memory - The agentic memory SDK persists chat-style history for agentic applications. It
> exposes three types: aMemorySpacethat groups related conversations, aSessionthat represents a single
> conversation, and anEventthat records a turn or message within a session.

This Markdown file sits beside the HTML page at the same path (with a `.md` suffix). It summarizes the topic and lists links for tools and LLM context.

Companion generated at `2026-05-06T18:17:09.590822+00:00` (UTC).

## Primary page

- [Agentic memory](https://docs.datarobot.com/en/docs/api/dev-learning/python/genai/agentic-memory.html): Full documentation for this topic (HTML).

## Sections on this page

- [Memory terminology](https://docs.datarobot.com/en/docs/api/dev-learning/python/genai/agentic-memory.html#memory-terminology): In-page section heading.
- [Memory space](https://docs.datarobot.com/en/docs/api/dev-learning/python/genai/agentic-memory.html#memory-space): In-page section heading.
- [Create and modify a memory space](https://docs.datarobot.com/en/docs/api/dev-learning/python/genai/agentic-memory.html#create-and-modify-a-memory-space): In-page section heading.
- [Retrieve memory spaces](https://docs.datarobot.com/en/docs/api/dev-learning/python/genai/agentic-memory.html#retrieve-memory-spaces): In-page section heading.
- [Delete a memory space](https://docs.datarobot.com/en/docs/api/dev-learning/python/genai/agentic-memory.html#delete-a-memory-space): In-page section heading.
- [Sessions and events](https://docs.datarobot.com/en/docs/api/dev-learning/python/genai/agentic-memory.html#sessions-and-events): In-page section heading.
- [Create a session and append events](https://docs.datarobot.com/en/docs/api/dev-learning/python/genai/agentic-memory.html#create-a-session-and-append-events): In-page section heading.
- [Update an event](https://docs.datarobot.com/en/docs/api/dev-learning/python/genai/agentic-memory.html#update-an-event): In-page section heading.
- [List events](https://docs.datarobot.com/en/docs/api/dev-learning/python/genai/agentic-memory.html#list-events): In-page section heading.
- [Update or delete a session](https://docs.datarobot.com/en/docs/api/dev-learning/python/genai/agentic-memory.html#update-or-delete-a-session): In-page section heading.

## Related documentation

- [Developer documentation](https://docs.datarobot.com/en/docs/api/index.html): Linked from this page.
- [Developer learning](https://docs.datarobot.com/en/docs/api/dev-learning/index.html): Linked from this page.
- [Python API client user guide](https://docs.datarobot.com/en/docs/api/dev-learning/python/index.html): Linked from this page.
- [Generative AI](https://docs.datarobot.com/en/docs/api/dev-learning/python/genai/index.html): Linked from this page.

## Documentation content

The agentic memory SDK persists chat-style history for agentic applications. It exposes three types: a [MemorySpace](https://docs.datarobot.com/en/docs/api/dev-learning/python/genai/agentic-memory.html#memory-space) that groups related conversations, a [Session](https://docs.datarobot.com/en/docs/api/dev-learning/python/genai/agentic-memory.html#sessions) that represents a single conversation, and an [Event](https://docs.datarobot.com/en/docs/api/dev-learning/python/genai/agentic-memory.html#events) that records a turn or message within a session.

> [!NOTE] Premium
> DataRobot's Agentic AI capabilities are a premium feature; contact your DataRobot representative for enablement information.

## 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](https://docs.datarobot.com/en/docs/api/dev-learning/python/genai/agentic-memory.html#memory-space) 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](https://docs.datarobot.com/en/docs/api/dev-learning/python/genai/agentic-memory.html#sessions) with [Session.create](https://docs.datarobot.com/en/docs/api/dev-learning/python/genai/agentic-memory.html#sessions), passing the parent `memory_space_id` and the `participants` list. Use [Session.post_event](https://docs.datarobot.com/en/docs/api/dev-learning/python/genai/agentic-memory.html#events) 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.

> [!NOTE] One participant per session
> Multi-participant sessions are not supported. Pass a single-element list to `participants`; the server rejects sessions with more than one participant.

```
>>> 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](https://docs.datarobot.com/en/docs/api/dev-learning/python/genai/agentic-memory.html#events) 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](https://docs.datarobot.com/en/docs/api/dev-learning/python/genai/agentic-memory.html#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()
```