에이전트 메모리 시작하기

이 문서에서는 에이전트 메모리 설치 및 사용자 컨텍스트 저장 및 검색을 비롯한 기본 메모리 작업 수행 과정을 안내합니다.

선행 조건

다음과 같은 작업을 수행할 수 있습니다.

Oracle AI Database 기능 요구사항

Oracle Agent 메모리의 DB 지원 저장소에는 Oracle AI Database 23ai 이상이 필요합니다(데이터베이스 버전 23.4 이상). Oracle AI Vector Search의 경우 데이터베이스 COMPATIBLE 초기화 매개변수를 23.4.0 이상으로 설정합니다.

선택한 검색 전략에는 다음과 같은 추가 요구 사항이 있습니다.

관리 스키마 초기화 중 Oracle Agent Memory는 DDL을 실행하기 전에 접속된 데이터베이스 버전을 검증하고 선택한 검색 전략을 사용할 수 없을 때 업그레이드 작업을 보고합니다.

관리 데이터베이스 설정

스키마 소유자가 메모리 저장소를 생성하거나 재생성할 때 Oracle Agent Memory Python 패키지는 필요한 관리 데이터베이스 객체를 준비합니다. 소유자에게는 Oracle CREATE TABLE 및 CREATE PROCEDURE 시스템 권한이 필요합니다.

스키마 설정에 대한 스키마 소유자로 연결합니다. schema_owner를 사용하는 응용 프로그램 연결은 기존 저장소에 액세스하며 SchemaPolicy.REQUIRE_EXISTING를 사용해야 합니다. 소유자의 관리 데이터베이스 객체를 생성하거나 업데이트하지는 않습니다.

SDK 설치

소프트웨어 다운로드 페이지에서 oracleagentmemory의 모든 버전 및 지원되는 플랫폼을 찾을 수 있습니다.

에이전트 메모리를 설치하려면 다음을 실행합니다.

pip install "oracleagentmemory==26.8.0"

pip를 사용하여 설치하면 지원되는 플랫폼에서 사전 구축된 바이너리 휠이 풀링됩니다.

로깅 및 분석

Oracle AI Agent Memory는 oracleagentmemory로 시작하는 로거 이름으로 표준 Python 로깅을 통해 진단 메시지를 내보냅니다. SDK는 처리기 또는 로그 레벨을 구성하지 않습니다. 응용 프로그램은 이러한 로그를 기존 콘솔, 파일 또는 관찰성 파이프라인으로 라우팅할 수 있습니다. 일부 로그 레코드는 구조화된 로깅 처리기로 캡처할 수 있는 안전한 구조화된 진단을 위해 Python 로깅의 extra 필드를 사용합니다.

import logging

logging.basicConfig(level=logging.INFO)
logging.getLogger("oracleagentmemory").setLevel(logging.INFO)

제어 환경에서 문제를 해결하려면 DEBUG 로그를 사용으로 설정합니다.

logging.getLogger("oracleagentmemory").setLevel(logging.DEBUG)

운영 배포를 DEBUG 수준이 아닌 수준으로 유지합니다. DEBUG 로그는 개발 및 지원 진단을 위한 것이며 로그 메시지 텍스트는 안정적인 공용 API로 취급해서는 안됩니다.

보관 시간 및 만료 레코드 비우기

Oracle DB 지원 메시지 및 메모리는 쓰기 및 업데이트 API에서 스키마 레벨 보존 기본값과 레코드별 ttl_days/ttl_anchor 값을 조합하여 자동으로 만료될 수 있습니다.

Oracle Agent Memory는 관리 스키마를 생성하거나 업그레이드할 때 만료된 행, 해당 검색 청크 및 지원되는 소스 행이 더 이상 존재하지 않는 고립된 검색 청크를 물리적으로 제거하는 일별 DBMS_SCHEDULER 비우기 작업도 생성합니다. 스키마 설정에서 해당 작업을 생성해야 하지만 데이터베이스 사용자에게 CREATE JOB가 없으면 만료된 행은 읽기 및 검색에서 필터링된 상태로 유지되지만 만료된 청크와 고립된 청크는 권한이 있는 사용자가 작업을 생성할 때까지 물리적으로 비워지지 않습니다. SchemaPolicy.REQUIRE_EXISTING에서 누락된 비우기 작업은 허용되며 DEBUG 레벨에서 기록됩니다.

또한 Linked-memory 스키마는 삭제 작업이 만료된 메모리를 삭제하고 Oracle이 해당 링크를 캐스케이드하는 경우를 포함하여 링크가 삭제된 후 남아 있는 메모리를 재검증하는 트리거를 생성합니다. 스키마 소유자에는 스키마 생성 또는 업그레이드 중 CREATE TRIGGER가 필요합니다. 일반 런타임 사용자는 해당 권한이 필요하지 않습니다.

전체 보존 모델, MemoryRetentionConfig 설정, 비우기 작업 확인 질의, 수동 DBA 작업 생성 및 TimeToLiveAnchor를 사용하는 Python 예는 메시지 및 메모리에 보관 시간 사용을 참조하십시오.

Linked-Memory 스키마 권한

Linked-memory 스키마에는 Oracle SQL 속성 그래프와 링크가 삭제될 때 수명 주기 상태를 정확하게 유지하는 데이터베이스 트리거가 포함되어 있습니다.

memory_store_id를 설정할 경우 관리되는 그래프 이름 앞에 테이블과 동일한 방식으로 접두어가 붙습니다. 예를 들어, memory_store_id="SALES"는 SALES_MEMORY_GRAPH를 생성합니다.

APP_SCHEMA 및 APP_USER 값은 자리 표시자입니다. 데이터베이스 사용자 이름으로 바꿉니다. 따옴표로 묶이지 않은 Oracle 식별자는 대문자로 저장되므로 예제에서는 대문자를 사용합니다.

  1. 스키마 설정 중 스키마 소유자에게 CREATE PROPERTY GRAPH 및 CREATE TRIGGER을 부여합니다. 관리형 그래프 또는 링크 삭제 트리거를 생성해야 할 때마다 SchemaPolicy.CREATE_IF_NECESSARY 또는 SchemaPolicy.RECREATE에 필요합니다. 
    GRANT CREATE PROPERTY GRAPH TO APP_SCHEMA;
GRANT CREATE TRIGGER TO APP_SCHEMA;
-- Run OracleAgentMemory schema setup as APP_SCHEMA.
REVOKE CREATE PROPERTY GRAPH FROM APP_SCHEMA;
REVOKE CREATE TRIGGER FROM APP_SCHEMA;

    업그레이드 시 관리형 그래프 또는 링크 삭제 트리거를 생성하거나 재생성해야 하는 경우 이후 SDK 업그레이드 전에 다시 부여하십시오.

  2. 일반적인 응용 프로그램 런타임 시 Oracle에 연결할 유저를 결정합니다.
    • 런타임 사용자가 APP_SCHEMA인 경우 추가 그래프 권한 부여가 필요하지 않습니다. 그래프 소유자는 자체 그래프에 액세스할 수 있습니다.
    • 런타임 사용자가 다른 경우 스키마 설정 후 다음을 APP_SCHEMA로 실행합니다. 기본 그래프 이름은 MEMORY_GRAPH이며, memory_store_id가 설정된 경우 접두어가 붙은 이름을 사용합니다. 
      GRANT SELECT ON PROPERTY GRAPH APP_SCHEMA.MEMORY_GRAPH TO APP_USER;

      또한 런타임 사용자에게는 나머지 Oracle Agent 메모리 배치에 필요한 일반 데이터베이스 액세스가 필요합니다.

SchemaPolicy.REQUIRE_EXISTING는 그래프와 트리거가 이미 존재해야 하므로 첫번째 단계를 건너뜁니다. 별도의 런타임 사용자는 여전히 관리 속성 그래프에 액세스해야 합니다.

메모리 인스턴스 초기화

임베더, LLM 및 데이터베이스 접속을 구성하여 OracleAgentMemory 인스턴스를 생성합니다.

import oracledb

from oracleagentmemory.core import SchemaPolicy
from oracleagentmemory.core.oracleagentmemory import OracleAgentMemory
from oracleagentmemory.apis.searchscope import SearchScope
from oracleagentmemory.core.embedders.embedder import Embedder
from oracleagentmemory.core.llms.llm import Llm

embedder = Embedder(model="YOUR_EMBEDDING_MODEL")
llm = Llm(model="YOUR_LLM")
db_pool = oracledb.SessionPool(
    user="YOUR DB USER",
    password="YOUR DB PASSWORD",
    dsn="YOUR DB CONNECT STRING",
)
memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_store_id="T_GET_STARTED",
)

주: 기본적으로 관리형 Oracle AI Database 스키마는 메시지 및 메모리에 대한 보존 기간을 설정하지 않습니다. 다른 보존 기간을 사용하도록 MemoryRetentionConfig 또는 레코드별 TTL 설정을 구성합니다. 자세한 내용은 메시지 및 메모리에 Time-to-Live 사용을 참조하십시오.

메모리 항목 저장

스레드를 만들고, 메시지를 추가하고, 사용자에 대한 메모리 항목을 저장하는 것부터 시작합니다.

messages = [
    {
        "role": "user",
        "content": (
            "Orange juice has become my favorite breakfast drink lately, "
            "what can I pair it with?"
        ),
    },
    {
        "role": "assistant",
        "content": (
            "Nice! Orange juice goes great with something savory. "
            "Try eggs and toast, avocado toast, or a breakfast sandwich."
        ),
    },
]

thread = memory.create_thread(user_id="user_123")
#add_messages will add messages to the DB and extract memories automatically
thread.add_messages(messages)
#add_memory adds memory to the DB
thread.add_memory("The user likes orange juice with breakfast.")

메모리 항목 검색

사용자 범위의 질의를 사용하여 메모리를 검색합니다.

results = memory.search(query="orange juice", scope=SearchScope(user_id="user_123"))
for result in results:
    print(f"- [{result.record.record_type}] {result.content}")

출력:

- [memory] The user likes orange juice with breakfast.
- [message] Orange juice has become my favorite breakfast drink lately, what can I pair it with?
- [message] Nice! Orange juice goes great with something savory. Try eggs and toast,
            avocado toast, or a breakfast sandwich.

주: 표시된 출력은 그림입니다. 이후 버전은 추가 결과 유형, 필드 또는 순서를 반환할 수 있습니다.

모델 호환성

다음 LLM(Large Language Models) 및 임베딩 모델은 oracleagentmemory과 호환됩니다.

LLM

다음 LLM(대형 언어 모델)이 호환되는 것으로 확인되었습니다.

OCI 호스팅 모델

OpenAI

자체 호스팅된 LLM

인류학

쌍둥이

임베딩

다음 임베딩 모델이 호환되는 것으로 확인되었습니다.

OCI 호스팅 모델

OpenAI

자체 호스팅된 LLM

쌍둥이