Oracle Agent-Speicher mit Oracle Autonomous AI Database verwenden

In diesem Handbuch wird gezeigt, wie Sie oracleagentmemory mit Oracle Autonomous Database (ADB) verbinden.

In diesem Handbuch erfahren Sie, wie Sie:

ADB-Schemabenutzer für Oracle Agent-Speicher vorbereiten
Verbinden Sie sich mit Walletless TLS oder mit einem mTLS-Wallet.
Initialisieren Sie das Schema für den verwalteten Speicher, speichern und durchsuchen Sie einen Speicher.

Hinweis: Informationen zum Packagesetup finden Sie unter Erste Schritte mit Agent-Speicher. Um Oracle Agent Memory stattdessen für eine containerisierte lokale Datenbank auszuführen, folgen Sie Oracle AI Database lokal ausführen.

Voraussetzungen

Sie benötigen eine verfügbare Oracle Autonomous AI Database, die Oracle AI Vector Search (Oracle AI Database 23ai oder höher) unterstützt, einen ADB-Administrator, der einen Datenbankbenutzer erstellen kann, und eine Python-Umgebung mit installierter oracleagentmemory. Wenn Sie noch keine Datenbank haben, befolgen Sie den Leitfaden zum Provisioning der autonomen KI-Datenbank von Oracle.

Der Oracle Agent-Speicher verwendet die von Ihrer Anwendung bereitgestellte Verbindung oder den von Ihnen bereitgestellten Pool. Er konfiguriert nicht die Sicherheit für den Datenbanktransport selbst. ADB unterstützt zwei sichere Verbindungsoptionen:

TLS ohne Wallet eignet sich für die meisten neuen Anwendungen. Es verwendet Datenbankzugangsdaten und verschlüsselt die Verbindung. Konfigurieren Sie vor der Verwendung eine IP-Ausnahmeliste (ACL) oder einen privaten Endpunkt, damit die Anwendung die Datenbank erreichen kann. TLS schützt die Verbindung; der ACL- oder private Endpunkt steuert, welche Netzwerke die Datenbank erreichen können.
Mutual TLS (mTLS) mit einem Wallet ist geeignet, wenn ADB mTLS erfordert oder wenn Ihre Organisation eine Client-Zertifikat-Authentifizierung erfordert.

Separate Datenbankbenutzer in der Produktion verwenden

Verwenden Sie zwei ADB-Datenbankbenutzer in einem Produktions-Deployment:

Der Schemaeigentümer erstellt, aktualisiert und ist Eigentümer der Oracle Agent-Speichertabellen und -Indizes.
Der Anwendungsbenutzer stellt eine Verbindung her, wenn die Anwendung Speicher liest und schreibt. Erteilen Sie diesem Benutzer nur die Berechtigungen, die er für die Objekte des Schemaeigentümers benötigt.

Verwenden Sie nicht die Zugangsdaten des Schemaeigentümers, um die Anwendung auszuführen. Verwenden Sie sie nur, wenn Sie das verwaltete Schema einrichten oder aktualisieren. In dieser Anleitung wird zunächst der Schemaeigentümer erstellt. Konfigurieren Sie nach dem Setup den Anwendungsbenutzer mit SchemaPolicy.REQUIRE_EXISTING. In der Fehlerbehebungsdokumentation werden die Objektberechtigungen aufgeführt, die von einem Anwendungsbenutzer benötigt werden.

Führen Sie jede Schemaerstellung oder jedes Upgrade als einzelnen Wartungsvorgang aus, bevor Sie Anwendungsinstanzen starten, die in die verwalteten Tabellen schreiben. Verwenden Sie eine Schemaeigentümerverbindung für den Vorgang. Lassen Sie nicht zu, dass mehrere Clients SchemaPolicy.CREATE_IF_NECESSARY gleichzeitig ausführen. Nach erfolgreicher Ausführung sollten Anwendungsinstanzen SchemaPolicy.REQUIRE_EXISTING verwenden.

ADB-Schemabenutzer erstellen

Verwenden Sie einen dedizierten ADB-Datenbankbenutzer, um Eigentümer des Oracle Agent-Speicherschemas zu sein. Öffnen Sie in der OCI-Konsole Database Actions, melden Sie sich als ADMIN an, und öffnen Sie das SQL-Arbeitsblatt. Erstellen Sie einen Benutzer mit einem starken Kennwort, erteilen Sie die Berechtigungen, die vom Setup des verwalteten Schemas verwendet werden, und legen Sie eine gebundene Speicher-Quota für den Benutzer fest:

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

DWROLE umfasst die normalen Objekterstellungsberechtigungen, die der Oracle Agent-Speicher verwendet, einschließlich CREATE TABLE, CREATE SEQUENCE, CREATE PROCEDURE und CREATE JOB. Mit CREATE JOB kann der Oracle Agent-Speicher einen geplanten Job erstellen, der Datensätze nach deren Ablauf endgültig löscht.

Die Quota 1G ist ein Startlimit für diese Anleitung und keine Empfehlung zur Größenanpassung für die Produktion. Wählen Sie einen Grenzwert basierend auf der erwarteten Speichermenge und der Aufbewahrungs-Policy aus. Überwachen Sie die Speicherauslastung, und erhöhen Sie die Quota bei Bedarf. Schreibvorgänge sind nicht erfolgreich, wenn der Benutzer seine Quota erreicht. ADB verwaltet Tablespaces, sodass in diesem Handbuch kein Tablespace erstellt wird.

Mit TLS ohne Wallet verbinden

Öffnen Sie in der OCI-Konsole die Seite "ADB-Details". Konfigurieren Sie unter Netzwerk eine ACL, die die Egress-IP-Adresse der Anwendung zulässt, oder verwenden Sie einen privaten Endpunkt. Bearbeiten Sie dann die Mutual TLS-(mTLS-)Authentifizierung, löschen Sie die Option Gegenseitige TLS-(mTLS-)Authentifizierung erforderlich, und warten Sie, bis die Datenbank zu Available zurückkehrt.

Öffnen Sie die Datenbankverbindung, wählen Sie unter TLS-Authentifizierung die Option TLS aus, und wählen Sie einen der aufgeführten Verbindungsservices aus. Die Services haben in der Regel Namen wie myadb_low, myadb_medium und myadb_high. Sie wählen aus, wie ADB Datenbankressourcen zwischen Verbindungen teilt. Beginnen Sie mit der Serviceebene, die der Datenbankadministrator für die Workload der Anwendung empfiehlt, und kopieren Sie dann die Verbindungszeichenfolge. Speichern Sie sie und die Datenbankzugangsdaten in Ihrem 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>'

Verwenden Sie den TLS-Deskriptor genau wie kopiert. Ein mTLS-Deskriptor funktioniert ohne ein Wallet nicht.

Im Beispiel wird ein Verbindungspool erstellt, bei dem es sich um eine wiederverwendbare Gruppe von Datenbankverbindungen handelt. Wenn ORACLE_MEMORY_ADB_USE_MTLS nicht true ist, verwenden diese Verbindungen TLS. Es verwendet SchemaPolicy.CREATE_IF_NECESSARY für das erstmalige Setup. Verwenden Sie SchemaPolicy.REQUIRE_EXISTING beim normalen Anwendungsstart, nachdem das Schema bereit ist.

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"

Die automatische Speicherextraktion ist nur deaktiviert, um dieses Verbindungsbeispiel im Blick zu behalten. Konfigurieren Sie ein LLM, und aktivieren Sie die Extraktion, wenn die Anwendung eine automatische dauerhafte Speicherextraktion benötigt.

API-Referenz: OracleAgentMemory

Schema-Policy

Verbindung mit einem mTLS-Wallet herstellen

Verwenden Sie diese Option, wenn für die ADB-Netzwerkkonfiguration mTLS erforderlich ist. Öffnen Sie in der OCI-Konsole die Datenbankverbindung, wählen Sie ein Instanz-Wallet aus, und laden Sie es herunter. Extrahieren Sie das Wallet in ein geschütztes Verzeichnis, das nicht in der Quellkontrolle eingecheckt ist. In der Oracle-Dokumentation werden restriktive Dateiberechtigungen für Wallet-Dateien empfohlen (Beispiel: Verwenden Sie chmod 600 unter Linux oder Unix).

Exportieren Sie die Datenbankzugangsdaten, das Wallet-Verzeichnis und das Wallet-Downloadkennwort. ORACLE_MEMORY_WALLET_PASSWORD ist das Kennwort, das Sie beim Herunterladen der Wallet-ZIP-Datei angegeben haben. Es handelt sich nicht um das Kennwort des Datenbankbenutzers. Setzen Sie ORACLE_MEMORY_DB_DSN auf den Servicealias in der tnsnames.ora-Datei des Wallets, wie myadb_low. Verwenden Sie nicht die lange TLS-Verbindungszeichenfolge aus der ADB-Konsole für diese Wallet-Konfiguration:

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'

Im Thin-Modus python-oracledb benötigt das Wallet-Verzeichnis tnsnames.ora und ewallet.pem. Wenn Sie ORACLE_MEMORY_ADB_USE_MTLS auf true setzen, wird im Beispiel der mTLS-Pool erstellt, bevor OracleAgentMemory initialisiert wird.

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,
)

Speicher und Suchspeicher in ADB

Nachdem der Oracle Agent-Speicherclient mit einem Pool konfiguriert wurde, erstellen Sie einen Thread, fügen Sie einen dauerhaften Speicher hinzu, und suchen Sie ihn zurück.

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-Referenz: OracleAgentMemory

OracleThread

OracleSearchResult

Abschluss

In diesem Handbuch haben wir gelernt, wie Sie einen ADB-Benutzer vorbereiten, Walletless TLS oder mTLS auswählen, Oracle Agent Memory mit einem python-oracledb-Pool verbinden und prüfen, ob ein Speicher gespeichert und aus ADB abgerufen werden kann.

→ Nachdem Sie Oracle Agent Memory mit ADB verbunden haben, können Sie jetzt mit Speicher und Suchspeicher fortfahren.

Vollständiger Code

Das vollständige Beispiel ist in diesem Handbuch enthalten, das Sie kopieren und ausführen können.

#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)