Memory API reference

This page is the REST API reference for managed agent memory. It covers the endpoints, request fields, and response fields for managed memory:

A memory store is a Unity Catalog securable that acts as a container for memory entries. Use the Memory store APIs to create and manage stores.
A memory entry is an individual piece of content stored inside a memory store. Use the Memory entry APIs to read and write entries.
A conversation is OpenAI-compatible conversation state — messages and tool calls — backed by a memory store and pinned to a scope. Use the Conversation APIs to create and manage conversations and their items.

Prerequisites

Generate an OAuth token using the Databricks CLI to call the APIs:

Bash
databricks auth login --host ${DATABRICKS_HOST}
databricks auth token

Memory store APIs

A memory store is a Unity Catalog securable that acts as a container for memory entries. Memory stores use three-level naming: catalog.schema.memory_store_name.

Operation	Endpoint	Required privilege
Create	`POST /api/2.1/unity-catalog/memory-stores`	`CREATE MEMORY STORE` on the parent schema
Get	`GET /api/2.1/unity-catalog/memory-stores/{full_name}`	`READ MEMORY STORE` on the store
List	`GET /api/2.1/unity-catalog/memory-stores`	`USE SCHEMA` on the parent schema
Update	`PATCH /api/2.1/unity-catalog/memory-stores/{full_name}`	`MANAGE` on the store
Delete	`DELETE /api/2.1/unity-catalog/memory-stores/{full_name}`	`MANAGE` on the store

Create a memory store

Creates a new memory store under a parent schema.

Endpoint: POST /api/2.1/unity-catalog/memory-stores
Required privilege: CREATE MEMORY STORE on the parent schema

Bash
curl -X POST "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "agent_memory",
    "catalog_name": "main",
    "schema_name": "default",
    "description": "Memory store for customer support agents"
  }'

Request fields:

Field	Type	Required	Description
`name`	`string`	Yes	Short name for the memory store. Must match `[A-Za-z0-9_-]+`, 1-255 characters. Unique within the parent schema.
`catalog_name`	`string`	Yes	Name of the parent catalog.
`schema_name`	`string`	Yes	Name of the parent schema, relative to the catalog.
`description`	`string`	No	Human-readable description of the memory store.

Get a memory store

Retrieves a memory store by its three-part fully qualified name.

Endpoint: GET /api/2.1/unity-catalog/memory-stores/{full_name}
Required privilege: READ MEMORY STORE on the store

Bash
curl -X GET \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

List memory stores

Lists memory stores in a schema. Results are filtered to stores the caller can read.

Endpoint: GET /api/2.1/unity-catalog/memory-stores
Required privilege: USE SCHEMA on the parent schema

Bash
curl -X GET \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores?catalog_name=main&schema_name=default" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Query parameters:

Parameter	Type	Required	Description
`catalog_name`	`string`	Yes	Parent catalog name.
`schema_name`	`string`	Yes	Parent schema name.
`page_token`	`string`	No	Pagination token from a previous response.
`max_results`	`integer`	No	Maximum stores per page. Defaults to 100, max 1000.

Update a memory store

Updates mutable fields on a memory store. Currently only description is mutable.

Endpoint: PATCH /api/2.1/unity-catalog/memory-stores/{full_name}
Required privilege: MANAGE on the store

Bash
curl -X PATCH \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "memory_store": {
      "description": "Updated description for the memory store"
    },
    "update_mask": "description"
  }'

Delete a memory store

Deletes a memory store and all of its memory entries.

Endpoint: DELETE /api/2.1/unity-catalog/memory-stores/{full_name}
Required privilege: MANAGE on the store

Bash
curl -X DELETE \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Memory store response fields

Field	Type	Description
`name`	`string`	Short name of the memory store.
`catalog_name`	`string`	Parent catalog name.
`schema_name`	`string`	Parent schema name.
`description`	`string`	Human-readable description.
`owner`	`string`	UC principal that owns the store. Set on create.
`full_name`	`string`	Three-part fully qualified name: `catalog.schema.name`.
`memory_store_id`	`string`	Server-assigned UUID.
`securable_type`	`string`	Always `MEMORY_STORE`.
`created_at`	`integer`	Creation time in Unix epoch milliseconds.
`updated_at`	`integer`	Last update time in Unix epoch milliseconds.
`created_by`	`string`	Principal that created the store.

Memory entry APIs

Memory entries are the individual pieces of content stored inside a memory store. Each entry is identified by a scope and a path: scope is a partition key the caller assigns (for example, an end-user ID), and path is a soft path within that scope that must start with /memories/ (for example, /memories/preferences.md). scope is required on every memory entry request.

Operation	Endpoint	Required privilege
Create	`POST /api/2.1/unity-catalog/memory-stores/{full_name}/entries`	`WRITE MEMORY STORE` on the store
Get	`GET /api/2.1/unity-catalog/memory-stores/{full_name}/entries:get`	`READ MEMORY STORE` on the store
List	`GET /api/2.1/unity-catalog/memory-stores/{full_name}/entries`	`READ MEMORY STORE` on the store
Update	`PATCH /api/2.1/unity-catalog/memory-stores/{full_name}/entries`	`WRITE MEMORY STORE` on the store
Delete	`DELETE /api/2.1/unity-catalog/memory-stores/{full_name}/entries`	`WRITE MEMORY STORE` on the store
Search	`POST /api/2.1/unity-catalog/memory-stores/{full_name}/entries:search`	`READ MEMORY STORE` on the store

Create a memory entry

Creates a new memory entry in a memory store.

Endpoint: POST /api/2.1/unity-catalog/memory-stores/{full_name}/entries?scope=<scope>
Required privilege: WRITE MEMORY STORE on the store

scope is a query parameter; the request body is the entry itself.

Bash
curl -X POST \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory/entries?scope=user-42" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/memories/preferences.md",
    "contents": "The user prefers responses in English and uses formal tone.",
    "description": "User language and tone preferences"
  }'

Request fields:

Field	In	Type	Required	Description
`scope`	query	`string`	Yes	Partition the entry belongs to, assigned by the caller (for example, an end-user ID).
`path`	body	`string`	Yes	Soft path identifying the entry within the scope. Must start with `/memories/`. Immutable.
`contents`	body	`string`	No	Free-form memory text content.
`description`	body	`string`	No	One-line summary of the memory entry. Serves as an index hook in list responses.

Get a memory entry

Retrieves a single memory entry by scope and path.

Endpoint: GET /api/2.1/unity-catalog/memory-stores/{full_name}/entries:get
Required privilege: READ MEMORY STORE on the store

Bash
curl -X GET \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory/entries:get?scope=user-42&path=/memories/preferences.md" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

List memory entries

Lists memory entries in a scope.

Endpoint: GET /api/2.1/unity-catalog/memory-stores/{full_name}/entries
Required privilege: READ MEMORY STORE on the store

Bash
curl -X GET \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory/entries?scope=user-42" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Query parameters:

Parameter	Type	Required	Description
`scope`	`string`	Yes	Scope (partition) to list entries from.
`path_prefix`	`string`	No	Return only entries whose path starts with this prefix.
`page_size`	`integer`	No	Maximum entries per page. The server caps the page size.
`page_token`	`string`	No	Pagination token from a previous response.

List responses omit contents (metadata only) and include a next_page_token when more pages remain.

Update a memory entry

Applies a single edit operation to an existing entry's contents, identified by scope and path. Provide exactly one of str_replace, insert, or replace_all. description is editable: set it to replace the entry's description, or omit it to leave the description unchanged.

Endpoint: PATCH /api/2.1/unity-catalog/memory-stores/{full_name}/entries
Required privilege: WRITE MEMORY STORE on the store

Bash
curl -X PATCH \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory/entries" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "user-42",
    "path": "/memories/preferences.md",
    "replace_all": { "contents": "The user prefers responses in Spanish and uses casual tone." }
  }'

Edit operations (set exactly one):

Operation	Fields	Behavior
`replace_all`	`contents`	Overwrite the entry's full contents.
`str_replace`	`old_str`, `new_str`	Replace the single occurrence of `old_str` with `new_str` (must match exactly once).
`insert`	`insert_line`, `insert_text`	Insert `insert_text`; `insert_line` 0 = top, omitted = append to the end.

Delete a memory entry

Deletes a memory entry, identified by scope and path.

Endpoint: DELETE /api/2.1/unity-catalog/memory-stores/{full_name}/entries
Required privilege: WRITE MEMORY STORE on the store

Bash
curl -X DELETE \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory/entries?scope=user-42&path=/memories/preferences.md" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Search memory entries

Searches memory entries by keyword across path, content, and description fields.

Endpoint: POST /api/2.1/unity-catalog/memory-stores/{full_name}/entries:search
Required privilege: READ MEMORY STORE on the store

Bash
curl -X POST \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory/entries:search" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "user-42",
    "query": "language preferences"
  }'

Request fields: scope (required), query (required), path_prefix (optional), top_k (optional; defaults to 10, max 50).

Memory entry response fields

Field	Type	Description
`path`	`string`	Soft path of the entry within its scope.
`contents`	`string`	Memory text. Omitted in List responses.
`description`	`string`	One-line summary.
`scope`	`string`	Scope (partition) the entry belongs to.
`memory_store_name`	`string`	Three-part name of the parent memory store.
`has_contents`	`boolean`	Whether the entry has non-empty `contents` (useful in List).
`create_time`	`string`	Creation timestamp (RFC 3339).
`update_time`	`string`	Last update timestamp (RFC 3339).

Conversation APIs

A conversation stores OpenAI-compatible conversation state — messages, tool calls, and other items — in a memory store under a single scope. With a conversation, an agent persists and reloads session state server-side. You create each conversation against a memory store (three-part name) and a scope, and conversation operations require the same privileges as the underlying memory store.

Operation	Endpoint	Required privilege
Create	`POST /api/2.1/unity-catalog/conversations`	`WRITE MEMORY STORE` on the store
Get	`GET /api/2.1/unity-catalog/conversations/{conversation_id}`	`READ MEMORY STORE` on the store
Update	`POST /api/2.1/unity-catalog/conversations/{conversation_id}`	`WRITE MEMORY STORE` on the store
Delete	`DELETE /api/2.1/unity-catalog/conversations/{conversation_id}`	`WRITE MEMORY STORE` on the store

Create a conversation

Creates a conversation bound to a memory store and scope.

Endpoint: POST /api/2.1/unity-catalog/conversations
Required privilege: WRITE MEMORY STORE on the store

Bash
curl -X POST "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/conversations" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "memory_store": { "name": "main.default.support_agent_memory" },
    "scope": { "kind": "user", "value": "user-123" },
    "metadata": { "source": "support-chat" }
  }'

Request fields:

Field	Type	Required	Description
`memory_store`	`object`	Yes	Memory store backing the conversation.
`memory_store.name`	`string`	Yes	Three-part fully qualified name of the memory store: `catalog.schema.memory_store`.
`scope`	`object`	Yes	Scope the conversation is pinned to.
`scope.kind`	`string`	Yes	Scope kind, for example `user` or `user_defined`.
`scope.value`	`string`	Yes	Kind-specific scope value, for example an end-user ID.
`metadata`	`object`	No	Caller-controlled key-value metadata. Up to 16 keys; keys up to 64 characters, values up to 512 characters.
`items`	`array`	No	Initial OpenAI conversation items to seed the conversation (up to 20). Items without a `type` are stored as message items.

Get a conversation

Retrieves a conversation by its ID.

Endpoint: GET /api/2.1/unity-catalog/conversations/{conversation_id}
Required privilege: READ MEMORY STORE on the store

Bash
curl -X GET \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/conversations/${CONVERSATION_ID}" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Update a conversation

Updates a conversation's metadata.

Endpoint: POST /api/2.1/unity-catalog/conversations/{conversation_id}
Required privilege: WRITE MEMORY STORE on the store

Bash
curl -X POST \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/conversations/${CONVERSATION_ID}" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "source": "support-chat", "resolved": "true" } }'

Delete a conversation

Deletes a conversation and its items.

Endpoint: DELETE /api/2.1/unity-catalog/conversations/{conversation_id}
Required privilege: WRITE MEMORY STORE on the store

Bash
curl -X DELETE \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/conversations/${CONVERSATION_ID}" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Conversation response fields

Field	Type	Description
`id`	`string`	Server-assigned conversation ID.
`object`	`string`	Always `conversation`.
`created_at`	`integer`	Creation time in Unix epoch seconds.
`metadata`	`object`	Caller-supplied key-value metadata.

Conversation item APIs

Items are the individual messages and tool calls within a conversation. They follow the OpenAI conversation items shape and use OpenAI-compatible pagination (after, limit, has_more).

Operation	Endpoint	Required privilege
Create items	`POST /api/2.1/unity-catalog/conversations/{conversation_id}/items`	`WRITE MEMORY STORE` on the store
Get item	`GET /api/2.1/unity-catalog/conversations/{conversation_id}/items/{item_id}`	`READ MEMORY STORE` on the store
List items	`GET /api/2.1/unity-catalog/conversations/{conversation_id}/items`	`READ MEMORY STORE` on the store
Delete item	`DELETE /api/2.1/unity-catalog/conversations/{conversation_id}/items/{item_id}`	`WRITE MEMORY STORE` on the store

Prerequisites​

Memory store APIs​

Create a memory store​

Get a memory store​

List memory stores​

Update a memory store​

Delete a memory store​

Memory store response fields​

Memory entry APIs​

Create a memory entry​

Get a memory entry​

List memory entries​

Update a memory entry​

Delete a memory entry​

Search memory entries​

Memory entry response fields​

Conversation APIs​

Create a conversation​

Get a conversation​

Update a conversation​

Delete a conversation​

Conversation response fields​

Conversation item APIs​

Prerequisites

Memory store APIs

Create a memory store

Get a memory store

List memory stores

Update a memory store

Delete a memory store

Memory store response fields

Memory entry APIs

Create a memory entry

Get a memory entry

List memory entries

Update a memory entry

Delete a memory entry

Search memory entries

Memory entry response fields

Conversation APIs

Create a conversation

Get a conversation

Update a conversation

Delete a conversation

Conversation response fields

Conversation item APIs