Manage permissions for agent memory and session stores

Beta

This feature is in Beta. To use it, a workspace admin must turn on Agent Memory Sessions from the Previews page. See Manage Databricks previews.

Agent memory stores and session stores use the same store-level permission model. A permission applies to the contents of the store: every memory entry in a memory store, or every session and session item in a session store.

You can grant access to a Databricks user or service principal. Identify a user by email and a service principal by its application (client) ID. Store permissions don't support groups.

Requirements

• An existing memory store or session store.
• For the Agent Bricks CLI or AgentKit SDK examples, Python 3.10 or above and databricks-agentbricks 0.8.0 or above.

Store-level access model

The store is the security boundary. Fields such as actor_id, session_id, path, and metadata organize and filter data, but they don't restrict access. A principal with store access can access data for every actor in the store. To isolate data between tenants or users, create a separate store for each security boundary.

Store permissions have the following levels:

Permission	Read store data	Write store data
READ	Yes	No
WRITE	Yes	Yes. WRITE includes READ.
No access	No	No. You can't grant this state. To remove a principal's explicit access, use the Revoke operation. The Get operation reports this state as PERMISSION_LEVEL_UNSPECIFIED.

Permission	Read store data	Write store data
READ	Yes	No
WRITE	Yes	Yes. WRITE includes READ.
No access	No	No. You can't grant this state. To remove a principal's explicit access, use the Revoke operation. The Get operation reports this state as PERMISSION_LEVEL_UNSPECIFIED.

Only the store creator and workspace admins can manage permissions:

• The store creator has implicit WRITE access and can grant, list, and revoke permissions. You can't revoke the creator's ownership.
• A workspace admin can grant, list, and revoke permissions on any store in the workspace. Being a workspace admin does not by itself grant data access. An admin without existing data access must grant themselves READ or WRITE to use the store.
• A user or service principal with READ or WRITE can use the store but can't manage its permissions.

Inherited access comes from membership in a Postgres role in the backing Lakebase project, such as databricks_superuser. Store permission operations don't change those role memberships. See Manage permissions for Postgres roles.

Permission operations

Store permissions support four operations:

Operation	Behavior
Grant	Grants READ or WRITE to one user or service principal. The operation is idempotent. Granting READ to a principal that has WRITE does not downgrade the existing grant.
Get	Any authenticated caller can run Get. It returns only the caller's effective permission, including implicit creator access and inherited access. It returns PERMISSION_LEVEL_UNSPECIFIED when the caller has no access.
List	Returns explicit grants to users and service principals. It excludes the creator's implicit access, workspace-admin management authority, and inherited access. An empty result does not prove that no principal can access the store.
Revoke	Removes both explicit READ and WRITE grants from one principal. The operation is idempotent. It does not remove ownership or inherited access.

Operation	Behavior
Grant	Grants READ or WRITE to one user or service principal. The operation is idempotent. Granting READ to a principal that has WRITE does not downgrade the existing grant.
Get	Any authenticated caller can run Get. It returns only the caller's effective permission, including implicit creator access and inherited access. It returns PERMISSION_LEVEL_UNSPECIFIED when the caller has no access.
List	Returns explicit grants to users and service principals. It excludes the creator's implicit access, workspace-admin management authority, and inherited access. An empty result does not prove that no principal can access the store.
Revoke	Removes both explicit READ and WRITE grants from one principal. The operation is idempotent. It does not remove ownership or inherited access.

The List REST API uses a default page size of 100 grants and supports up to 1,000 grants per page. The AgentKit SDK follows all pages automatically. With the Agent Bricks CLI, use --all to return every page.

To downgrade a principal from WRITE to READ, revoke the existing grant and then grant READ. These operations aren't atomic, so the principal has no explicit access between the two calls.

Manage store permissions

The following examples manage permissions on a memory store. For a session store, use sessions stores instead of memory stores in the Agent Bricks CLI, client.session_stores.get("<store-name>") in the AgentKit SDK, or session-stores/<store-name> in the REST API path.

Agent Bricks

The permission commands accept the same store identifiers as the other store commands. Memory stores accept a store ID, resource name, or unambiguous display name. Session stores accept a store name or resource name.

To grant a user read access, run the following:

Bash

agentbricks memory stores permissions grant <store-id> \
  --user teammate@example.com --permission READ

To grant a service principal write access, run the following. Pass the service principal's application ID:

Bash

agentbricks memory stores permissions grant <store-id> \
  --service-principal <application-id> --permission WRITE

To get your own effective permission, run the following:

Bash

agentbricks memory stores permissions get <store-id>

To list all explicit grants, run the following as the store creator or a workspace admin:

Bash

agentbricks memory stores permissions list <store-id> --all

To revoke a user's explicit access, run the following. The --yes option skips the confirmation prompt:

Bash

agentbricks memory stores permissions revoke <store-id> \
  --user teammate@example.com --yes

AgentKit SDK

The permission methods are available on both MemoryStore and SessionStore objects. The following example passes the permission level and principal type explicitly:

Python

from databricks.sdk import WorkspaceClient
from databricks_agentkit import AgentKitClient

client = AgentKitClient(WorkspaceClient())
store = client.memory_stores.get("<store-id>")

# Grant a user read access.
store.grant_permission(
    "teammate@example.com",
    principal_type="USER",
    permission="READ",
)

# Return the authenticated caller's effective permission.
permission = store.get_permission()
print(permission.principal.name, permission.permission)

# List every explicit grant.
for grant in store.list_permissions(page_size=100):
    print(grant.principal.name, grant.principal.principal_type, grant.permission)

# Remove the user's explicit READ and WRITE grants.
store.revoke_permission("teammate@example.com", principal_type="USER")

grant_permission() and revoke_permission() use SERVICE_PRINCIPAL as the default principal type. grant_permission() uses WRITE as the default permission. Pass both arguments explicitly when you grant user access or read-only access.

REST API

The permission endpoints are under /api/2.0/agents/memory-stores/<store-id>/permissions. The request body identifies a user with USER and a service principal with SERVICE_PRINCIPAL.

Set DATABRICKS_HOST to your workspace URL, including https://, and DATABRICKS_TOKEN to your access token.

To grant a user read access, call the Grant operation:

Bash

curl -X POST "${DATABRICKS_HOST}/api/2.0/agents/memory-stores/<store-id>/permissions:grant" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "principal": {"principal_type": "USER", "name": "teammate@example.com"},
    "permission": "READ"
  }'

To get the authenticated caller's effective permission, call the Get operation:

Bash

curl "${DATABRICKS_HOST}/api/2.0/agents/memory-stores/<store-id>/permissions/self" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

To list explicit grants, call the List operation as the store creator or a workspace admin:

Bash

curl "${DATABRICKS_HOST}/api/2.0/agents/memory-stores/<store-id>/permissions?page_size=100" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

To revoke the user's explicit access, call the Revoke operation:

Bash

curl -X POST "${DATABRICKS_HOST}/api/2.0/agents/memory-stores/<store-id>/permissions:revoke" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "principal": {"principal_type": "USER", "name": "teammate@example.com"}
  }'

The Grant and Revoke operations don't return a permission object. To verify a change, run List as the store creator or a workspace admin. To check effective access, authenticate as the affected principal and run Get.

Permissions managed by agent deployment

When an agent project declares a memory or session store, agentbricks deploy grants the deployed app's service principal access to that store. A later deployment can restore access that you revoked manually.

Unbinding a store removes the binding from the agent project. It does not revoke access that was already granted to the app's service principal. Use the Revoke operation to remove that access.

Additional resources

• • Agent memory
  • Give agents long-term memory that persists across separate conversations.
• • Agent sessions
  • Store an agent's conversation history so it can resume an interaction across turns.