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 and memory records in Oracle Database and, when LLM-backed features are enabled, send content to configured model endpoints for 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 thread summarization and automatic memory extraction. When these features are enabled, the SDK may send recent messages, thread summaries, retrieved memories, or search text to the configured LLM or embedding endpoint.

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.
• Choose asynchronous extraction only when delayed derived writes are acceptable: In background mode, raw message writes can complete before derived memories, summaries, or related runtime state are written. If a workflow requires review or a tighter commit boundary before model-derived state becomes durable, use inline extraction or disable automatic extraction for that workflow.
• 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.
• Choose 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 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 and metadata, a workflow may also persist extracted memories, summaries, or embeddings.
• Treat write-capable memory paths as trusted: Database credentials and backend 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.
• Choose 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: delete_thread(), delete_user(cascade=True), and delete_agent(cascade=True) wait only for earlier accepted background extraction already known to that client when the wait starts. They are not a global concurrency barrier across other handles, components, or processes, and concurrent writes during deletion are unsupported. When a retention or shutdown boundary requires already-accepted background extraction from the current client to finish first, call wait_for_memory_extraction() before process shutdown or related administrative operations.
• 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. Choose 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.

Considerations regarding application integration and caller trust

Oracle AI Agent Memory is meant to be called by the integrating application or other trusted backend 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 choose 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 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 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 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.
• 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 Database rejects the statement.
• Create encrypted database connections and pools: Production code should pass a TLS-enabled Oracle 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.
• Monitor outbound traffic and provider usage for unexpected destinations, unusual request volume, or anomalous token consumption.
• Choose 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.