Security Considerations

Scope: This document covers security considerations related to Oracle AI Agent Memory Python SDK. It applies to applications using either the active-memory features of the SDK or the store layer only.

Why it matters: Oracle AI Agent Memory can persist thread content, images, and memory records in Oracle AI Database and, when LLM-backed features are enabled, send content to configured model endpoints for image-description generation, summarization, memory extraction, or embeddings. Secure deployment therefore depends on careful handling of application data, retrieval scope, database access, external model endpoints, and retention policies.

Considerations regarding LLM-backed memory processing

Oracle AI Agent Memory supports active-memory features such as image-description generation, thread summarization, and automatic memory extraction. When these features are enabled, the SDK may send image bytes, recent messages, thread summaries, retrieved memories, or search text to the configured LLM or embedding endpoint. See Use Images and Multimodal Messages for the image-description and extraction modes that determine when image bytes are sent to the configured LLM.

Important: Only send content to Oracle AI Agent Memory that is appropriate for the configured model endpoint and your deployment policies. If active-memory is enabled for data that appears to include secrets, credentials, or unnecessary sensitive data, minimize or redact that content before messages enter the memory pipeline. Treat extracted memories, summaries, context cards, and other model-derived text as untrusted output that must be reviewed and handled safely by the integrating application.

Warning: Model-derived text can become persistent memory state. When automatic extraction, summarization, or context-card features are enabled, a summary, extracted memory, or retrieved record may be inserted by the SDK into later prompts, such as memory-extraction, summarization, context-card, or agent prompts, before the application can review that specific intermediate value. Treat this as normal untrusted LLM data flow: review and validate the outputs your application consumes, and do not let memory-derived content authorize privileged actions or bypass policy.

Follow these recommendations when using active-memory features:

• Validate and minimize application data: Review which messages, metadata, and IDs your application sends into the SDK. Avoid passing more data than the memory workflow needs.
• Use trusted model endpoints: Configure LLM and embedding endpoints that meet your requirements for transport security, data residency, retention, and operational monitoring.
• Treat generated memory as application data and untrusted output: Extracted memories, summaries, and context cards are derived outputs. Review how your application uses them, especially before they influence privileged actions, external tool calls, or customer-visible decisions.
• Account for persistent prompt injection: Caller-provided, retrieved, or model-derived text stored in memory can be replayed into later summarization, extraction, context-card, or agent prompts. Prompt delimiters, escaping, and extraction instructions can help structure model input, but they are not a security boundary. Review extracted memories, summaries, context cards, and other persisted or prompt-bound intermediate text before relying on them. If your workflow requires review before model-derived text can influence future extraction or context construction, disable automatic extraction and use explicit memory writes or another application-controlled review gate.
• Sanitize or escape derived text for its destination: If extracted memories, summaries, context cards, or other model-derived text are rendered into HTML, Markdown, templates, logs, or other output surfaces, apply context-appropriate escaping or sanitization. Use the same care before reusing derived text in downstream prompts, tool inputs, commands, or other interpreter-like contexts.
• Select the right operating mode: If your application needs review before model-derived text can influence later extraction or context construction, consider using explicit memory writes, store-only integrations, or memory_extraction_config=MemoryExtractionConfig(extract_memories=False) for workflows that should not perform automatic extraction.

Considerations regarding persistence and data minimization

Oracle AI Agent Memory is designed to persist messages, memories, metadata, and embeddings in Oracle AI Database when the DB-backed store is used. This allows durable retrieval and cross-session memory, but it also means the application should plan what data is appropriate to retain.

The following guidance helps keep deployments aligned with secure data-handling practices:

• For store-only usage, persist only what is needed: Design your application so that only useful, business-appropriate content is written to the memory store.
• When active-memory features are enabled, plan for derived records: In addition to caller-provided content such as messages, images, and metadata, a workflow may also persist generated image descriptions, extracted memories, summaries, or embeddings.
• Treat write-capable memory paths as trusted: Database credentials and back-end code paths that can write messages, summaries, memories, metadata, embeddings, or thread runtime state can affect future prompts and retrieval results. Active-memory features intentionally persist model-derived state; if that is not appropriate for a workflow, disable automatic extraction or use a store-only/manual-write integration with narrower application controls.
• Select the right deletion scope for retention work: delete_message() removes the raw message record only. Derived memories or other downstream thread-scoped artifacts created from that message can remain searchable because extracted memories do not currently persist per-message provenance. When you need thread-scoped cleanup that also removes associated memories and managed retrieval data, use OracleAgentMemory.delete_thread().
• Plan around the delete and shutdown boundary for background work: Client and thread deletion methods wait up to 300 seconds for relevant background memory extraction and image-description generation already accepted by the same OracleAgentMemory instance before the wait starts. delete_thread(), delete_message(), and thread-level delete_memory() wait for their thread; client-level delete_memory() waits only when its stored target has a thread scope; and delete_user() and delete_agent() wait for known owned threads whether or not cascade cleanup is enabled. A timeout raises TimeoutError without performing the deletion. These waits and stale image-description checks are not global concurrency barriers across other client instances or processes, and concurrent writes during deletion are unsupported. Before another client or process updates or deletes an image whose description is being generated in the background, ensure wait_for_memory_extraction() has returned on the originating instance. Use the same wait before process shutdown or related administrative operations when all background work already accepted by the current client must finish first.
• Define retention and deletion policies up front: If your application offers deletion or retention commitments, make sure they cover raw messages, extracted memories, metadata, and other related records created by the workflow. Select per-record ttl_days values and the schema memory_retention_config based on the expected type of information in each record, why the application needs to retain it, and any applicable retention commitments. Use automatic expiration when records should be purged by age, and verify that the managed Oracle purge job is present in DB-backed deployments, especially when the schema setup user does not have scheduler-job privileges.
• Plan for purge-job database load: The managed Oracle purge job runs on a schedule and deletes expired rows from the SDK-managed tables in batches rather than as one large delete. Monitor its runtime, redo/undo generation, skipped-run history, and row volume in environments with high write rates or large expiration batches, and adjust retention settings or operational rollout plans if purge activity could overlap with latency-sensitive database workloads. The managed job sets a one-day schedule_limit so runs delayed too long can be skipped instead of starting arbitrarily late.
• Avoid relying on memory as a source of truth: Stored memories are intended to improve context and retrieval. Applications should continue to rely on authoritative systems for important decisions.

Considerations regarding retrieval scope and access control

Oracle AI Agent Memory uses caller-provided user_id, agent_id, and thread_id values to scope retrieval. This is a powerful filtering model, but it should not be the only control your application relies on when deciding how retrieved content is used or shown.

By default, thread-scoped retrieval uses exact matching for user_id and agent_id and a broader match for thread_id so relevant results can span past threads for the same user-agent pair. Top-level OracleAgentMemory.search() and search_async() calls also require explicit user scoping and exact user matching. They reject omitted user scope and exact_user_match=False so the public client API does not accidentally search across multiple users. Passing user_id=None is allowed only with exact user matching and targets only unscoped records.

Use the following practices when designing retrieval:

• Map application rules to memory scope: Ensure that the scopes your application passes to the SDK match your tenant, user, and data-sharing rules.
• Pass an explicit user scope on every client search: Derive the user_id from the authenticated request context rather than from request JSON or other caller-controlled input, and provide it on each top-level OracleAgentMemory.search() or search_async() call. Use user_id=None only for workflows intentionally restricted to unscoped records.
• Prefer the narrowest scope that satisfies the use case: Use exact matching and tighter filters for workflows that handle more sensitive data.
• Review cross-thread retrieval intentionally: Broader retrieval can improve continuity across sessions, but applications should enable it only where that behavior is appropriate.
• Treat search results as retrieved content, not final decisions: Returned memories may be relevant, but the application remains responsible for deciding whether and how they should be shown or acted on.
• Handle retrieved text safely at the integration boundary: Retrieved records can include caller-provided or model-derived text. If retrieved memories or other returned text are rendered into HTML, Markdown, templates, logs, or other output surfaces, apply context-appropriate escaping or sanitization before displaying it, transforming it, or passing it to downstream systems.

For database-enforced end-user authorization, Oracle Agent Memory also exposes an integration with Oracle Deep Data Security. This is a distinct security feature built on database data roles, data grants, and end-user security contexts. Review the Deep Data Security API and security reference before granting policies or using a shared runtime connection pool. That page also documents Unified Auditing and the different effective times for database policy revocation and OCI IAM group-membership changes.

Considerations regarding application integration and caller trust

Oracle AI Agent Memory is meant to be called by the integrating application or other trusted back-end code, not directly by end users. It is not an end-user-facing security boundary, and it does not perform end-user authentication or authorization on its own. The package trusts the caller to provide the correct user_id, agent_id, thread_id, and retrieval scope for each operation.

Important: The integrating application is responsible for authenticating the end user, authorizing access, and deriving the correct user_id and scope before it calls Oracle AI Agent Memory APIs. A caller-supplied user_id is a scoping value, not proof of identity.

Use the following practices when integrating the SDK into an agentic application:

• Treat user_id as security-sensitive application input: If the integrating application derives user_id from request JSON or other caller-controlled input instead of authenticated context, that can allow cross-user memory access. Derive user_id from your authenticated application context instead of letting end users select arbitrary values.
• Apply application authorization before every memory call: The integrating application must decide which user_id, agent_id, thread_id, and search scope values are valid for the current request and keep reads and writes inside the intended tenant and user boundary.
• Do not expose raw memory APIs to end users: Package APIs such as add_memory or search helpers should be wrapped in application logic that validates the caller, enforces policy, and controls what data can be written or returned.
• Keep user-ID discovery and enumeration privileged: If the package adds helpers for listing or enumerating user_id values, treat them as administrative capabilities only and never expose them to end users through the integrating application.
• Review scope overrides carefully: Any workflow that broadens thread scope, disables exact matching, or drops to lower-level store APIs should be restricted to trusted components and reviewed for cross-user or cross-tenant effects.

Considerations regarding logging and diagnostics

Oracle AI Agent Memory uses standard Python logging and does not configure application log handlers or log levels for the integrating application. Applications can enable the oracleagentmemory logger and route SDK logs through their existing logging configuration.

Use the following practices when consuming SDK logs:

• Keep production deployments at a non-DEBUG level: DEBUG logging is intended only for controlled development or support diagnostics and is not suitable for production log collection.
• Limit access to diagnostic logs: Store logs in protected sinks with appropriate access control, retention, and sharing policies. Review support bundles before sending logs outside the operating environment.
• Avoid adding sensitive context in application logging wrappers: Do not enrich SDK log records with prompts, memory contents, credentials, raw metadata, database row values, or caller-controlled identifiers.
• Treat log text as diagnostic output, not an audit interface: Log messages can help troubleshoot SDK behavior, but applications should use their own explicit audit events for security and compliance workflows.

Considerations regarding database access, schema management, and secrets

Oracle AI Agent Memory uses a caller-provided Oracle AI Database connection or pool. The package does not create or manage database credentials itself. It also does not create, negotiate, or upgrade database network encryption on behalf of the caller.

Important: Production code should pass a TLS-enabled Oracle AI Database connection or pool into Oracle AI Agent Memory. The SDK uses the caller-provided connection or pool as-is and does not upgrade a plaintext DSN. Do not use plaintext database connections across untrusted, shared, or external networks. When using python-oracledb, follow the official section Securely Encrypting Network Traffic to Oracle AI Database and configure TLS or another approved encrypted transport as part of connection or pool creation.

Important: Never embed API keys, passwords, or other secrets directly in application code, checked-in configuration, or exported artifacts. Always use secure injection mechanisms and follow the principle of least privilege for credential access.

The following deployment practices are recommended:

• Use database users with only the required privileges: Grant only what is needed for the selected deployment model and schema policy.
• Separate schema administration from application access: Use a privileged database user once to create or update the managed Agent Memory schema. Grant the application user only the required runtime privileges, then connect the application with SchemaPolicy.REQUIRE_EXISTING and schema_owner set to the schema-owning user. The application user can then read and write memory data without receiving schema-creation, upgrade, or recreation privileges; see the troubleshooting guide for the required grants.
• Use a separate database user for deletion workflows where practical: If your application needs to remove records, prefer a dedicated connection or pool for those paths and grant DELETE on the managed Oracle AI Agent Memory tables only to that database user. Keep the main runtime connection limited to the non-deletion privileges required for its normal operations so accidental or unwanted deletes have a narrower blast radius. If a caller invokes delete() through a connection that does not have DELETE permission, Oracle AI Database rejects the statement.
• Create encrypted database connections and pools: Production code should pass a TLS-enabled Oracle AI Database connection or pool into the SDK. Oracle AI Agent Memory uses the caller-provided connection or pool exactly as provided, so for python-oracledb prefer TLS-enabled connections such as protocol="tcps" or an equivalent TCPS DSN, configure the required wallet or CA material, and keep server certificate validation enabled.
• Keep the default schema policy unless you explicitly need DDL changes: SchemaPolicy.REQUIRE_EXISTING is the default and avoids creating, modifying, or dropping schema objects during normal application startup.
• Restrict destructive setup modes: SchemaPolicy.RECREATE is intended for setup, testing, or administrative workflows and should not be used in normal production paths.
• Rely on package-managed SQL paths, not dynamic SQL assembly in application code: In the managed DB paths, record values and search filters are sent with bind variables, and managed object names are derived from validated prefixes.
• Protect connection and provider credentials: Store database, LLM, and embedding credentials in a secrets manager such as OCI Vault, and rotate them regularly.
• Prefer validated TLS in both Thin and Thick mode: The official python-oracledb docs note that both Thin and Thick modes support TLS, and Thick mode can also use Oracle Native Network Encryption where that is your approved standard.
• Use secure transport to the database: Database network security, TLS configuration, and authentication method are determined by the caller-provided connection and should follow your organization’s standards.

Considerations regarding network communication and external endpoints

Oracle AI Agent Memory can communicate with external services when the deployment configures remote LLM or embedding providers. The SDK forwards prompts and request parameters through the configured client path, but the surrounding application and deployment remain responsible for securing these connections.

We recommend the following:

• Use HTTPS for model endpoints and prefer private or restricted network paths where available.
• Configure model-endpoint certificates explicitly: For an HTTPS OpenAI-compatible endpoint that uses a private CA, pass its trusted PEM certificate or bundle through ca_file on Llm or Embedder. For mutual TLS, pass the client certificate and private key through cert_file and key_file together, and protect the private key with appropriate filesystem permissions. Server certificate verification remains enabled; do not replace trusted CA material with an untrusted certificate.
• Control provider proxy environment settings intentionally: Provider requests honor HTTPX proxy and TLS-related environment variables by default. Pass proxy when a specific proxy must be used; an explicit proxy takes precedence over proxy environment variables. Set trust_env=False when the application must ignore those environment settings. An explicit proxy remains effective with trust_env=False.
• Monitor outbound traffic and provider usage for unexpected destinations, unusual request volume, or anomalous token consumption.
• Select providers that match your compliance and residency needs before enabling active-memory features on regulated or sensitive workflows.

Considerations regarding resource-exhaustion vectors

Memory workflows can increase database usage, embedding traffic, and LLM token consumption over time. This is true both for malicious over-use and for innocent implementation mistakes such as oversized messages or overly broad retrieval patterns.

Use these controls as part of your production hardening:

• Set practical prompt and message bounds: Configure values such as max_message_token_length and memory_extraction_token_limit to fit your workload and provider limits. max_message_token_length limits the prompt-time copy used by extraction workflows; stored messages remain unchanged.
• Bound retrieval sizes: Use reasonable max_results values and record-type filters for application searches.
• Apply infrastructure limits outside the SDK: Use database quotas, connection limits, network controls, endpoint timeouts, and rate limiting in the surrounding deployment.
• Monitor growth over time: Track stored message volume, durable memory growth, provider usage, and query latency so retention or tuning changes can be made before they affect reliability.

Recommended Oracle Deep Data Security deployment

Oracle Deep Data Security (Deep Sec) can enforce Agent Memory row and column constraints in the database, such as allowing end users to read and write only rows that contain their own user_id. The UserOwnRowsDeepDataSecurityPolicy policy also prevents end users from updating ownership and identity columns after insert; see Deep Data Security for the exact per-table permissions.

To use this security functionality to the fullest extent, we recommend to use a separate db user for each security responsibility, so that the application has no privileged fallback when an end-user context is absent.

We recommend the following account separation in production:

• Security administrator: Creates and manages data roles, data grants, application identities, and their mappings to IAM groups. This account is an administrative setup account and is not used for normal Agent Memory requests.
• Managed-schema owner: Creates and owns the Oracle Agent Memory tables and managed schema objects. This account has owner privileges on those tables, so a connection without an end-user security context can access all rows. Do not use it as the runtime application account. Restrict its use to schema setup, migrations, and controlled administrative operations. This user should have the privilege to create JOBs.
• App DB user: Connects at runtime and has only the privileges needed to establish a database session and attach an end-user security context, normally CREATE SESSION and CREATE END USER SECURITY CONTEXT. Do not grant this user ordinary SELECT, INSERT, UPDATE, or DELETE privileges on the managed tables. A request that reaches this account without a valid end-user context then fails closed instead of falling back to broader table privileges.

For every end-user request, authenticate the user outside the OAM sdk, acquire one application-pool connection, attach that user’s end-user security context, and perform the Agent Memory operation through that connection. Clear the context before releasing the connection to a pool. A context belongs to one physical database session; it must not be reused for another user. Oracle’s Deep Sec end-user security context lifecycle documentation describes the corresponding attachment, replacement, and release behavior.

Do not pass a general application pool directly to an Agent Memory instance unless the database driver is configured to attach the current request’s end-user context on every acquired connection. Otherwise, an SDK operation can borrow a session with no context or with the wrong request context. Instead, acquire and configure the connection in the application, then pass that context-bearing connection to the request-scoped Agent Memory component.

Background or deferred work that reads or writes user-owned records needs the same protection. Keep the authorized connection and its end-user context valid until the work completes, or arrange for the worker to acquire a fresh connection and attach the correct authenticated user’s context. Never run this work through the schema owner simply to bypass a missing end-user context.