에이전트 메모리
이 페이지에서는 구체적인 Oracle AI 에이전트 메모리 구현을 보여줍니다.
Oracle 에이전트 메모리
클래스 oracleagentmemory.core.OracleAgentMemory
기준: IAgentMemory
Oracle DB 또는 호출자가 제공한 저장소에서 지원하는 에이전트 메모리 클라이언트입니다.
메모리 클라이언트를 만듭니다.
- 매개변수:
- store
OracleMemoryStore– 미리 구성된 저장소 인스턴스(선택사항)입니다. 제공된 경우 클라이언트는 자체 저장소를 인스턴스화하는 대신 이 저장소를 직접 사용합니다. 이는 호출자가OracleAgentMemory에 표시된 생성자 옵션 이외의 저장소 구성을 필요로 하는 경우에 유용합니다. - connection
object– 선택적 Oracle DB 연결/풀입니다. 제공된 경우 DB 저장소가 사용됩니다. 원시 연결을 전달하면 이 클라이언트 Instance에 대해 단일 세션 모드가 활성화되므로 동시 요청에서는 대신 연결 풀을 사용해야 합니다. 생략할 경우 호출자는 명시적store를 전달해야 합니다. - embedder
IEmbedder | str– Embedder 구현 인스턴스 또는 LiteLLM 포함 모델 식별자입니다. 생략할 경우 임베더가 연결되지 않으며 호출자는 하위 레벨 저장소 API를 통해 사전 계산된 벡터를 제공해야 합니다. - LLM
ILlm– 메모리 추출 및/또는 컨텍스트 요약을 위해 스레드에서 사용되는 선택적 LLM 어댑터입니다. 기본적으로 이 클라이언트에서 생성되거나 로드된 스레드에는 LLM이 필요하므로 영구 메모리에 대한 최근 메시지를 채울 수 있습니다. 여기에llm를 전달하거나, 나중에create_thread에 제공하거나,extract_memories=False로 옵트아웃하십시오. - extract_memories
bool–True인 경우 이 클라이언트에 의해 생성되거나 로드된 스레드에 LLM이 필요하며 자동 메모리 추출이 사용으로 설정된 상태로 유지됩니다. 자동 메모리 추출을 사용 안함으로 설정하고 해당 스레드가 LLM 없이 작동하도록 허용하려면False로 설정합니다. 기본값은True이므로 추출 LLM 누락이 빠르게 실패합니다. - schema_policy
SchemaPolicy | str–connection에서 DB 저장소를 구성할 때만 사용되는 DB 스키마 설정 정책입니다. 기본값은SchemaPolicy.REQUIRE_EXISTING입니다. - table_name_prefix
str–connection에서 DB 저장소를 구성할 때만 사용되는 선택적 DB 테이블/인덱스 접두어입니다.
- store
- 확장: ValueError – 충돌하는 저장소 구성(예:
store및connection전달, DB 연결 없이 DB 특정 옵션 또는store와connection모두 생략)이 제공되는 경우
예제
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
connection=db_pool,
embedder=embedder,
llm=llm,
)
read_only_client = OracleAgentMemory(
connection=db_pool,
embedder=embedder,
extract_memories=False,
)
방법 add_agent
상점에 에이전트 프로파일 레코드를 추가합니다.
- 매개변수:
- agent_id
str– 에이전트 식별자입니다. - 정보
str– 에이전트에 대한 자유 형식 정보입니다.
- agent_id
- 반환: 저장된 에이전트 프로파일의 식별자입니다.
- 반환 유형: str
주
에이전트 프로파일 레코드는 클라이언트 레벨 저장소에 저장됩니다.
예제
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
connection=db_pool,
embedder=embedder,
llm=llm,
)
client.add_agent("a1", "Support assistant")
'a1'
방법 add_memory
표시된 사용자, 에이전트 및 스레드에 기인한 메모리를 메모리 시스템에 추가합니다.
- 매개변수:
- content
str– 지속할 메모리 컨텐츠입니다. - user_id
str– 저장된 메모리와 연관된 선택적 범위 식별자입니다. - agent_id
str– 저장된 메모리와 연관된 선택적 범위 식별자입니다. - thread_id
str– 저장된 메모리와 연관된 선택적 범위 식별자입니다. - memory_id
str– 이 메모리 행에 대해 선택적인 호출자가 제공하는 안정적인 식별자입니다. - **store_kwargs(임의) – 보조 기억 장치로 전달된 저장소별 쓰기 옵션입니다.
- content
- 반환: 삽입된 메모리 레코드의 식별자입니다.
- 반환 유형: str
예제
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'
방법 add_user
점포에 사용자 프로파일 레코드를 추가합니다.
- 매개변수:
- user_id
str– 사용자 식별자입니다. - information
str– 사용자에 대한 자유 형식 정보입니다.
- user_id
- 반환: 저장된 사용자 프로파일의 식별자입니다.
- 반환 유형: str
주
사용자 프로파일 레코드는 특정 스레드에 연결되지 않은 클라이언트 레벨 저장소에 저장됩니다.
예제
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
connection=db_pool,
embedder=embedder,
llm=llm,
)
client.add_user("u1", "Prefers concise answers.")
'u1'
방법 create_thread
스레드를 만들고 등록합니다.
- 매개변수:
- thread_id
str– 스레드 식별자입니다. 생략할 경우 새 항목이 생성됩니다. - user_id
str– 이 스레드 레코드에 첨부된 사용자 식별자입니다. 생략할 경우 새 항목이 생성됩니다. - agent_id
str– 이 스레드 레코드에 연결된 에이전트 식별자입니다. 생략할 경우 새 항목이 생성됩니다. - LLM
ILlm– 이 스레드에 대한 선택적 LLM 대체입니다. 생략할 경우 구성 시 구성된 클라이언트 레벨 LLM이 사용됩니다. 기본적으로 클라이언트 또는 스레드는 자동 메모리 추출을 실행할 수 있도록 LLM을 제공해야 합니다. 해당 요구 사항을 옵트아웃하려면 여기 또는 클라이언트에서extract_memories=False를 설정합니다. - extract_memories
bool– 자동 메모리 추출을 위한 선택적 스레드별 대체입니다.True인 경우 이 스레드에는 자동 추출을 실행할 수 있도록 LLM이 필요합니다. 이 스레드에 대한 자동 추출을 사용 안함으로 설정하고 LLM 없이 작업을 허용하려면False로 설정합니다. 생략할 경우 클라이언트 레벨extract_memories설정이 사용됩니다. - max_message_token_length
int– 메모리 추출 및 컨텍스트 요약 업데이트 중 잘림 또는 요약 전의 최대 프롬프트 시간 메시지 크기입니다. 저장된 메시지 내용은 변경되지 않습니다. 생략할 경우 기본값은15_000토큰입니다. - message_shortening_input_token_limit
int– 대형 프롬프트 시간 메시지 복사본을 줄일 때 LLM에 보낸 메시지 발췌 내용의 최대 크기(토큰)입니다. 생략할 경우 기본값은30_000토큰입니다. - memory_extraction_window
int– 메모리 추출 중 포함할 최근 메시지 수입니다. 새로 추가된 메시지의 전체 일괄 처리를 사용하여add_messages호출당 하나의 추출을 수행하려면-1으로 설정합니다. 생략할 경우 기본값은-1입니다. - context_summary_update_frequency
int– 컨텍스트 요약 새로고침 빈도입니다. 새로 추가된 메시지의 전체 일괄 처리를 사용하여add_messages호출당 하나의 요약 업데이트를 수행하려면-1로 설정합니다.add_messages동안 새로 고친 스레드 요약 메타데이터에 대해 동일한 주기가 재사용됩니다. 생략할 경우 기본값은4입니다. - memory_extraction_frequency
int– 메모리 추출 업데이트 빈도입니다. 새로 추가된 메시지의 전체 일괄 처리를 사용하여add_messages호출당 하나의 추출을 수행하려면-1으로 설정합니다. 생략할 경우 기본값은-1입니다. - memory_extraction_token_limit
int– 토큰의 최대 추출 프롬프트 크기입니다. 생략할 경우 기본값은100_000입니다. - enable_context_summary
bool– 이 스레드에 대해 실행 중인 컨텍스트 요약을 유지할지 여부입니다. - **kwargs(임의) – 추가 구현별 스레드 옵션입니다.
- thread_id
- 반품:
OracleThread. - 반품 유형: OracleThread
- Raises: ValueError – 자동 메모리 추출에 사용 가능한 LLM이 없고 스레드 및 클라이언트가
extract_memories=False로 구성되지 않은 경우입니다.
예제
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_memory
식별자별로 메모리 레코드를 삭제합니다.
- 매개변수: memory_id
str– 메모리 식별자입니다. - 반환: 삭제된 메모리 행 수(
0또는1)입니다. - 반품 유형: int
예제
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
방법 delete_thread
스레드 식별자와 연관된 모든 레코드를 삭제합니다.
- 매개변수:
- thread_id
str– 삭제할 스레드 식별자입니다. - allow_non_existing
bool–True에서 누락된 스레드를 삭제하면 no-op으로 처리됩니다.
- thread_id
- 반환: 삭제된 스레드 행 수(
0또는1)입니다. - 반품 유형: int
예제
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
방법 get_thread
이전에 생성한 스레드를 검색합니다.
- 매개변수:
- thread_id
str– 스레드를 만들 때 사용되는 식별자입니다. - LLM
ILlm– 재개설된 스레드에 대한 선택적 LLM 대체입니다. 생략할 경우 구성 시 구성된 클라이언트 레벨 LLM이 사용됩니다. - extract_memories
bool– 재개설된 스레드에서 자동 메모리 추출을 위한 선택적 대체입니다. 생략할 경우 클라이언트 레벨extract_memories설정이 사용됩니다. - max_message_token_length
int– 메모리 추출 및 컨텍스트 요약 업데이트 중 잘라내기 또는 요약 전 최대 프롬프트 시간 메시지 크기에 대한 선택적 대체입니다. 저장된 메시지 내용은 변경되지 않습니다. - message_shortening_input_token_limit
int– 대형 프롬프트 시간 메시지 복사본을 줄일 때 LLM으로 보낸 메시지 발췌 내용의 최대 크기(토큰)에 대한 선택적 대체입니다. - memory_extraction_window
int– 메모리 추출 중 사용된 최근 메시지 수에 대한 선택적 대체입니다. - context_summary_update_frequency
int– 컨텍스트 요약 새로 고침 빈도에 대한 선택적 대체입니다. - memory_extraction_frequency
int– 메모리 추출 업데이트 빈도에 대한 선택적 대체입니다. - memory_extraction_token_limit
int– 최대 추출 프롬프트 크기(토큰)에 대한 선택적 대체입니다. - enable_context_summary
bool– 재개설된 스레드가 실행 중인 컨텍스트 요약을 유지해야 하는지 여부에 대한 선택적 대체입니다.
- thread_id
- 반환: 저장소 메타데이터에서 재구성된 스레드 핸들입니다.
- 반품 유형: OracleThread
- 발생 값:
- KeyError – 이 클라이언트 인스턴스에서 스레드 ID를 알 수 없는 경우입니다.
- ValueError – 자동 메모리 추출에 사용할 수 있는 LLM이 없고 클라이언트가
extract_memories=False로 구성되지 않은 경우
주
명시적 호출당 재정의가 우선합니다. 런타임 대체가 생략되면 재개설된 스레드는 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'