Use Oracle Agent Memory with Oracle Autonomous AI Database

This guide shows how to connect oracleagentmemory to Oracle Autonomous Database (ADB).

In this guide, you will learn how to:

Prepare an ADB schema user for Oracle Agent Memory.
Connect with walletless TLS or with an mTLS wallet.
Initialize the managed memory schema and store and search a memory.

Hint: For package setup, see the Get Started with Agent Memory. To run Oracle Agent Memory against a containerized local database instead, follow Run Oracle AI Database locally.

Prerequisites

You need an available Oracle Autonomous AI Database that supports Oracle AI Vector Search (Oracle AI Database 23ai or later), an ADB administrator who can create a database user, and a Python environment with oracleagentmemory installed. If you do not yet have a database, follow Oracle’s Autonomous AI Database provisioning guide.

Oracle Agent Memory uses the connection or pool supplied by your application; it does not configure database transport security itself. ADB supports two secure connection choices:

TLS without a wallet is suitable for most new applications. It uses database credentials and encrypts the connection. Before using it, configure an IP allowlist (ACL) or a private endpoint so the application can reach the database. TLS protects the connection; the ACL or private endpoint controls which networks can reach the database.
Mutual TLS (mTLS) with a wallet is suitable when ADB requires mTLS or when your organization requires client-certificate authentication.

Use separate database users in production

Use two ADB database users in a production deployment:

The schema owner creates, upgrades, and owns the Oracle Agent Memory tables and indexes.
The application user connects when the application reads and writes memories. Give this user only the permissions it needs on the schema owner’s objects.

Do not use the schema owner’s credentials to run the application. Use them only when setting up or upgrading the managed schema. This guide first creates the schema owner. After setup, configure the application user with SchemaPolicy.REQUIRE_EXISTING. The troubleshooting guide lists the object grants needed by an application user.

Run each schema creation or upgrade as a single maintenance operation before starting application instances that write to the managed tables. Use one schema-owner connection for the operation; do not allow multiple clients to run SchemaPolicy.CREATE_IF_NECESSARY concurrently. After it succeeds, application instances should use SchemaPolicy.REQUIRE_EXISTING.

Create an ADB schema user

Use a dedicated ADB database user to own the Oracle Agent Memory schema. In the OCI Console, open Database Actions, sign in as ADMIN, and open the SQL worksheet. Create a user with a strong password, grant the privileges used by managed schema setup, and set a bounded storage quota for the user:

CREATE USER oam_owner IDENTIFIED BY "CHOOSE_A_STRONG_PASSWORD";
GRANT DWROLE TO oam_owner;
ALTER USER oam_owner QUOTA 1G ON DATA;

DWROLE includes the normal object-creation privileges Oracle Agent Memory uses, including CREATE TABLE, CREATE SEQUENCE, CREATE PROCEDURE, and CREATE JOB. CREATE JOB allows Oracle Agent Memory to create a scheduled job that permanently deletes records after they expire.

The 1G quota is a starting limit for this guide, not a production sizing recommendation. Select a limit based on the amount of memory you expect to store and your retention policy. Monitor storage use and increase the quota when needed; writes fail when the user reaches its quota. ADB manages tablespaces, so this guide does not create one.

Connect with TLS without a wallet

In the OCI Console, open the ADB details page. Under Network, configure an ACL that allows the application’s egress IP address, or use a private endpoint. Then edit Mutual TLS (mTLS) Authentication, clear Require mutual TLS (mTLS) authentication, and wait for the database to return to Available.

Open Database connection, select TLS under TLS Authentication, and select one of the listed connection services. The services typically have names such as myadb_low, myadb_medium, and myadb_high; they select how ADB shares database resources among connections. Start with the service level your database administrator recommends for the application’s workload, then copy its connection string. Store it and the database credentials in your secret-management system:

export ORACLE_MEMORY_DB_USER='oam_owner'
export ORACLE_MEMORY_DB_PASSWORD='<database-user-password>'
export ORACLE_MEMORY_DB_DSN='<copied TLS connection string>'

Use the TLS descriptor exactly as copied. An mTLS descriptor does not work without a wallet.

The example creates a connection pool, which is a reusable group of database connections. When ORACLE_MEMORY_ADB_USE_MTLS is not true, those connections use TLS. It uses SchemaPolicy.CREATE_IF_NECESSARY for first-time setup; use SchemaPolicy.REQUIRE_EXISTING in normal application startup after the schema is ready.

import os

import oracledb

from oracleagentmemory.core import (
    MemoryExtractionConfig,
    OracleAgentMemory,
    SchemaPolicy,
)
from oracleagentmemory.core.embedders import Embedder


def create_adb_tls_pool() -> oracledb.ConnectionPool:
    """Create an ADB TLS pool from securely injected environment variables."""
    return oracledb.create_pool(
        user=os.environ.get("ORACLE_MEMORY_DB_USER", "YOUR DB USER"),
        password=os.environ["ORACLE_MEMORY_DB_PASSWORD"],
        #Set ORACLE_MEMORY_DB_DSN to the TLS descriptor copied from the ADB console.
        dsn=os.environ["ORACLE_MEMORY_DB_DSN"],
        min=1,
        max=5,
        increment=1,
    )


embedder = Embedder(model="YOUR_EMBEDDING_MODEL")
MEMORY_STORE_ID = "APP_MEMORY"

Automatic memory extraction is disabled only to keep this connection example focused. Configure an LLM and enable extraction when the application needs automatic durable-memory extraction.

API Reference: OracleAgentMemory

SchemaPolicy

Connect with an mTLS wallet

Use this option if the ADB network configuration requires mTLS. In the OCI Console, open Database connection, select an Instance wallet, and download it. Extract the wallet into a protected directory that is not checked into source control. Oracle documentation recommends restrictive file permissions on wallet files (for example, use chmod 600 on Linux or Unix).

Export the database credentials, wallet directory, and the wallet-download password. ORACLE_MEMORY_WALLET_PASSWORD is the password you supplied when you downloaded the wallet ZIP file; it is not the database user’s password. Set ORACLE_MEMORY_DB_DSN to the service alias in the wallet’s tnsnames.ora file, such as myadb_low. Do not use the long TLS connection string from the ADB console for this wallet configuration:

export ORACLE_MEMORY_DB_USER='oam_owner'
export ORACLE_MEMORY_DB_PASSWORD='<database-user-password>'
export ORACLE_MEMORY_DB_DSN='myadb_low'
export ORACLE_MEMORY_WALLET_DIR='/secure/path/to/wallet'
export ORACLE_MEMORY_WALLET_PASSWORD='<wallet-download-password>'
export ORACLE_MEMORY_ADB_USE_MTLS='true'

In python-oracledb Thin mode, the wallet directory needs tnsnames.ora and ewallet.pem. Setting ORACLE_MEMORY_ADB_USE_MTLS to true makes the example create the mTLS pool before it initializes OracleAgentMemory.

def create_adb_mtls_pool() -> oracledb.ConnectionPool:
    """Create an ADB mTLS pool from securely injected environment variables."""
    return oracledb.create_pool(
        user=os.environ["ORACLE_MEMORY_DB_USER"],
        password=os.environ["ORACLE_MEMORY_DB_PASSWORD"],
        dsn=os.environ["ORACLE_MEMORY_DB_DSN"],
        config_dir=os.environ["ORACLE_MEMORY_WALLET_DIR"],
        wallet_location=os.environ["ORACLE_MEMORY_WALLET_DIR"],
        wallet_password=os.environ["ORACLE_MEMORY_WALLET_PASSWORD"],
        min=1,
        max=5,
        increment=1,
    )



if os.environ.get("ORACLE_MEMORY_ADB_USE_MTLS", "false").lower() == "true":
    db_pool = create_adb_mtls_pool()
else:
    db_pool = create_adb_tls_pool()

memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_store_id=MEMORY_STORE_ID,
)

Store and search memory in ADB

Once the Oracle Agent Memory client has been configured with either pool, create a thread, add a durable memory, and search it back.

thread = memory.create_thread(user_id="user_123")
thread.add_memory("The user prefers concise answers.")

results = memory.search(
    query="concise answers",
    user_id="user_123",
    record_types=["memory"],
    max_results=5,
)

for result in results:
    print(result.content)

API Reference: OracleAgentMemory

OracleThread

OracleSearchResult

Conclusion

In this guide we learned how to prepare an ADB user, select walletless TLS or mTLS, connect Oracle Agent Memory with a python-oracledb pool, and verify that a memory can be stored and retrieved from ADB.

→ Having connected Oracle Agent Memory to ADB, you may now proceed to Store and Search Memory.

Full Code

The complete example is included in this guide for you to copy and run.

#Copyright © 2026 Oracle and/or its affiliates.
#This software is under the Apache License 2.0
#(LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0) or Universal Permissive License
#(UPL) 1.0 (LICENSE-UPL or https://oss.oracle.com/licenses/upl), at your option.

#Oracle Agent Memory Code Example - Oracle Autonomous AI Database
#-------------------------------------------------------------

##Configure an Autonomous AI Database TLS connection pool

import os

import oracledb

from oracleagentmemory.core import (
    MemoryExtractionConfig,
    OracleAgentMemory,
    SchemaPolicy,
)
from oracleagentmemory.core.embedders import Embedder


def create_adb_tls_pool() -> oracledb.ConnectionPool:
    """Create an ADB TLS pool from securely injected environment variables."""
    return oracledb.create_pool(
        user=os.environ.get("ORACLE_MEMORY_DB_USER", "YOUR DB USER"),
        password=os.environ["ORACLE_MEMORY_DB_PASSWORD"],
        #Set ORACLE_MEMORY_DB_DSN to the TLS descriptor copied from the ADB console.
        dsn=os.environ["ORACLE_MEMORY_DB_DSN"],
        min=1,
        max=5,
        increment=1,
    )


embedder = Embedder(model="YOUR_EMBEDDING_MODEL")
MEMORY_STORE_ID = "APP_MEMORY"



##Configure an Autonomous AI Database mTLS connection pool

def create_adb_mtls_pool() -> oracledb.ConnectionPool:
    """Create an ADB mTLS pool from securely injected environment variables."""
    return oracledb.create_pool(
        user=os.environ["ORACLE_MEMORY_DB_USER"],
        password=os.environ["ORACLE_MEMORY_DB_PASSWORD"],
        dsn=os.environ["ORACLE_MEMORY_DB_DSN"],
        config_dir=os.environ["ORACLE_MEMORY_WALLET_DIR"],
        wallet_location=os.environ["ORACLE_MEMORY_WALLET_DIR"],
        wallet_password=os.environ["ORACLE_MEMORY_WALLET_PASSWORD"],
        min=1,
        max=5,
        increment=1,
    )



if os.environ.get("ORACLE_MEMORY_ADB_USE_MTLS", "false").lower() == "true":
    db_pool = create_adb_mtls_pool()
else:
    db_pool = create_adb_tls_pool()

memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_store_id=MEMORY_STORE_ID,
)



##Store and search memory in Autonomous AI Database

thread = memory.create_thread(user_id="user_123")
thread.add_memory("The user prefers concise answers.")

results = memory.search(
    query="concise answers",
    user_id="user_123",
    record_types=["memory"],
    max_results=5,
)

for result in results:
    print(result.content)