Memory API reference (legacy)

Legacy

This page is the REST API reference for the legacy managed agent memory, which will be turned down soon. Don't build new agents on it. For long-term agent memory, use Managed agent memory.

This page covers the endpoints, request fields, and response fields for the legacy 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

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.

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.

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.

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

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.

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.

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.

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

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

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.

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.

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

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