에이전트 메모리

이 페이지에서는 구체적인 Oracle AI Agent Memory 구현을 제공합니다.

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는 인덱스가 존재하는 후의 지속적인 유지 관리를 제어하며 첫번째 인덱스가 비동기적으로 생성되지 않습니다.

예제

다른 데이터베이스 사용자가 생성한 스키마에 액세스하려면 애플리케이션 DB 사용자에 대해 memory_rw_pool를 구성하고 memory_schema_owner를 소유 사용자의 따옴표로 묶이지 않은 데이터베이스 이름으로 설정합니다.

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),
)
pruned_search_client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
    pruner_llm=llm,
)
shared_client = OracleAgentMemory(
    connection=memory_rw_pool,
    embedder=embedder,
    llm=llm,
    schema_owner=memory_schema_owner,
)

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

방법 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'

method add_agent_async(비동기)

상담원 프로파일 레코드를 점포에 비동기식으로 추가합니다.

노트

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

예제

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

방법 add_image

클라이언트에 이미지 레코드를 추가합니다.

예제

image_id = client.add_image(
    b"image-bytes",
    description="Image description",
    mime_type=ImageMimeType.PNG,
    image_id="img-1",
    user_id="user-1",
)
image_id
'img-1'

method add_image_async(비동기)

구성된 저장소를 통해 하나의 독립형 이미지를 유지합니다.

description가 생략되거나 None인 경우 구성된 LLM이 캡션을 생성합니다.

방법 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(비동기)

메모리 시스템의 메모리를 비동기적으로 추가합니다.

예제

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

방법 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'

method add_user_async(비동기)

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

노트

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

예제

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
import asyncio
asyncio.run(client.add_user_async(
    "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()와 동일한 종료 동작을 따릅니다. 시간 초과가 만료되면 백그라운드 작업이 계속 실행되는 동안 반환될 수 있습니다.

예제

import asyncio
asyncio.run(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'

method create_thread_async(비동기)

스레드를 비동기적으로 만들고 등록합니다.

예제

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

방법 delete_agent

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

노트

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

예제

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

method delete_agent_async(비동기)

ID별로 비동기식으로 에이전트 프로파일 레코드를 삭제합니다.

노트

이 방법은 delete_agent()에 설명된 백그라운드 추출 대기 및 동시성 동작을 따릅니다.

예제

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
import asyncio
asyncio.run(client.add_agent_async("a-delete", "Support assistant"))
'a-delete'
asyncio.run(client.delete_agent_async("a-delete"))
1

방법 delete_image

식별자로 이미지 레코드를 삭제합니다.

method delete_image_async(비동기)

구성된 저장소를 통해 하나의 독립형 이미지를 삭제합니다.

방법 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_memory()에 문서화된 대상 백그라운드 추출 대기 및 동시성 동작을 따릅니다.

예제

import asyncio
memory_id = asyncio.run(client.add_memory_async(
    "Temporary memory", memory_id="mem-delete"
))
asyncio.run(client.delete_memory_async(memory_id))
1

식별자로 관계를 삭제하거나 끝점 튜플을 완료합니다.

relation_id가 제공되지 않은 경우 저장된 소스-대상 방향에서 모든 소스, 대상, 유형 및 관계 레이블 인수를 제공합니다.

예제

client.delete_record_link(relation_id="relation-id")
1

ID별 관계를 비동기적으로 삭제하거나 끝점 튜플을 완료합니다.

방법 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

method delete_thread_async(비동기)

스레드 식별자와 연관된 모든 레코드를 비동기적으로 삭제합니다.

노트

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

예제

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
import asyncio
thread = asyncio.run(client.create_thread_async(thread_id="c-delete"))
asyncio.run(client.delete_thread_async(thread.thread_id))
1

방법 delete_user

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

노트

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

예제

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

method delete_user_async(비동기)

식별자별로 비동기적으로 유저 프로파일 레코드를 삭제합니다.

노트

이 방법은 delete_user()에 설명된 백그라운드 추출 대기 및 동시성 동작을 따릅니다.

예제

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
import asyncio
asyncio.run(client.add_user_async("u-delete", "Prefers concise answers."))
'u-delete'
asyncio.run(client.delete_user_async("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="c2", user_id="u1")
loaded = client.get_thread("c2")
loaded.user_id
'u1'

method get_thread_async(비동기)

이전에 생성한 스레드를 비동기적으로 검색합니다.

노트

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

예제

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
import asyncio
created = asyncio.run(client.create_thread_async(
    thread_id="c2", user_id="u1"
))
loaded = asyncio.run(client.get_thread_async("c2"))
loaded.user_id
'u1'

저장된 두 레코드 간에 지시된 관계를 생성합니다.

현재 두 끝점은 메모리와 유사한 레코드("memory", "fact", "guideline" 또는 "preference")여야 합니다. 기본 제공 관계 유형은 "supersedes"("is_superseded_by"), "contradicts", "refines"("is_refined_by"), "supports"("is_supported_by") 및 "duplicates"입니다. "contradicts" 및 "duplicates"는 동일한 레이블을 역방향으로 사용합니다.

끝점 쌍에 대해 하나의 방향만 저장할 수 있습니다. opposite_relation_type는 대상에서 소스로 순회할 때 관계의 이름을 지정합니다. 예를 들어, new "supersedes" old인 경우 역순회는 old "is_superseded_by" new입니다.

예제

client.link_records(
    "fact-1", "fact", "memory-1", "memory", "supports"
)
'relation-id'

저장된 레코드 간에 유형화된 관계를 비동기적으로 생성합니다.

현재 두 끝점은 메모리와 유사한 레코드("memory", "fact", "guideline" 또는 "preference")여야 합니다. 기본 제공 관계 유형은 "supersedes"("is_superseded_by"), "contradicts", "refines"("is_refined_by"), "supports"("is_supported_by") 및 "duplicates"입니다. "contradicts" 및 "duplicates"는 동일한 레이블을 역방향으로 사용합니다.

방법 list_agents

지속 에이전트 프로파일 레코드를 나열합니다.

예제

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_agent("a1", "Support assistant", metadata={"source": "catalog"})
'a1'
[record.id for record in client.list_agents(metadata_filter={"source": "catalog"})]
['a1']

method list_agents_async(비동기)

지속 에이전트 프로파일 레코드를 비동기적으로 나열합니다.

예제

import anyio
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
async def main():
    await client.add_agent_async(
        "a1",
        "Support assistant",
        metadata={"source": "catalog"},
    )
    records = await client.list_agents_async(metadata_filter={"source": "catalog"})
    return [record.id for record in records]
anyio.run(main)
['a1']

방법 list_images

지속된 독립형 이미지 레코드를 나열합니다.

예제

images = client.list_images(user_id="u1", limit=10)
[image.id for image in images]
['img-1']

method list_images_async(비동기)

지속된 독립형 이미지 레코드를 비동기적으로 나열합니다.

예제

images = await client.list_images_async(
    user_id="u1",
    limit=10,
)
[image.id for image in images]
['img-1']

방법 list_memories

영구 메모리 유사 레코드를 나열합니다.

예제

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_memory("User likes pizza.", user_id="u1", memory_id="mem-1")
'mem-1'
[record.id for record in client.list_memories(user_id="u1", limit=10)]
['mem-1']

method list_memories_async(비동기)

영구 메모리 유사 레코드를 비동기적으로 나열합니다.

예제

import anyio
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
async def main():
    await client.add_memory_async("User likes pizza.", user_id="u1", memory_id="mem-1")
    records = await client.list_memories_async(user_id="u1", limit=10)
    return [record.id for record in records]
anyio.run(main)
['mem-1']

방법 list_messages

지속 채팅 메시지 레코드를 나열합니다.

예제

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
thread = client.create_thread(thread_id="c1", user_id="u1")
message_id = thread.add_messages([{"role": "user", "content": "Hello"}])[0]
[record.id for record in client.list_messages(thread_id="c1", limit=10)] == [message_id]
True

method list_messages_async(비동기)

지속 채팅 메시지 레코드를 비동기적으로 나열합니다.

예제

import anyio
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
async def main():
    thread = await client.create_thread_async(thread_id="c1", user_id="u1")
    message_ids = await thread.add_messages_async(
        [{"role": "user", "content": "Hello"}]
    )
    records = await client.list_messages_async(thread_id="c1", limit=10)
    return [record.id for record in records] == message_ids
anyio.run(main)
True

방법 list_threads

지속된 대화 스레드를 나열합니다.

예제

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.create_thread(thread_id="c1", user_id="u1").thread_id
'c1'
[record.thread_id for record in client.list_threads(user_id="u1", limit=10)]
['c1']

method list_threads_async(비동기)

지속된 대화 스레드를 비동기적으로 나열합니다.

예제

import anyio
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
async def main():
    await client.create_thread_async(thread_id="c1", user_id="u1")
    records = await client.list_threads_async(user_id="u1", limit=10)
    return [record.thread_id for record in records]
anyio.run(main)
['c1']

방법 list_users

지속된 사용자 프로파일 레코드를 나열합니다.

예제

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'
[record.id for record in client.list_users(metadata_filter={"source": "crm"})]
['u1']

method list_users_async(비동기)

지속된 사용자 프로파일 레코드를 비동기적으로 나열합니다.

예제

import anyio
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
async def main():
    await client.add_user_async(
        "u1",
        "Prefers concise answers.",
        metadata={"source": "crm"},
    )
    records = await client.list_users_async(metadata_filter={"source": "crm"})
    return [record.id for record in records]
anyio.run(main)
['u1']

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

노트

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

method search_async(비동기)

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

노트

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

방법 update_image

저장된 이미지 레코드를 식별자로 업데이트합니다.

노트

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

method update_image_async(비동기)

구성된 저장소를 통해 하나의 독립형 이미지를 업데이트합니다.

기존 바이트를 보존하려면 image를 생략합니다. image가 제공된 경우 mime_type를 제공해야 합니다. 기존 설명을 보존하려면 description를 생략합니다. None을 전달하여 구성된 LLM으로 새 설명을 생성합니다. 널이 아닌 설명이 직접 대체됩니다. 메타데이터, 시간 기록 및 만료 설정은 제공될 때 업데이트됩니다.

방법 update_memory

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

노트

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

method update_memory_async(비동기)

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

노트

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

예제

import asyncio
memory_id = asyncio.run(client.add_memory_async("Original memory"))
(
    asyncio.run(client.update_memory_async(
        memory_id, content="Updated memory"
    ))
    == memory_id
)
True

저장된 관계식의 변경 가능한 필드를 업데이트합니다.

생략된 값은 보존됩니다. relation_type가 내장 메모리 관계 유형으로 변경되면 고정 역방향 레이블이 opposite_relation_type를 대체합니다. timestamp 또는 metadata의 경우 None를 전달하여 해당 값을 지웁니다.

예제

client.update_record_link("relation-id", relation_type="supports")
1

저장된 관계식을 비동기적으로 업데이트합니다.

방법 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

method update_thread_async(비동기)

업데이트된 스레드 메타데이터와 지속 가능한 런타임 구성을 비동기적으로 유지합니다.

방법 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()와 동일한 동작을 따릅니다.

예제

import asyncio
asyncio.run(client.wait_for_memory_extraction_async(timeout=10))

이미지 입력 한도

클래스 oracleagentmemory.core.ImageInputLimitConfig

기준: object

원시 이미지 및 LLM 이미지 요청 제한을 구성합니다.

생략된 필드는 다음으로 광범위한 구성 범위에서 상속됩니다. 클라이언트 필드는 SDK 기본값을 상속하고 스레드별 필드는 클라이언트 구성을 상속합니다. 검증을 사용 안함으로 설정할 수 없으며 분석된 값은 SDK의 절대 최대값을 초과할 수 없습니다.

예제

from oracleagentmemory.core import ImageInputLimitConfig
config = ImageInputLimitConfig(
    max_raw_image_bytes=16 * 1024 * 1024,
    max_images_per_llm_request=200,
)

메모리 추출

클래스 oracleagentmemory.core.MemoryExtractionImageContext

기준: str, Enum

이미지가 자동 메모리 추출에 참여하는 방법을 선택합니다.

DISABLED는 추출 프롬프트에서 이미지 및 이미지 설명을 생략합니다. 이미지가 원본 이미지 부분을 보냅니다. CAPTION은 이미지 설명을 텍스트로 전송하며 선택된 모든 이미지에 공백이 아닌 설명이 있어야 합니다.

CAPTION = 'CAPTION'(캡션)

설명을 텍스트로 포함하고 선택된 모든 이미지에 대해 하나씩 필요합니다.

사용 안함 = 'DISABLED'

추출 프롬프트에 이미지 또는 이미지 설명을 포함하지 마십시오.

이미지 = 'IMAGE'

추출 프롬프트에 원본 이미지 부분을 포함합니다.

메모리 = 'MEMORY'

이미지별 메모리 추출은 현재 지원되지 않습니다.

클래스 oracleagentmemory.core.MemoryExtractionConfig

기준: object

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

이 객체를 OracleAgentMemory, create_thread, get_thread 또는 update_thread에 전달하여 자동 추출을 구성합니다. extraction_mode 및 백그라운드 대기열 설정은 자동 이미지 설명 생성을 제어합니다. 각 필드는 독립적으로 해결됩니다. 작업에 대해 제공된 값이 우선하고 그 뒤에 저장된 스레드 값, 클라이언트 값 및 SDK 기본값이 옵니다. 새 스레드와 독립형 스레드에 저장된 스레드 값이 없습니다.

예제

from oracleagentmemory.core import (
    MemoryExtractionImageContext,
    MemoryExtractionConfig,
    MemoryExtractionMode,
    MemoryLinkExtractionMode,
)
config = MemoryExtractionConfig(
    extract_memories=True,
    memory_extraction_image_context=MemoryExtractionImageContext.CAPTION,
    extraction_mode=MemoryExtractionMode.BACKGROUND,
    memory_link_extraction_mode=MemoryLinkExtractionMode.POST_EXTRACTION,
    memory_link_extraction_token_limit=8_000,
)

추출 또는 이미지 설명이 즉시 대기열에 추가할 수 없는 경우 수행할 작업

생략된 값은 DROP로 분석됩니다.

대기 모드에서 대기열 용량에 대해 백그라운드 작업이 대기하는 최대 시간(초)입니다.

생략된 값은 300.0초로 분석됩니다.

자동 새로고침 전 최신 적합한 요약 이후의 메시지입니다.

모든 검사 시 0보다 작거나 같은 값이 새로 고쳐집니다.

OAM이 스레드 읽기 및 추출 프롬프트에 대한 컨텍스트 요약을 유지 관리할지 여부입니다.

추출 및 이미지 설명이 인라인 또는 백그라운드 작업으로 실행되는지 여부입니다.

생략된 값은 BACKGROUND로 분석됩니다.

추출 실행 간 메시지입니다. 0 미만의 값은 모든 추가 후 추출됩니다.

이미지 표현; 생략은 스레드, 클라이언트, DISABLED로 분석됩니다.

추출된 메모리에 복사된 소스 메시지 메타데이터입니다.

프롬프트에 대한 입력 토큰 예산입니다. 1 미만의 값은 제한을 사용 안함으로 설정합니다.

추출 프롬프트에 사용되는 최근 메시지 창입니다. -1는 새 메시지만 사용합니다.

자동 링크 해결 프롬프트에 추가되는 선택적 호출자 지침입니다.

추출된 메모리에 대한 자동 링크 해결 방법

생략된 값은 POST_EXTRACTION로 분석됩니다.

POST_EXTRACTION 링크 분석에 대한 총 입력 토큰 예산입니다.

1 미만의 값은 제한을 사용 안함으로 설정합니다.

클래스 oracleagentmemory.core.MemoryExtractionMode

기준: str, Enum

자동 추출 및 이미지 설명이 실행되는 시기를 제어합니다.

INLINE는 쓰기 메소드가 반환되기 전에 파생된 작업을 완료합니다. BACKGROUND는 원시 쓰기가 성공한 후 해당 작업을 대기열에 넣으려고 시도합니다. 백그라운드 작업은 최선의 작업입니다. 생성된 설명 및 파생된 메모리는 나중에 나타날 수도 있고 완료할 수 없는 경우 작성되지 않을 수도 있습니다.

배경 = '배경'

원시 쓰기 후 백그라운드에서 파생된 작업을 실행합니다.

인라인 = '인라인'

쓰기가 반환되기 전에 추출 및 이미지 설명을 완료합니다.

클래스 oracleagentmemory.core.BackgroundExtractionQueueFullBehavior

기준: str, Enum

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

추출 관련 이름에도 불구하고 이 설정은 백그라운드 모드의 자동 이미지 설명 생성에도 적용됩니다.

= '삭제' 삭제

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

WAIT_THEN_DROP = 'WAIT_THEN_DROP'

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

WAIT_THEN_RAISE = 'WAIT_THEN_RAISE'

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