에이전트 메모리 시작하기

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

필수 조건

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

SDK 설치

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

pip install "oracleagentmemory==26.6.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로 취급해서는 안됩니다.

메모리 인스턴스 초기화

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

import oracledb

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)

주: 기본적으로 관리형 Oracle 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.

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

모델 호환성

2026년 4월 현재 다음 LLM(Large Language Models) 및 임베딩 모델은 oracleagentmemory과 호환됩니다.

LLM

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

OCI 호스팅 모델

OpenAI

자체 호스팅된 LLM

인류학

Gemini

임베딩

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

OCI 호스팅 모델

OpenAI

Gemini