에이전트 메모리

이 페이지에서는 구체적인 Oracle AI 에이전트 메모리 구현을 보여줍니다.

Oracle 에이전트 메모리

주: OracleAgentMemory.delete_thread()는 스레드 범위의 계단식 정리에 대해 지원되는 경로입니다. 연관된 메시지, 내구성 있는 메모리 및 관리되는 검색 데이터와 함께 스레드를 제거합니다. 원시 메시지 행만 삭제하는 OracleThread.delete_message()보다 큽니다. 스레드를 삭제하기 전에 해당 스레드에 대해 이 클라이언트에 이미 알려진 이전에 수락된 백그라운드 추출을 기다립니다. 삭제가 진행 중인 동안 동일한 스레드에 대한 모든 동시 작업을 직렬화하지는 않습니다.

클래스 oracleagentmemory.core.OracleAgentMemory

기준: IAgentMemory

Oracle DB 또는 호출자가 제공한 저장소에서 지원하는 에이전트 메모리 클라이언트입니다.

메모리 클라이언트를 만듭니다.

경고: SchemaPolicy.CREATE_IF_NECESSARY는 초기화가 성공하기 전에 관리 스키마 DDL 및 최선 조건 데이터 재작성을 적용할 수 있으므로 일반 클라이언트 시작보다 비용이 많이 들 수 있습니다. 스키마에 많은 행이 포함될 수 있는 경우 이전 관리 스키마의 첫번째 열기를 이전 또는 유지 관리 작업으로 계획합니다.

스키마 설정에서 만료된 관리 레코드 비우기 작업을 생성해야 하지만 데이터베이스 사용자에게 스케줄러 작업 권한이 없는 경우 초기화가 경고되고 계속됩니다. 만료된 메시지 및 메모리는 읽기 및 검색에서 숨겨지지만 CREATE JOB 또는 이와 동등한 스케줄러 권한을 가진 사용자가 작업을 생성할 때까지는 물리적으로 비워지지 않습니다.

SchemaPolicy.CREATE_IF_NECESSARY가 기존 스키마를 통해 관리형 하이브리드 인덱스를 처음 생성하는 경우 Oracle은 저장된 검색 텍스트를 스캔하고 구성된 데이터베이스 내 모델에서 관리형 하이브리드 인덱스 상태를 구축합니다. 클라이언트 시작은 해당 DDL이 완료될 때까지 기다리므로 대규모 스키마에 대한 이전 또는 유지 관리 작업으로 첫번째 하이브리드 업그레이드를 계획하십시오. SearchIndexSyncMode는 인덱스가 존재하는 후의 지속적인 유지 관리를 제어하며 첫번째 인덱스가 비동기적으로 생성되지 않습니다.

예제

from oracleagentmemory.core import (
    MemoryExtractionConfig,
    SearchIndexSyncMode,
    OracleAgentMemory,
    SchemaPolicy,
    SearchStrategy,
)
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
read_only_client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
)

DB 내 임베딩 모델을 사용하여 Oracle 하이브리드 인덱스 검색 활용:

from oracleagentmemory.core.embedders import OracleDBEmbedder
db_embedder = OracleDBEmbedder(
    connection=db_pool,
    model="DOC_MODEL",
    embedding_dimension=768,
)
hybrid_client = OracleAgentMemory(
    connection=db_pool,
    embedder=db_embedder,
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    search_strategy=SearchStrategy.HYBRID,
    search_index_sync=SearchIndexSyncMode.ON_COMMIT,
)

방법 add_agent

상점에 에이전트 프로파일 레코드를 추가합니다.

주

에이전트 프로파일 레코드는 클라이언트 레벨 저장소에 저장되며 의도적으로 범위가 지정되지 않습니다. 반환된 레코드 식별자는 애플리케이션이 agent_id로 사용하는 공용 식별자와 동일합니다.

예제

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_agent(
    "a1",
    "Support assistant",
    metadata={"source": "catalog"},
)
'a1'

방법 add_memory

표시된 사용자, 에이전트 및 스레드에 기인한 메모리를 메모리 시스템에 추가합니다.

예제

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
memory_id = client.add_memory("User likes pizza", memory_id="mem-1")
memory_id
'mem-1'

method add_memory_async(비동기)

비동기적으로 클라이언트에 메모리 레코드를 추가합니다.

방법 add_user

점포에 사용자 프로파일 레코드를 추가합니다.

주

사용자 프로파일 레코드는 클라이언트 레벨 저장소에 저장되며 의도적으로 범위가 지정되지 않습니다. 반환된 레코드 식별자는 애플리케이션이 user_id로 사용하는 공용 식별자와 동일합니다.

예제

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_user(
    "u1",
    "Prefers concise answers.",
    metadata={"source": "crm"},
)
'u1'

방법 close

에이전트 메모리 구성 요소를 닫습니다.

닫기는 새 백그라운드 추출 작업 수락을 중지하고 보류 중인 백그라운드 메모리 추출이 구성된 시간 초과까지 완료될 때까지 기다립니다. 해당 시간 초과가 만료되면 일부 백그라운드 추출 작업이 아직 완료되지 않은 경우에도 close()가 반환됩니다. 메소드는 idempotent입니다.

예제

client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
)
client.close()

method close_async(비동기)

에이전트 메모리 구성 요소를 비동기적으로 닫습니다.

이 방법은 close()와 동일한 종료 동작을 따릅니다. 시간 초과가 만료되면 백그라운드 추출 작업이 계속 실행되는 동안 반환될 수 있습니다.

예제

await client.close_async()

방법 create_thread

스레드를 만들고 등록합니다.

예제

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
thread = client.create_thread(thread_id="c1", user_id="u1")
thread.thread_id
'c1'

방법 delete_agent

식별자별로 에이전트 프로파일 레코드를 삭제합니다.

주

계단식 삭제는 보조 저장소 내에서 계획되고 실행되므로 프로파일 삭제 및 모든 범위가 지정된 하위 삭제가 하나의 저장소 작업에서 수행됩니다. 계단식 삭제가 실행되기 전에 이 메소드는 이 에이전트 메모리 구성 요소를 통해 해당 시점에 알려진 소유 스레드에 대해 이미 수락된 이전 백그라운드 추출을 기다립니다. 해당 대기가 시작된 후 또는 다른 에이전트 메모리 구성 요소나 프로세스에 의해 시작된 작업을 위해 수락된 작업을 기다리지 않습니다. 삭제가 진행 중인 동안의 동시 작업자 범위 사용이 지원되지 않습니다.

예제

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_agent("a-delete", "Support assistant")
'a-delete'
client.delete_agent("a-delete")
1

방법 delete_memory

메모리 유사 레코드(예: 메모리, 팩트, 기본 설정 또는 지침)를 식별자로 삭제합니다.

예제

client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
memory_id = client.add_memory("Temporary memory", memory_id="mem-delete")
client.delete_memory(memory_id)
1

method delete_memory_async(비동기)

메모리 유사 레코드(예: 메모리, 팩트, 기본 설정 또는 지침)를 식별자로 비동기적으로 삭제합니다.

방법 delete_thread

스레드 식별자와 연관된 모든 레코드를 삭제합니다.

주

스레드의 보존-완료 제거가 필요한 경우 이 작업을 사용합니다. 보조 저장소는 연관된 스레드 범위의 메시지, 영구 메모리와 관리되는 검색 데이터와 함께 스레드를 삭제합니다. 이는 원시 메시지 레코드만 제거하고 해당 메시지에서 생성된 파생된 메모리에 캐스케이드하지 않는 OracleThread.delete_message()와 다릅니다. 스레드를 삭제하기 전에 이 메소드는 이 에이전트 메모리 구성 요소를 통해 해당 스레드에 대해 이미 수락된 이전 백그라운드 추출을 기다립니다. 해당 대기가 시작된 후 또는 다른 에이전트 메모리 구성 요소나 프로세스에 의해 시작된 작업을 위해 백그라운드 작업이 수락될 때까지 기다리지 않습니다. 삭제가 진행 중인 동안 동일한 스레드의 동시 사용은 지원되지 않습니다.

예제

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
thread = client.create_thread(thread_id="c-delete")
client.delete_thread(thread.thread_id)
1

방법 delete_user

식별자로 사용자 프로파일 레코드를 삭제합니다.

주

계단식 삭제는 보조 저장소 내에서 계획되고 실행되므로 프로파일 삭제 및 모든 범위가 지정된 하위 삭제가 하나의 저장소 작업에서 수행됩니다. 계단식 삭제가 실행되기 전에 이 메소드는 이 에이전트 메모리 구성 요소를 통해 해당 시점에 알려진 소유 스레드에 대해 이미 수락된 이전 백그라운드 추출을 기다립니다. 해당 대기가 시작된 후 또는 다른 에이전트 메모리 구성 요소나 프로세스에 의해 시작된 작업을 위해 수락된 작업을 기다리지 않습니다. 삭제가 진행 중인 동안의 동시 작업자 범위 사용이 지원되지 않습니다.

예제

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_user("u-delete", "Prefers concise answers.")
'u-delete'
client.delete_user("u-delete")
1

방법 get_thread

이전에 생성한 스레드를 검색합니다.

주

명시적 호출당 재정의가 우선합니다. 런타임 대체가 생략되면 재개설된 스레드는 SDK 기본값으로 폴백하기 전에 사용 가능한 경우 지속 런타임 구성을 사용합니다.

예제

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
created = client.create_thread(thread_id="c1", user_id="u1")
loaded = client.get_thread("c1")
loaded.user_id
'u1'

조회와 관련된 레코드를 동기적으로 검색합니다.

주

명시적 None 범위 값은 해결된 정확한 일치 규칙을 계속 따릅니다. exact_*_match=False는 해당 차원을 제약 없는 상태로 둡니다. 반면 exact_*_match=True는 해당 차원에서 범위가 지정되지 않은 레코드만 일치시킵니다.

method search_async(비동기)

조회와 관련된 레코드를 비동기적으로 검색합니다.

주

명시적 None 범위 값은 해결된 정확한 일치 규칙을 계속 따릅니다. exact_*_match=False는 해당 차원을 제약 없는 상태로 둡니다. 반면 exact_*_match=True는 해당 차원에서 범위가 지정되지 않은 레코드만 일치시킵니다.

방법 update_memory

저장된 메모리 유사 레코드를 식별자로 업데이트합니다.

주

생략된 필드는 저장된 레코드에서 보존됩니다. 저장된 범위는 변경되지 않은 상태로 유지됩니다. 메타데이터 바꾸기는 순환적 JSON 병합이 아닌 전체 객체 바꾸기입니다.

method update_memory_async(비동기)

저장된 메모리와 유사한 레코드를 식별자로 비동기적으로 업데이트합니다.

주

생략된 필드는 변경되지 않습니다. 이 API에서는 범위 업데이트가 지원되지 않습니다. 메타데이터 바꾸기는 순환적 JSON 병합이 아닌 전체 객체 바꾸기입니다.

방법 update_thread

스레드 메타데이터 및 영구 런타임 구성 업데이트를 유지합니다.

주

런타임 구성은 저장된 대화 스레드와 이 호출에 전달된 명시적 우선 적용에서 분석되어 결과를 지속하기 전에 get_thread 의미와 일치합니다. 생략된 메타데이터 및 런타임 구성 업데이트는 이전에 로드된 OracleThread 인스턴스가 아닌 저장된 데이터에서 해결되며 명시적으로 제공된 메타데이터 업데이트 또는 영구 런타임 구성 대체만 다시 기록됩니다. 메타데이터 바꾸기는 순환적 JSON 병합이 아닌 전체 객체 바꾸기입니다. 스레드 소유권은 이 API를 통해 변경될 수 없으므로 user_id 및 agent_id는 변경되지 않습니다. 추출 카운터와 같은 변경 가능한 런타임 상태는 그대로 유지됩니다.

예제

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
updated = client.update_thread(
    "c1",
    metadata={"flags": {"vip": True}},
    message_shortening_input_token_limit=12_000,
)
updated.message_shortening_input_token_limit
12000

방법 wait_for_memory_extraction

이 클라이언트가 시작한 이전 백그라운드 메모리 추출을 기다립니다.

이 메소드는 이 에이전트 메모리 구성 요소가 소유한 모든 스레드에서 이 OracleAgentMemory 인스턴스를 통해 이미 시작된 백그라운드 추출을 기다립니다. 이 대기가 시작된 후, 다른 에이전트 메모리 구성 요소에 의해 추출이 시작되었거나 다른 프로세스에서 추출이 실행될 때까지는 추출이 시작될 때까지 기다리지 않습니다. 추출 실패는 이 대기에 대해 완료된 것으로 계산됩니다.

예제

client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
)
client.wait_for_memory_extraction(timeout=10)

method wait_for_memory_extraction_async(비동기)

이전 백그라운드 메모리 추출을 비동기적으로 기다립니다.

이 메소드는 wait_for_memory_extraction()와 동일한 동작을 따릅니다.

예제

await client.wait_for_memory_extraction_async(timeout=10)

메모리 추출

클래스 oracleagentmemory.core.MemoryExtractionConfig

기준: object

자동 메모리 추출을 위한 그룹화된 설정입니다.

이 객체를 OracleAgentMemory, create_thread, get_thread 또는 update_thread에 전달하여 자동 추출을 구성합니다. 생략된 필드는 다음 더 넓은 설정에서 상속됩니다. 예를 들어, memory_extraction_frequency 없이 생성된 스레드는 에이전트 메모리 구성 요소 기본값을 사용하며 구성 요소 기본값은 SDK 기본값으로 돌아갑니다.

예제

from oracleagentmemory.core import MemoryExtractionConfig, MemoryExtractionMode
config = MemoryExtractionConfig(
    extract_memories=True,
    extraction_mode=MemoryExtractionMode.BACKGROUND,
)

클래스 oracleagentmemory.core.MemoryExtractionMode

기준: str, Enum

자동 메모리 추출 작업이 실행되는 시기를 제어합니다.

INLINE는 쓰기 메소드가 반환되기 전에 자동 추출을 실행합니다. BACKGROUND는 원시 쓰기가 성공하고 만기 추출 작업이 백그라운드에서 시도된 후 반환됩니다. 백그라운드 추출은 최선의 작업입니다. 파생된 메모리는 나중에 나타날 수도 있고 백그라운드 작업을 완료할 수 없는 경우에는 기록되지 않을 수도 있습니다.

배경 = '배경'

원시 메시지 지속성 후 돌아가서 백그라운드 작업에서 최선의 추출을 실행합니다.

인라인 = '인라인'

write 메소드가 반환되기 전에 추출을 실행합니다.

클래스 oracleagentmemory.core.BackgroundExtractionQueueFullBehavior

기준: str, Enum

백그라운드 추출이 시간에 대기열에 추가할 수 없을 때 발생하는 동작을 제어합니다.

= '삭제' 삭제

경고를 기록하고 대기열 용량을 사용할 수 없을 때 즉시 계속합니다.

WAIT_THEN_DROP = 'WAIT_THEN_DROP'

대기열 용량이 구성된 시간 초과까지 대기한 다음 경고를 기록하고 계속합니다.

WAIT_THEN_RAISE = 'WAIT_THEN_RAISE'

대기열 용량이 구성된 시간 초과까지 대기한 다음 TimeoutError를 발생시킵니다.