Deep Data Security

Oracle Agent Memory integrates with Oracle Deep Data Security (Deep Sec) to enforce end-user authorization inside Oracle AI Database. Deep Sec is a security feature: its data roles, data grants, and end-user security contexts determine which managed memory rows a request can read or modify.

Important: Treat the APIs on this page as security-administration and request-security interfaces. Use separate database identities for policy administration, managed-schema ownership, and runtime connection pooling. The runtime pool account should not have direct privileges that provide fallback access to protected Agent Memory tables.

Oracle’s Deep Data Security overview describes the database authorization model. For a complete OCI IAM deployment, see Enforce end-user memory isolation with Deep Data Security.

Security model

The Agent Memory integration supports two policies:

Policy Effective access
UserOwnRowsDeepDataSecurityPolicy Read and write user-scoped Agent Memory rows only when their owner matches ORA_END_USER_CONTEXT.username. Memory-link reads require both endpoint memories to be readable under the assigned policies; link writes require both endpoint memories to belong to that user.
GlobalMemoriesDeepDataSecurityPolicy Read unscoped memory rows whose user_id is NULL. This policy does not grant writes or access to another user’s scoped memories. It exposes a memory link when both endpoint memories are readable under the active policies. With only this policy, both endpoints must be global memories; when combined with the own-row policy, links between an owned memory and a global memory are also visible.

Policy objects are opaque selections for the administration APIs. Their managed-table, data-role, data-grant, and SQL implementations remain private so Oracle Agent Memory can evolve its database schema safely. Custom policy subclasses are not supported; use one of the two policy classes above.

Policies are scoped to the combination of owner_schema and memory_store_id. Creating or assigning a policy for one store does not assign it to another store, including a store with the same ID in a different owner schema.

The UserOwnRowsDeepDataSecurityPolicy policy also limits writes by column. End users can set identity and ownership columns when inserting an owned row, but cannot change those columns later. The policy grants the following write surface:

Column-level write permissions for UserOwnRowsDeepDataSecurityPolicy

Managed table Insertable columns Updatable columns
Thread record_id, user_id, agent_id, metadata, runtime_config, runtime_state metadata, runtime_config, runtime_state
Thread summary record_id, thread_id, user_id, agent_id, space_id, content, metadata, status content, metadata, status
Message record_id, thread_id, user_id, agent_id, message_role, content, timestamp, metadata, expires_at, status content, timestamp, metadata, expires_at
Document record_id, message_id, thread_id, user_id, agent_id, space_id, document_type, description, blob, timestamp, metadata, document_metadata, expires_at, status description, blob, timestamp, metadata, document_metadata, expires_at
Memory record_id, thread_id, user_id, agent_id, memory_type, content, timestamp, metadata, expires_at, status content, timestamp, metadata, expires_at, status
Memory link relation_id, source_memory_id, source_memory_user_id, target_memory_id, target_memory_user_id, relation_type, opposite_relation_type, timestamp, metadata relation_type, opposite_relation_type, timestamp, metadata
User actor profile actor_id, actor_type, information, metadata, status information, metadata
Record chunks source_id, source_record_type, source_emb_column, chunk_seq, chunk_text, thread_id, user_id, agent_id, status, and embedding when the store persists vectors status

SELECT and DELETE remain row-scoped. Generated, creation-time, and reserved columns such as chunk_id, created_at, and order_seq are not insertable or updatable by end users unless explicitly listed above. The database also checks the row predicate for inserts, so listing user_id as insertable does not permit an end user to create a row owned by another identity. When an UPDATE targets a non-updatable column on a table that grants UPDATE on other columns, Deep Sec can silently leave the row unchanged rather than raise an error. Record chunks allow only status updates. The SDK replaces changes to chunk identity, text, and embedding values with delete and insert operations. Applications should use the SDK’s supported mutation methods and must not treat direct SQL execution alone as proof that a protected value changed.

Use the administration APIs in this order:

  1. Create the managed Agent Memory store as its schema owner.
  2. Call add_deep_data_security_policies() as the security administrator.
  3. Call grant_agent_memory_policies() for each authorized OCI IAM group or local Deep Sec end user.
  4. At runtime, wrap every Agent Memory operation in OracleMemoryEndUserSecurityContext.
  5. Revoke assignments before removing policies that are no longer needed.

If runtime operations use OracleDBEmbedder with the default provider="database" and a model stored in Oracle AI Database, typically an ONNX model, the policy grants above authorize Agent Memory tables only. The IAM group’s mapped data role must also have access to the database-resident model. Configure that access as described in Use an in-database embedding model with Deep Sec before serving requests.

OracleDBEmbedder can also use a remote provider through DBMS_VECTOR_CHAIN.UTL_TO_EMBEDDING. That configuration does not use a database-resident model and does not require SELECT ON MINING MODEL. Configure the remote provider’s Oracle credential and network access separately. The Agent Memory operation must still run inside OracleMemoryEndUserSecurityContext.

The administration calls commit their database changes before returning. For the underlying role and grant concepts, see Oracle’s Data Access Control Configuration.

Context-use checks

The SDK rejects unsafe combinations before protected application work runs:

These checks diagnose an incorrect SDK execution path. Oracle AI Database data grants remain the authorization boundary and continue to determine which rows and columns an authenticated end user can access.

Policies

class oracleagentmemory.core.deepsec.DeepDataSecurityPolicy

Bases: object

Identify a supported Oracle Agent Memory Deep Data Security policy.

Policy objects are opaque selections passed to the Deep Data Security administration functions. Instantiate UserOwnRowsDeepDataSecurityPolicy or GlobalMemoriesDeepDataSecurityPolicy. Policy implementation details, including managed tables, data roles, data grants, and SQL, remain private to Oracle Agent Memory and may change between releases.

This class is not a custom-policy extension point. Subclasses other than the two policy classes supplied by Oracle Agent Memory are rejected by the administration functions.

Examples

Create the policy set for end-user rows and unscoped global memories:

policies = [
    UserOwnRowsDeepDataSecurityPolicy(),
    GlobalMemoriesDeepDataSecurityPolicy(),
]

class oracleagentmemory.core.deepsec.UserOwnRowsDeepDataSecurityPolicy

Bases: DeepDataSecurityPolicy

Grant access to rows owned by the authenticated end user.

This policy grants row-scoped SELECT, column-scoped INSERT and UPDATE, and row-scoped DELETE on user-owned data. Ownership, record-type, generated, creation-time, and reserved columns cannot be changed after insertion. Record chunks can be inserted and deleted but cannot be updated because the SDK replaces them as complete rows. The policy also grants the registry read needed to initialize a runtime store. Memory-link SELECT follows the shared endpoint-visibility rule, while link INSERT, UPDATE, and DELETE require both endpoint memories to belong to the end user.

Examples

policy = UserOwnRowsDeepDataSecurityPolicy()

class oracleagentmemory.core.deepsec.GlobalMemoriesDeepDataSecurityPolicy

Bases: DeepDataSecurityPolicy

Grant read access to global memories and links between visible memories.

This policy grants SELECT on memory rows whose user_id is NULL and grants the registry read needed to initialize a runtime store. Its memory-link read grant exposes a link when both endpoint memories are readable by the end user under the assigned Deep Data Security policies. With only this policy, both endpoints must therefore be global memories; combined with the own-row policy, a link between an owned memory and a global memory is also visible. It does not permit writes or access to another user’s scoped memories.

Examples

policy = GlobalMemoriesDeepDataSecurityPolicy()

Principals

An assignment targets either an OCI IAM group carried in the access token’s group custom claim or a local Deep Sec end user. OCI IAM group information must be configured as a custom claim before Oracle AI Database can map it to an external data role. See Configure Custom Claims for Group Information in OCI IAM.

class oracleagentmemory.core.deepsec.Principal

Bases: object

Base type identifying who receives Agent Memory policy assignments.

Principals are the security identities targeted by grant_agent_memory_policies() or revoke_agent_memory_policies(). The principal identifies the grantee whose Deep Data Security data roles or data grants control access to a specific Agent Memory store. Current principal types supported are OCI IAM groups and local DB end users.

Use OciGroupPrincipal for an OCI IAM group or LocalEndUserPrincipal for a database-managed Deep Data Security end user. Passing a direct Principal instance to an administration function is not supported.

class oracleagentmemory.core.deepsec.OciGroupPrincipal

Bases: Principal

Identify an OCI IAM group that receives Agent Memory policies.

class oracleagentmemory.core.deepsec.LocalEndUserPrincipal

Bases: Principal

Identify a local Deep Data Security end user receiving policies.

Administration

Run these functions through a dedicated security-administration connection. For cross-schema Agent Memory tables, that account needs the applicable Deep Sec administration privileges, including CREATE ANY DATA GRANT, DROP ANY DATA GRANT, and ADMINISTER ANY DATA GRANT, plus authority to create and drop data roles. Do not give these privileges to the runtime pool account.

oracleagentmemory.core.deepsec.add_deep_data_security_policies

Create the data roles and data grants for Agent Memory policies.

The policies are scoped to one owner_schema and memory_store_id. Adding them enables mandatory Deep Data Security enforcement on their protected managed tables. Re-adding a policy replaces its Agent Memory-managed data role and grants with the current definition. Repeated calls are idempotent. If Oracle commits part of the policy DDL before an interruption, retrying the same call repairs the managed definitions.

This function commits the connection before returning. Use a dedicated security-administration connection rather than a schema-owner or runtime application connection.

Examples

Add own-row and global-memory access policies:

add_deep_data_security_policies(
    connection,
    owner_schema="MY_OWNER_SCHEMA",
    memory_store_id="MEMORY",
    policies=[
        UserOwnRowsDeepDataSecurityPolicy(),
        GlobalMemoriesDeepDataSecurityPolicy(),
    ],
)

oracleagentmemory.core.deepsec.remove_deep_data_security_policies

Remove Agent Memory Deep Data Security policies.

Dropping a policy role also removes that role from its data grants and local end-user assignments. OCI IAM assignments created as external data grants should first be removed with revoke_agent_memory_policies(). Mandatory data-grant enforcement is disabled for a managed table only when no data grants remain on that table.

This function commits the connection before returning.

Examples

Remove the own-row policy:

remove_deep_data_security_policies(
    connection,
    owner_schema="MY_OWNER_SCHEMA",
    memory_store_id="MEMORY",
    policies=[UserOwnRowsDeepDataSecurityPolicy()],
)

oracleagentmemory.core.deepsec.list_deep_data_security_policies

List Agent Memory policies currently created in Oracle AI Database.

Examples

Inspect configured policy types:

policies = list_deep_data_security_policies(
    connection,
    owner_schema="MY_OWNER_SCHEMA",
    memory_store_id="MEMORY",
)
[type(policy).__name__ for policy in policies]
['UserOwnRowsDeepDataSecurityPolicy']

oracleagentmemory.core.deepsec.grant_agent_memory_policies

Grant Agent Memory policies to OCI IAM groups or local end users.

OCI IAM groups are represented by externally mapped data roles. Data grants for each policy are attached directly to that mapped role because Oracle AI Database does not permit externally mapped data roles to receive locally managed data roles.

Create each policy for the target store with add_deep_data_security_policies() before assigning it. This function commits the connection before returning. Repeated calls are idempotent. If Oracle commits part of an OCI IAM assignment before an interruption, retrying the same call recreates the missing managed data grants.

Examples

Grant own-row access to an OCI IAM group:

grant_agent_memory_policies(
    connection,
    memory_store_id="MEMORY",
    owner_schema="MY_OWNER_SCHEMA",
    principals=[OciGroupPrincipal("ORACLEAGENTMEMORY_USERS")],
    policies=[UserOwnRowsDeepDataSecurityPolicy()],
)

oracleagentmemory.core.deepsec.revoke_agent_memory_policies

Revoke Agent Memory policies from OCI IAM groups or local end users.

The principal itself is preserved. In particular, an OCI IAM group’s externally mapped data role remains available for assignments from this or another Agent Memory store.

Revocation changes database policy state and commits before returning, so subsequent protected database statements no longer receive the revoked policy. This is distinct from removing a user from an OCI IAM group: an already-issued access token retains its embedded group claim until that token expires.

Examples

Revoke own-row access from an OCI IAM group:

revoke_agent_memory_policies(
    connection,
    memory_store_id="MEMORY",
    owner_schema="MY_OWNER_SCHEMA",
    principals=[OciGroupPrincipal("ORACLEAGENTMEMORY_USERS")],
    policies=[UserOwnRowsDeepDataSecurityPolicy()],
)

oracleagentmemory.core.deepsec.list_agent_memory_granted_policies

List principals and Agent Memory policies assigned to each principal.

Examples

List policy assignments:

assignments = list_agent_memory_granted_policies(
    connection,
    memory_store_id="MEMORY",
    owner_schema="MY_OWNER_SCHEMA",
)
len(assignments) >= 0
True

Runtime security context

OracleMemoryEndUserSecurityContext scopes the python-oracledb security context to Agent Memory operations. The context carries the end-user token and database-access token; Oracle AI Database validates them and derives active data roles from their claims. The SDK attaches the context to each acquired physical connection and clears it before returning that connection to the pool.

See Oracle’s End-User Security Context for the security model and How the Database Server Manages an End-User Security Context for validation, role resolution, connection reuse, and context cleanup.

class oracleagentmemory.core.deepsec.OracleMemoryEndUserSecurityContext

Bases: object

Apply an Oracle end-user security context to Agent Memory operations.

Entering this context manager makes security_context available to Oracle-backed Agent Memory stores used in the current execution context. Each database operation applies the context after acquiring its physical connection, verifies that an end-user identity is active, and clears the context before releasing the connection. This behavior works with both direct connections and connection pools.

The scope propagates to awaited asynchronous Agent Memory calls. Caller tasks that outlive the with or async with block cannot use the expired scope. Background memory-extraction jobs accepted inside the block retain a private snapshot so they can complete after the block exits.

Use a fresh oracledb.EndUserSecurityContext when the end-user or database-access token changes. Oracle AI Database derives the enabled data roles from the claims in the supplied token; this manager does not refresh, revoke, or inspect OAuth tokens.

Notes

This class scopes Oracle Agent Memory operations. It does not modify an arbitrary connection used directly by application SQL outside the SDK. Nesting is supported, including nesting the same manager instance; each exit restores the context from its matching entry.

Examples

Apply an OAuth-derived context to synchronous Agent Memory operations:

import oracledb
from oracleagentmemory.core.deepsec import (
    OracleMemoryEndUserSecurityContext,
)
user_context = oracledb.create_end_user_security_context(
    end_user_identity=end_user_token,
    database_access_token=database_access_token,
)
with OracleMemoryEndUserSecurityContext(user_context):
    memory_store.add(
        ["Remember this preference."],
        record_type="memory",
    )

The same manager supports asynchronous calls:

async with OracleMemoryEndUserSecurityContext(user_context):
    await memory_store.add_async(
        ["Remember this preference."],
        record_type="memory",
    )

method __aenter__ (async)

Enter the scope for awaited Agent Memory operations.

method __aexit__ (async)

Exit the asynchronous scope without suppressing block exceptions.

method __enter__

Enter the scope and return this context manager.

Agent Memory operations started in the current execution context use this manager’s end-user security context until the matching exit.

method __exit__

Exit the scope and prevent inherited caller tasks from reusing it.

Any exception from the managed block is propagated unchanged.

oracleagentmemory.core.deepsec.get_end_user_username

Return the end-user username attached to an Oracle DB connection.

Deep Data Security evaluates data grants using the end-user security context attached to a database connection. This helper reads the username attribute from that context. It does not return the database account used to establish the physical connection.

Examples

Check whether a connection has an attached end-user identity:

get_end_user_username(conn) is None
True

Auditing

Deep Sec uses Oracle AI Database Unified Auditing. A database administrator can create unified audit policies for Deep Sec configuration operations such as creating or dropping data roles and data grants, granting or revoking data roles, and creating or dropping end users and end-user contexts. Audit records are available through UNIFIED_AUDIT_TRAIL and can include the end-user identity and security-context identifier for activity performed under an end-user security context.

The CREATE END USER SECURITY CONTEXT action records security-context creation. Oracle notes that it can generate many records and is not included by ACTIONS ALL; specify it explicitly when that lifecycle event must be audited. Select audit actions and retention according to the deployment’s security and compliance requirements. SDK application logs are diagnostic and are not a replacement for the database audit trail.

See Audit Oracle Deep Data Security Operations and the official list of Deep Sec Auditable Actions.

Revocation time contract

Database policy revocation and OCI IAM group-membership removal have different effective times:

Administrative action Effective time
Call revoke_agent_memory_policies() The function removes the store-specific database assignment and commits before returning. Subsequent protected database statements no longer receive that policy. A statement already executing is not retroactively cancelled.
Remove a user from the grantee group in OCI IAM Newly issued access tokens reflect the updated membership. An access token already issued to the user still contains its group claim and can continue to authorize the corresponding Deep Sec data role until that token expires.

The effective upper bound for IAM-only revocation is therefore the remaining lifetime in the issued token’s exp claim. OCI IAM access-token lifetime is configurable; when no resource-application, user-session, or custom expiry is set, the documented default is 3600 seconds. Applications must stop reusing an expired token and obtain a new token whose claims reflect current membership.

For urgent revocation, first call revoke_agent_memory_policies() to remove the database assignment immediately for subsequent statements, then remove the user from the OCI IAM group. Re-grant the database policy only when the group as a whole should regain access. If only one member must be removed while the group remains authorized, rely on token expiry or use a deployment-specific shorter access-token lifetime and reauthentication policy.

See OCI IAM’s Managing Authorization Using the API and Token Expiry Table, along with the Deep Sec security-context lifecycle references above.