Oracle Autonomous AI Database와 함께 Oracle Agent 메모리 사용

이 가이드는 oracleagentmemory을 Oracle Autonomous Database(ADB)에 연결하는 방법을 보여줍니다.

이 가이드에서는 다음 방법을 배울 수 있습니다.

힌트: 패키지 설정은 에이전트 메모리 시작하기를 참조하십시오. 대신 컨테이너화된 로컬 데이터베이스에 대해 Oracle Agent Memory를 실행하려면 로컬에서 Oracle AI Database 실행을 따르십시오.

선행 조건

Oracle AI Vector Search(Oracle AI Database 23ai 이상), 데이터베이스 사용자를 생성할 수 있는 ADB 관리자, oracleagentmemory가 설치된 Python 환경을 지원하는 사용 가능한 Oracle Autonomous AI Database가 필요합니다. 아직 데이터베이스가 없는 경우 Oracle의 자율운영 AI 데이터베이스 프로비저닝 가이드를 따르십시오.

Oracle 에이전트 메모리는 응용 프로그램에서 제공하는 연결 또는 풀을 사용하며 데이터베이스 전송 보안 자체를 구성하지 않습니다. ADB는 다음 두 가지 보안 연결 옵션을 지원합니다.

운용 중인 데이터베이스에서 개별 데이터베이스 유저 사용

운용 중인 배치에서 두 명의 ADB 데이터베이스 유저를 사용합니다.

스키마 소유자의 인증서를 사용하여 응용 프로그램을 실행하지 마십시오. 관리 스키마를 설정하거나 업그레이드할 때만 사용합니다. 이 안내서는 먼저 스키마 소유자를 생성합니다. 설정 후 애플리케이션 사용자를 SchemaPolicy.REQUIRE_EXISTING로 구성합니다. 문제 해결 설명서에는 응용 프로그램 사용자가 필요로 하는 객체 권한 부여가 나열되어 있습니다.

관리 테이블에 쓰는 애플리케이션 인스턴스를 시작하기 전에 각 스키마 생성 또는 업그레이드를 단일 유지 관리 작업으로 실행하십시오. 작업에 하나의 스키마 소유자 연결을 사용합니다. 여러 클라이언트가 SchemaPolicy.CREATE_IF_NECESSARY를 동시에 실행할 수 있도록 허용하지 마십시오. 성공한 후 애플리케이션 인스턴스는 SchemaPolicy.REQUIRE_EXISTING를 사용해야 합니다.

ADB 스키마 유저 생성

전용 ADB 데이터베이스 사용자를 사용하여 Oracle 에이전트 메모리 스키마를 소유합니다. OCI 콘솔에서 Database Actions를 열고 ADMIN로 사인인한 다음 SQL 워크시트를 엽니다. 강력한 암호를 가진 유저를 생성하고, 관리 스키마 설정에 사용되는 권한을 부여하고, 유저에 대해 제한된 저장 영역 할당량을 설정합니다.

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

DWROLE에는 CREATE TABLE, CREATE SEQUENCE, CREATE PROCEDURE, CREATE JOB 등 Oracle Agent Memory가 사용하는 일반적인 객체 생성 권한이 포함되어 있습니다. CREATE JOB를 사용하면 Oracle 에이전트 메모리가 만료된 후 레코드를 영구적으로 삭제하는 예약된 작업을 생성할 수 있습니다.

1G 할당량은 운용 크기 조정 권장 사항이 아니라 이 설명서의 시작 제한입니다. 저장할 메모리 양 및 보존 정책에 따라 제한을 선택합니다. 스토리지 사용을 모니터링하고 필요한 경우 할당량을 늘립니다. 사용자가 할당량에 도달하면 쓰기가 실패합니다. ADB가 테이블스페이스를 관리하므로 이 설명서에서는 테이블스페이스를 생성하지 않습니다.

전자 지갑 없이 TLS로 접속

OCI 콘솔에서 ADB details 페이지를 엽니다. 네트워크에서 애플리케이션의 송신 IP 주소를 허용하거나 프라이빗 끝점을 사용할 수 있도록 ACL을 구성합니다. 그런 다음 mTLS(상호 TLS) 인증을 편집하고 mTLS(상호 TLS) 인증 필요를 지운 다음 데이터베이스가 Available로 돌아올 때까지 기다립니다.

데이터베이스 연결을 열고 TLS 인증에서 TLS를 선택한 다음 나열된 연결 서비스 중 하나를 선택합니다. 서비스는 일반적으로 myadb_low, myadb_medium 및 myadb_high와 같은 이름을 가지며, ADB가 연결 간에 데이터베이스 리소스를 공유하는 방식을 선택합니다. 데이터베이스 관리자가 응용 프로그램의 작업 로드에 대해 권장하는 서비스 레벨부터 시작한 다음 해당 연결 문자열을 복사합니다. 암호 관리 시스템에 해당 인증서와 데이터베이스 인증서를 저장합니다.

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

복사한 그대로 TLS 설명자를 사용합니다. mTLS 기술자는 전자 지갑 없이 작동하지 않습니다.

예제에서는 데이터베이스 연결의 재사용 가능한 그룹인 연결 풀을 생성합니다. ORACLE_MEMORY_ADB_USE_MTLS가 true가 아닌 경우 해당 연결은 TLS를 사용합니다. 첫번째 설정에 SchemaPolicy.CREATE_IF_NECESSARY를 사용하고, 스키마가 준비된 후 정상적인 응용 프로그램 시작 시 SchemaPolicy.REQUIRE_EXISTING를 사용합니다.

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"

자동 메모리 추출은 이 연결 예제에 초점을 맞추기 위해서만 비활성화됩니다. 응용 프로그램에 자동 영구 메모리 추출이 필요한 경우 LLM을 구성하고 추출을 사용으로 설정합니다.

API 참조: OracleAgentMemory 스키마 정책

mTLS 전자 지갑으로 접속

ADB 네트워크 구성에 mTLS가 필요한 경우 이 옵션을 사용합니다. OCI 콘솔에서 데이터베이스 접속을 열고 인스턴스 전자 지갑을 선택한 다음 다운로드합니다. 소스 제어로 체크인되지 않은 보호된 디렉토리로 전자 지갑을 추출합니다. Oracle 설명서에서는 전자 지갑 파일에 대한 제한적인 파일 권한을 권장합니다(예: Linux 또는 Unix의 경우 chmod 600 사용).

데이터베이스 인증서, 전자 지갑 디렉토리 및 전자 지갑 다운로드 비밀번호를 익스포트합니다. ORACLE_MEMORY_WALLET_PASSWORD은 전자 지갑 ZIP 파일을 다운로드할 때 제공한 비밀번호이며 데이터베이스 사용자의 비밀번호가 아닙니다. ORACLE_MEMORY_DB_DSN를 전자 지갑의 tnsnames.ora 파일에 있는 서비스 별칭(예: myadb_low)으로 설정합니다. 이 전자 지갑 구성에 대해 ADB 콘솔에서 긴 TLS 연결 문자열을 사용하지 마십시오.

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'

python-oracledb Thin 모드에서는 전자 지갑 디렉토리에 tnsnames.ora 및 ewallet.pem가 필요합니다. ORACLE_MEMORY_ADB_USE_MTLS를 true로 설정하면 예제에서 OracleAgentMemory를 초기화하기 전에 mTLS 풀을 만듭니다.

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

ADB에 메모리 저장 및 검색

Oracle Agent 메모리 클라이언트가 풀 중 하나로 구성되면 스레드를 생성하고 내구성이 뛰어난 메모리를 추가한 다음 다시 검색합니다.

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 참조: OracleAgentMemory 오라클 스레드 오라클 검색 결과

결론

이 설명서에서는 ADB 사용자를 준비하고, 전자 지갑이 없는 TLS 또는 mTLS를 선택하고, python-oracledb 풀을 사용하여 Oracle 에이전트 메모리를 연결하고, ADB에서 메모리를 저장 및 검색할 수 있는지 확인하는 방법을 배웠습니다.

→ ADB에 Oracle Agent 메모리를 연결한 경우 이제 Store and Search Memory를 진행할 수 있습니다.

전체 코드

이 설명서에는 복사 및 실행을 위한 전체 예가 포함되어 있습니다.

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