상점 및 스키마

이 페이지에서는 Oracle Agent 메모리 SDK에서 사용되는 코어 저장소 추상화 및 스키마 콘트롤을 제공합니다.

API 저장

클래스 oracleagentmemory.core.OracleMemoryStore

기준: IMemoryStore

OracleAgentMemory에서 사용되는 공통 저장소 인터페이스입니다.

저장소 구현은 텍스트 레코드를 지속하고 이에 대한 유사성 검색을 수행합니다. 동기 및 비동기 엔트리 포인트가 모두 정의되므로 상위 레벨의 API가 매장별 논리를 복제하지 않고도 일치하는 동기화/비동기 서피스를 노출할 수 있습니다.

방법 add

점포에 레코드를 추가합니다.

• 매개변수:
  • contents list[str | None] – 지속할 페이로드를 기록합니다. 텍스트 값은 index_texts 또는 embeddings가 제공되지 않는 한 포함에도 사용됩니다. 텍스트 값이 None인 경우 구현이 metadata["content"]로 폴백될 수 있습니다. 명시적 빈 문자열은 보존됩니다.
  • record_type str – 생성할 논리적 레코드 유형(예: "message", "memory", "guideline", "fact", "preference", "user_profile" 또는 "agent_profile")입니다.
  • index_texts list[str] – 포함/인덱싱에만 사용되는 선택적 대체 페이로드입니다. 제공된 경우 텍스트 입력과 맞춰야 합니다.
  • embeddings list[list[float]] | list[ndarray] – 텍스트 입력과 정렬된 사전 계산된 내장 벡터(선택 사항)입니다. 제공된 경우 저장소는 임베더를 호출하는 대신 직접 이러한 벡터를 사용해야 합니다. 제공하지 않을 경우 점포에 임베더가 첨부되어 있어야 합니다. 그렇지 않으면 오류가 발생합니다.
  • record_ids str | None | list[str | None] – 선택적인 호출자가 볼 수 있는 식별자입니다. 단일 문자열은 단일 레코드 삽입에 사용될 수 있지만 리스트는 텍스트 입력과 일치해야 합니다. 이 필드를 생략하면 생성된 식별자가 반환됩니다.
  • thread_ids str | None | list[str | None] – 삽입된 레코드와 연관된 선택적 스레드 식별자입니다. 스칼라 값은 정렬된 텍스트 입력을 통해 브로드캐스트될 수 있습니다.
  • user_ids str | None | list[str | None] – 삽입된 레코드와 연관된 선택적 사용자 식별자입니다. 스칼라 값은 정렬된 텍스트 입력을 통해 브로드캐스트될 수 있습니다.
  • agent_ids str | None | list[str | None] – 삽입된 레코드와 연관된 선택적 에이전트 식별자입니다. 스칼라 값은 정렬된 텍스트 입력을 통해 브로드캐스트될 수 있습니다.
  • roles str | None | list[str | None] – "user" 또는 "assistant"와 같은 선택적 메시지 역할입니다. 스칼라 값은 정렬된 텍스트 입력을 통해 브로드캐스트될 수 있습니다. record_type이 "message"인 경우에만 사용됩니다.
  • timestamps str | None | list[str | None] – 레코드와 함께 지속되는 선택적 이벤트 시간 기록입니다. 스칼라 값은 정렬된 텍스트 입력을 통해 브로드캐스트될 수 있습니다.
  • metadata dict[str, Any] | list[dict[str, Any] | None] | None – 선택적 호출자가 제공한 메타데이터 딕셔너리입니다. ""로 명시적으로 설정하지 않고 텍스트 값을 생략할 경우 메타데이터에 폴백 소스로 "content"가 포함될 수 있습니다.
  • **store_kwargs(임의) – 구체적 저장소로 전달된 구현별 쓰기 옵션입니다.
• 반환 유형: list[str]

주

호출자에 이미 하나 이상의 PendingRecordBatch 객체가 있는 경우 add_batches()를 사용합니다.

• 반환: 입력과 동일한 논리적 순서로 삽입된 레코드의 식별자입니다.
• 반품 유형: 목록[str]
• 매개변수:
  • 내용 list[str | None]
  • record_type str
  • index_texts list[str]
  • 임베딩 list[list[float]] | list[ndarray]
  • record_ids str | None | list[str | None]
  • thread_ids str | None | list[str | None]
  • user_ids str | None | list[str | None]
  • agent_ids str | None | list[str | None]
  • 역할 str | None | list[str | None]
  • 시간 기록 str | None | list[str | None]
  • 메타데이터 dict[str, Any] | list[dict[str, Any] | None] | None
  • store_kwargs Any

method add_agent(개요)

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

• 매개변수:
  • agent_id str – 에이전트 프로파일에 대한 안정적인 식별자입니다.
  • information str – 에이전트를 설명하는 자유 형식 텍스트입니다.
• 반품: 생성된 에이전트 프로파일 레코드의 식별자입니다.
• 반환 유형: str

method add_async(비동기)

점포에 행 지향 레코드를 비동기적으로 추가합니다.

동일한 인수를 사용하고 add()와 동일한 식별자를 반환합니다.

• 매개변수:
  • 내용 list[str | None]
  • record_type str
  • index_texts list[str]
  • 임베딩 list[list[float]] | list[ndarray]
  • record_ids str | None | list[str | None]
  • thread_ids str | None | list[str | None]
  • user_ids str | None | list[str | None]
  • agent_ids str | None | list[str | None]
  • 역할 str | None | list[str | None]
  • 시간 기록 str | None | list[str | None]
  • 메타데이터 dict[str, Any] | list[dict[str, Any] | None] | None
  • store_kwargs Any
• 반환 유형: list[str]

방법 add_batches

호출자가 준비한 논리적 배치를 저장소에 추가합니다.

• 매개변수:
  • batches(일괄 처리) list[PendingRecordBatch] – 유지할 완전히 준비된 논리적 일괄 처리입니다. 각 뱃치에는 record_type, 범위 값, 역할, 시간 기록 및 메타데이터와 같은 고유한 레코드별 필드가 포함되어야 합니다.
  • **store_kwargs(임의) – 구체적 저장소로 전달된 구현별 쓰기 옵션입니다.
• 반환: 입력 배치 및 행과 동일한 논리적 순서로 삽입된 레코드의 식별자입니다.
• 반품 유형: 목록[str]

예제

store.add_batches(
    [
        PendingRecordBatch(
            texts=["pizza batch"],
            record_type="memory",
            record_ids="mem-batch-docs",
        )
    ]
)
['mem-batch-docs']

method add_batches_async(비동기)

호출자가 준비한 논리적 배치를 저장소에 비동기적으로 추가합니다.

동일한 인수를 사용하고 add_batches()와 동일한 식별자를 반환합니다.

• 매개변수:
  • 일괄 처리 list[PendingRecordBatch]
  • store_kwargs Any
• 반환 유형: list[str]

method add_user(개요)

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

• 매개변수:
  • user_id str – 사용자 프로파일에 대한 안정적인 식별자입니다.
  • information str – 사용자를 설명하는 자유 형식 텍스트입니다.
• 반환: 생성된 사용자 프로파일 레코드의 식별자입니다.
• 반환 유형: str

method delete(개요)

식별자로 저장된 레코드 하나를 삭제합니다.

• 매개변수:
  • record_type str – 제거할 레코드의 논리적 유형입니다.
  • record_id str – 제거할 레코드의 식별자입니다.
  • cascade bool – True의 경우 동일한 삭제 작업 내에서 요청된 최상위 레벨 대상에 대해 저장소 지원 캐스케이딩 삭제 동작을 적용합니다. 이는 주로 추가 범위가 지정된 레코드를 소유하는 작업자 프로파일과 같은 대상에 사용됩니다. 예를 들어, 사용자 프로파일 또는 에이전트 프로파일 캐스케이드는 소유한 스레드 자체, 스레드 범위의 메시지 및 이러한 스레드와 함께 제거된 메모리 유사 레코드 및 메시지, 메모리, 지침, 팩트 또는 환경설정과 같은 나머지 직접 작업자 범위의 레코드를 삭제할 수 있습니다. 작업자-프로파일 삭제의 경우 일치하는 프로파일 행이 이미 없을 때 이 범위가 지정된 정리가 계속 실행될 수 있습니다.
• 반환: 삭제된 요청된 최상위 레벨 레코드 수(일반적으로 0 또는 1)입니다. 계단식 하위 행은 별도로 계산되지 않으므로 누락된 작업자 프로파일이 범위 지정 정리를 트리거하는 경우에도 0일 수 있습니다.
• 반품 유형: int

method delete_thread(개요)

스레드 및 연관된 저장된 데이터를 삭제합니다.

• 매개변수: thread_id str – 제거할 스레드의 식별자입니다.
• 반환: 삭제된 스레드 레코드 수(일반적으로 0 또는 1)입니다.
• 반품 유형: int

주

저장소에서 관리하는 스레드 및 스레드 범위의 레코드를 제거하기 위한 저장소 레벨 작업입니다. 메시지 레벨 삭제는 별도로 지속된 파생 레코드가 제거된다는 것을 의미하지 않기 때문에 보존 요구 사항이 소스 메시지와 파생된 스레드 범위 메모리 데이터를 모두 삭제하도록 요구할 때 스레드 삭제를 선호합니다.

method get(개요)

유형 및 식별자별로 하나의 저장된 레코드를 검색합니다.

• 매개변수:
  • record_type str – 검색할 레코드의 논리적 유형입니다.
  • record_id str – 검색할 레코드의 식별자입니다.
• 반환: 저장된 레코드가 있는 경우, 그렇지 않은 경우 None입니다.
• 반품 유형: 레코드 | 없음

method list(개요)

하나의 레코드 유형에 대해 저장된 레코드를 나열합니다.

• 매개변수:
  • record_type str – 열거할 논리적 레코드 유형입니다.
  • limit int | None – 반환할 최근 레코드의 최대 개수(선택 사항)입니다. 생략할 경우 구현은 MAX_LIST_LIMIT와 같은 안전한 상한을 적용할 수 있습니다. 해당 상한값을 사용 안함으로 설정하고 일치하는 모든 레코드를 반환하려면 None를 전달합니다.
  • thread_id str | None – 정확한 스레드 범위 필터입니다. 생략할 경우 필터링이 적용되지 않습니다. None로 설정된 경우 thread_id가 None인 레코드만 반환됩니다. 범위가 지정되지 않은 레코드 유형은 이 필터를 무시합니다.
  • user_id str | None – 정확한 사용자 범위 필터입니다. 생략할 경우 필터링이 적용되지 않습니다. None로 설정된 경우 user_id가 None인 레코드만 반환됩니다. 범위가 지정되지 않은 레코드 유형은 이 필터를 무시합니다.
  • agent_id str | None – 정확한 에이전트 범위 필터입니다. 생략할 경우 필터링이 적용되지 않습니다. None로 설정된 경우 agent_id가 None인 레코드만 반환됩니다. 범위가 지정되지 않은 레코드 유형은 이 필터를 무시합니다.
• 반품: 반환된 창 내에서 가장 오래된 항목부터 최신 항목 순으로 정렬된 레코드입니다.
• 반품 유형: 목록[레코드]

method list_thread_messages(개요)

한 스레드에 대해 저장된 메시지 내역을 나열합니다.

• 매개변수:
  • thread_id str – 메시지를 반환해야 하는 스레드의 식별자입니다.
  • last_n int | None – 포함할 최신 메시지 수(선택 사항)입니다. 생략하면 스레드에 대해 저장된 모든 메시지가 반환됩니다.
• 반환: 반환된 창 내에서 가장 오래된 항목부터 최신 항목 순으로 정렬된 메시지 레코드입니다.
• 반환 유형: 목록[MessageRecord]

method search(개요)

유사성으로 레코드를 검색합니다.

• 매개변수:
  • query str | None – 자연어 쿼리입니다. query_vector가 생략된 경우 제공해야 합니다.
  • query_vector list[float] | None – 미리 계산된 선택적 질의 포함입니다. query 및 query_vector 중 정확히 하나를 제공해야 합니다.
  • k int – 반환할 최대 결과 수. 명시적 값은 1 이상이어야 합니다.
  • thread_id str | None – 선택적 스레드 범위입니다.
  • user_id str | None – 선택적 사용자 및 에이전트 범위 필터입니다.
  • agent_id str | None – 선택적 사용자 및 에이전트 범위 필터입니다.
  • exact_user_match bool – 제공된 각 범위 식별자가 정확히 일치해야 하는지 여부입니다.
  • exact_agent_match bool – 제공된 각 범위 식별자가 정확히 일치해야 하는지 여부입니다.
  • exact_thread_match bool – 제공된 각 범위 식별자가 정확히 일치해야 하는지 여부입니다.
  • record_types set[str] | None – 포함할 선택적 레코드 유형 세트입니다.
  • metadata_filter dict[str, Any] | None – 선택적 부분 메타데이터 매핑입니다. 레코드는 저장된 메타데이터에 요청된 모든 키와 값이 포함된 경우에만 일치합니다. 중첩된 딕셔너리는 재귀적으로 일치됩니다. 목록 값은 반복적인 부분 집합 일치가 아닌 정확한 동등으로 일치되므로 목록 순서와 길이도 일치해야 합니다.
• 반환: 거리 증가에 따라 정렬된 (record, distance) 쌍입니다.
• 반환 유형: list[tuple[Record, float]]
• 라이즈: ValueError – k가 1보다 작은 경우

예제

store.add(
    ["Searchable abstract memory"],
    record_type="memory",
    record_ids="mem-search-abstract-docs",
)
['mem-search-abstract-docs']
store.search("Searchable", 1, record_types={"memory"})[0][0].id
'mem-search-abstract-docs'

스칼라 메타데이터 값을 필터링합니다.

store.add(
    ["pizza release"],
    record_type="memory",
    record_ids="mem-search-meta-source-docs",
    metadata={"source": "slack"},
)
['mem-search-meta-source-docs']
any(
    record.id == "mem-search-meta-source-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"source": "slack"},
    )
)
True

중첩 메타데이터에 대한 필터:

store.add(
    ["pizza review"],
    record_type="memory",
    record_ids="mem-search-meta-review-docs",
    metadata={"review": {"status": "open"}},
)
['mem-search-meta-review-docs']
any(
    record.id == "mem-search-meta-review-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"review": {"status": "open"}},
    )
)
True

순서를 포함하여 목록 값과 정확히 일치:

store.add(
    ["pizza tags"],
    record_type="memory",
    record_ids="mem-search-meta-tags-docs",
    metadata={"tags": ["prod", "urgent"]},
)
['mem-search-meta-tags-docs']
any(
    record.id == "mem-search-meta-tags-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"tags": ["prod", "urgent"]},
    )
)
True

method search_async(비동기)

비동기적으로 벡터 유사성으로 레코드를 검색합니다.

• 매개변수:
  • query str | None – search에서 허용된 동일한 질의 텍스트입니다.
  • k int – search에서 수락된 최대 결과 수와 동일합니다. 명시적 값은 1 이상이어야 합니다.
  • query_vector list[float] | None – search에서 허용되는 사전 계산된 질의 포함(선택 사항)과 동일합니다.
  • thread_id str | None – search에서 허용되는 동일한 선택적 범위 필터입니다.
  • user_id str | None – search에 허용된 것과 동일한 선택적 범위 필터입니다.
  • agent_id str | None – search에서 허용된 동일한 선택적 범위 필터입니다.
  • exact_user_match bool – search에서 수락된 것과 동일한 일치 플래그입니다.
  • exact_agent_match bool – search에서 수락된 것과 동일한 일치 플래그입니다.
  • exact_thread_match bool – search에서 수락한 것과 동일한 일치 플래그입니다.
  • record_types set[str] | None – search에서 허용되는 동일한 선택적 레코드 유형 필터입니다.
• 반환: 기본 search 호출에서 반환된 (record, distance) 쌍입니다.
• 반환 유형: 목록[튜플[레코드, 부동]]
• 라이즈: ValueError – k가 1보다 작은 경우

method update(개요)

저장된 레코드 콘텐츠, 포함 데이터 또는 메타데이터를 업데이트합니다.

• 매개변수:
  • record_type str – 업데이트할 레코드의 논리적 유형입니다.
  • record_id str – 업데이트할 레코드의 식별자입니다.
  • text str | None – 선택적 대체 컨텐츠입니다. 저장소가 지원하는 경우 저장된 텍스트를 명시적으로 지우려면 None를 전달합니다. 저장소는 또한 연관된 의미 상태를 지우고 동일한 호출에서 충돌하는 널이 아닌 index_text 또는 embedding 업데이트를 거부할 수 있습니다. 컨텐트를 변경하지 않고 그대로 두려면 인수를 생략합니다.
  • index_text str | None – 지속 텍스트를 변경하지 않고 저장된 벡터를 재계산하는 데 사용되는 선택적 포함 전용 페이로드입니다.
  • embedding list[float] | ndarray | None – 사전 계산된 임베딩 벡터(선택 사항)입니다. 제공된 경우 직접 사용되며 임베더 호출이 수행되지 않습니다. None를 전달하여 저장소에서 내장 임베딩을 지원할 때 명시적으로 지웁니다.
  • metadata dict[str, Any] | None – 선택적 대체 메타데이터 매핑입니다. 저장소가 지원하는 경우 메타데이터를 지우려면 None를 전달합니다.
• 반환: 업데이트된 레코드 수(일반적으로 0 또는 1)입니다. 요청된 논리적 식별자와 일치하는 저장된 레코드가 없을 경우 0를 반환합니다.
• 반품 유형: int
• 발생: ValueError – 업데이트 페이로드가 저장소에 대해 부적합한 경우(예: 모든 선택적 필드 생략 또는 충돌하는 의미 인수 제공)

Oracle DB 저장소

클래스 oracleagentmemory.core.OracleDBMemoryStore

기준: OracleMemoryStore

메시지, 메모리 및 작업자 프로파일에 대한 데이터베이스 지원 지속성

Oracle DB 저장소를 생성합니다.

• 매개변수:
  • embedder IEmbedder | None – 벡터화된 레코드 유형에 사용되는 Embedder입니다. 호출자가 항상 add, update 및 search에서 사전 계산된 벡터를 제공하는 경우 None일 수 있습니다.
  • pool Any – Oracle DB 연결 또는 풀입니다. 원시 연결을 전달하면 이 저장소 인스턴스에 대한 단일 세션 모드가 사용으로 설정됩니다. 동시 저장소 호출은 쓰기 작업에 사용되는 행 잠금 및 트랜잭션 가정을 보존하기 위해 로컬로 직렬화됩니다. 동시 요청에 대해 연결 풀을 사용합니다.
  • schema_policy SchemaPolicy | str – 스키마 설정 모드입니다. 기본값은 기존의 최신 관리 스키마가 필요하며 DDL 변경을 수행하지 않습니다. 누락된 객체를 채우려면 SchemaPolicy.CREATE_IF_NECESSARY를 사용하고, 관리 객체를 삭제하고 재생성하려면 SchemaPolicy.RECREATE를 사용합니다.
  • vector_dim int – VECTOR 열이 생성될 때 스키마 생성에 대한 차원을 포함합니다.
  • table_name_prefix str – 관리 테이블/인덱스 이름에 추가되는 선택적 접두어입니다.

방법 add

점포에 레코드를 추가합니다.

• 매개변수:
  • contents list[str | None] – 지속할 페이로드를 기록합니다. 텍스트 값은 index_texts 또는 embeddings가 제공되지 않는 한 포함에도 사용됩니다. 텍스트 값이 None인 경우 구현이 metadata["content"]로 폴백될 수 있습니다. 명시적 빈 문자열은 보존됩니다.
  • record_type str – 생성할 논리적 레코드 유형(예: "message", "memory", "guideline", "fact", "preference", "user_profile" 또는 "agent_profile")입니다.
  • index_texts list[str] – 포함/인덱싱에만 사용되는 선택적 대체 페이로드입니다. 제공된 경우 텍스트 입력과 맞춰야 합니다.
  • embeddings list[list[float]] | list[ndarray] – 텍스트 입력과 정렬된 사전 계산된 내장 벡터(선택 사항)입니다. 제공된 경우 저장소는 임베더를 호출하는 대신 직접 이러한 벡터를 사용해야 합니다. 제공하지 않을 경우 점포에 임베더가 첨부되어 있어야 합니다. 그렇지 않으면 오류가 발생합니다.
  • record_ids str | None | list[str | None] – 선택적인 호출자가 볼 수 있는 식별자입니다. 단일 문자열은 단일 레코드 삽입에 사용될 수 있지만 리스트는 텍스트 입력과 일치해야 합니다. 이 필드를 생략하면 생성된 식별자가 반환됩니다.
  • thread_ids str | None | list[str | None] – 삽입된 레코드와 연관된 선택적 스레드 식별자입니다. 스칼라 값은 정렬된 텍스트 입력을 통해 브로드캐스트될 수 있습니다.
  • user_ids str | None | list[str | None] – 삽입된 레코드와 연관된 선택적 사용자 식별자입니다. 스칼라 값은 정렬된 텍스트 입력을 통해 브로드캐스트될 수 있습니다.
  • agent_ids str | None | list[str | None] – 삽입된 레코드와 연관된 선택적 에이전트 식별자입니다. 스칼라 값은 정렬된 텍스트 입력을 통해 브로드캐스트될 수 있습니다.
  • roles str | None | list[str | None] – "user" 또는 "assistant"와 같은 선택적 메시지 역할입니다. 스칼라 값은 정렬된 텍스트 입력을 통해 브로드캐스트될 수 있습니다. record_type이 "message"인 경우에만 사용됩니다.
  • timestamps str | None | list[str | None] – 레코드와 함께 지속되는 선택적 이벤트 시간 기록입니다. 스칼라 값은 정렬된 텍스트 입력을 통해 브로드캐스트될 수 있습니다.
  • metadata dict[str, Any] | list[dict[str, Any] | None] | None – 선택적 호출자가 제공한 메타데이터 딕셔너리입니다. ""로 명시적으로 설정하지 않고 텍스트 값을 생략할 경우 메타데이터에 폴백 소스로 "content"가 포함될 수 있습니다.
  • **store_kwargs(임의) – 구체적 저장소로 전달된 구현별 쓰기 옵션입니다.
• 반환 유형: list[str]

주

호출자에 이미 하나 이상의 PendingRecordBatch 객체가 있는 경우 add_batches()를 사용합니다.

• 반환: 입력과 동일한 논리적 순서로 삽입된 레코드의 식별자입니다.
• 반품 유형: 목록[str]
• 매개변수:
  • 내용 list[str | None]
  • record_type str
  • index_texts list[str]
  • 임베딩 list[list[float]] | list[ndarray]
  • record_ids str | None | list[str | None]
  • thread_ids str | None | list[str | None]
  • user_ids str | None | list[str | None]
  • agent_ids str | None | list[str | None]
  • 역할 str | None | list[str | None]
  • 시간 기록 str | None | list[str | None]
  • 메타데이터 dict[str, Any] | list[dict[str, Any] | None] | None
  • store_kwargs Any

method add_async(비동기)

점포에 행 지향 레코드를 비동기적으로 추가합니다.

동일한 인수를 사용하고 add()와 동일한 식별자를 반환합니다.

• 매개변수:
  • 내용 list[str | None]
  • record_type str
  • index_texts list[str]
  • 임베딩 list[list[float]] | list[ndarray]
  • record_ids str | None | list[str | None]
  • thread_ids str | None | list[str | None]
  • user_ids str | None | list[str | None]
  • agent_ids str | None | list[str | None]
  • 역할 str | None | list[str | None]
  • 시간 기록 str | None | list[str | None]
  • 메타데이터 dict[str, Any] | list[dict[str, Any] | None] | None
  • store_kwargs Any
• 반환 유형: list[str]

방법 add_batches

호출자가 준비한 논리적 배치를 저장소에 추가합니다.

• 매개변수:
  • batches(일괄 처리) list[PendingRecordBatch] – 유지할 완전히 준비된 논리적 일괄 처리입니다. 각 뱃치에는 record_type, 범위 값, 역할, 시간 기록 및 메타데이터와 같은 고유한 레코드별 필드가 포함되어야 합니다.
  • **store_kwargs(임의) – 구체적 저장소로 전달된 구현별 쓰기 옵션입니다.
• 반환: 입력 배치 및 행과 동일한 논리적 순서로 삽입된 레코드의 식별자입니다.
• 반품 유형: 목록[str]

예제

store.add_batches(
    [
        PendingRecordBatch(
            texts=["pizza batch"],
            record_type="memory",
            record_ids="mem-batch-docs",
        )
    ]
)
['mem-batch-docs']

method add_batches_async(비동기)

호출자가 준비한 논리적 배치를 저장소에 비동기적으로 추가합니다.

동일한 인수를 사용하고 add_batches()와 동일한 식별자를 반환합니다.

• 매개변수:
  • 일괄 처리 list[PendingRecordBatch]
  • store_kwargs Any
• 반환 유형: list[str]

방법 add_agent

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

• 매개변수:
  • agent_id str – 에이전트 식별자입니다.
  • 정보 str – 에이전트에 대한 자유 형식 정보입니다. 이 텍스트는 프로파일 콘텐츠로 저장되며 RECORD_CHUNKS에 프로파일 포함 행을 작성하는 데 사용됩니다.
• 반환: 삽입된 에이전트 프로파일 레코드의 식별자입니다.
• 반환 유형: str

주

에이전트 프로파일 레코드의 범위가 지정되지 않았습니다. 삽입된 공용 레코드 식별자는 agent_id로 전달된 값과 동일합니다.

예제

store.add_agent("a-docs-agent", "Support assistant")
'a-docs-agent'

방법 add_user

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

• 매개변수:
  • user_id str – 사용자 식별자입니다.
  • information str – 사용자에 대한 자유 형식 정보입니다. 이 텍스트는 프로파일 콘텐츠로 저장되며 RECORD_CHUNKS에 프로파일 포함 행을 작성하는 데 사용됩니다.
• 반환: 삽입된 사용자 프로파일 레코드의 식별자입니다.
• 반환 유형: str

주

사용자 프로파일 레코드의 범위가 지정되지 않았습니다. 삽입된 공용 레코드 식별자는 user_id로 전달된 값과 동일합니다.

예제

store.add_user("u-docs-profile", "Prefers concise answers.")
'u-docs-profile'

방법 delete

식별자별로 하나의 관리 행과 해당 조각 행을 삭제합니다.

• 매개변수:
  • record_type str – 삭제할 레코드 유형 레이블입니다. 지원되는 유형은 "thread", "message", "memory", "guideline", "fact", "preference", "user_profile" 및 "agent_profile"입니다.
  • record_id str – 삭제할 식별자입니다.
  • 계단식 배열 bool – True인 경우 작업자 프로파일과 같은 지원되는 최상위 레벨 대상을 동일한 트랜잭션 내의 범위가 지정된 하위 행으로 확장합니다. 사용자 프로파일 또는 에이전트 프로파일 대상의 경우 먼저 소유한 스레드 행을 삭제하여 스레드 범위의 메시지 및 메모리 테이블 행을 제거한 다음 나머지 직접 작업자 범위의 메시지 및 메모리 유사 행(memory, guideline, fact, preference)을 삭제합니다. 이 범위의 정리는 일치하는 프로파일 행이 이미 없을 때 계속 실행됩니다.
• 반환: 제거된 요청된 최상위 레벨 대상 수(일반적으로 0 또는 1)입니다. 계단식 하위 행은 별도로 계산되지 않으므로 누락된 작업자 프로파일이 범위 지정 정리를 트리거하는 경우에도 0일 수 있습니다.
• 반품 유형: int

주

이 작업은 하나의 트랜잭션 내에서 실행됩니다. 지원되는 최상위 레벨 대상에 대해 cascade가 사용으로 설정된 경우 프로파일 삭제 및 모든 범위가 지정된 하위 삭제가 커밋되거나 함께 롤백됩니다.

예제

store.add(["Delete me"], record_type="memory", record_ids="mem-delete-docs")
['mem-delete-docs']
store.delete("memory", "mem-delete-docs")
1

방법 delete_thread

스레드 및 연관된 내장 행을 삭제합니다.

• 매개변수: thread_id str – 스레드 행, 종속 하위 행 및 명시적 청크 행 정리를 포함하여 행을 제거해야 하는 스레드 식별자입니다.
• 반환: 삭제된 스레드 행 수(0 또는 1)입니다.
• 반품 유형: int

주

스레드 범위의 계단식 정리가 필요한 경우 이 작업을 사용합니다. DB 지원 저장소에서 스레드를 삭제하면 연관된 메시지 및 메모리 행과 함께 관리되는 스레드 행과 검색을 위해 유지 관리되는 레코드 조각 행이 제거됩니다. 이는 원시 메시지 행만 제거하는 메시지 레벨 삭제보다 광범위합니다. 스레드 삭제는 동일한 트랜잭션의 일치하는 RECORD_CHUNKS 행과 함께 THREAD에서 참조된 종속 메시지 및 메모리 행을 제거합니다.

예제

store.delete_thread("c1")
0

메소드 get

저장된 레코드를 식별자로 검색합니다.

• 매개변수:
  • record_type str – 관리되는 행(예: "message", "memory", "guideline", "fact", "preference", "user_profile" 또는 "agent_profile")으로 분석되는 레코드 유형 레이블입니다.
  • record_id str – 조회할 식별자입니다.
• 반환: 발견된 경우 디코딩된 메타데이터로 레코드를 채웁니다. 그렇지 않은 경우 None입니다.
• 반품 유형: 레코드 | 없음

예제

store.add(["Remember this"], record_type="memory", record_ids="mem-get-docs")
['mem-get-docs']
store.get("memory", "mem-get-docs").id
'mem-get-docs'

방법 list

레코드 유형에 대한 지속 레코드를 열거합니다.

• 매개변수:
  • record_type str – 레코드 유형 레이블(예: "message", "memory", "guideline", "fact", "preference", "user_profile" 또는 "agent_profile")입니다.
  • limit int | None – 반환할 최대 레코드 수(선택 사항)입니다. 생략할 경우 저장소는 기본 목록 상한값을 사용합니다. 해당 상한값을 사용 안함으로 설정하고 일치하는 모든 레코드를 반환하려면 None를 전달합니다.
  • thread_id str | None – 정확한 스레드 범위 필터입니다. 생략할 경우 필터링이 적용되지 않습니다. None로 설정하면 thread_id가 SQL NULL인 행만 반환됩니다. 범위가 지정되지 않은 레코드 유형은 이 필터를 무시합니다.
  • user_id str | None – 정확한 사용자 범위 필터입니다. 생략할 경우 필터링이 적용되지 않습니다. None로 설정하면 user_id가 SQL NULL인 행만 반환됩니다. 범위가 지정되지 않은 레코드 유형은 이 필터를 무시합니다.
  • agent_id str | None – 정확한 에이전트 범위 필터입니다. 생략할 경우 필터링이 적용되지 않습니다. None로 설정하면 agent_id가 SQL NULL인 행만 반환됩니다. 범위가 지정되지 않은 레코드 유형은 이 필터를 무시합니다.
  • metadata_filter dict[str, Any] | None – 메타데이터 필터입니다. 생략할 경우 필터링이 적용되지 않습니다. None로 설정하면 저장된 메타데이터가 없는 레코드만 반환됩니다. dict로 설정하면 저장된 메타데이터에 요청된 모든 키와 값이 포함되어야 합니다. 중첩된 딕셔너리는 재귀적으로 일치됩니다. 목록 값은 반복적인 부분 집합 일치가 아닌 정확한 동등으로 일치되므로 목록 순서와 길이도 일치해야 합니다.
• 반품: 삽입 순서별로 정렬된 레코드입니다.
• 반품 유형: list[레코드]

주

"user_profile" 및 "agent_profile"는 범위가 지정되지 않은 레코드 유형입니다. 해당 레코드 유형의 경우 thread_id, user_id 및 agent_id가 무시되고 작업자 ID가 record.id에 유지됩니다.

예제

store.add(
    ["First listed", "Second listed"],
    record_type="memory",
    record_ids=["mem-list-docs-1", "mem-list-docs-2"],
)
['mem-list-docs-1', 'mem-list-docs-2']
[record.id for record in store.list("memory", limit=2)]
['mem-list-docs-1', 'mem-list-docs-2']
store.add_user("u-list-docs", "Prefers concise answers.")
'u-list-docs'
any(
    record.id == "u-list-docs"
    for record in store.list("user_profile", user_id=None, limit=10)
)
True

방법 list_thread_messages

스레드에 대한 지속 메시지를 반환합니다.

• 매개변수:
  • thread_id str – 메시지를 반환해야 하는 스레드 식별자입니다.
  • last_n int | None – 반환할 가장 최근 메시지 수(선택 사항)입니다.
• 반환: 삽입 순서별로 정렬된 메시지 레코드입니다.
• 반환 유형: list[MessageRecord]

예제

store.list_thread_messages("c1")
[]

방법 search

유사성으로 레코드를 검색합니다.

• 매개변수:
  • query str | None – 자연어 쿼리입니다. query_vector가 생략된 경우 제공해야 합니다.
  • query_vector list[float] | None – 미리 계산된 선택적 질의 포함입니다. 정확히 query 및 query_vector 중 하나를 제공해야 합니다.
  • k int – 반환할 최대 결과 수. 명시적 값은 1 이상이어야 합니다.
  • thread_id str | None – 선택적 스레드 범위 식별자입니다. exact_thread_match=False는 스레드 차원을 제약 없는 상태로 유지합니다. exact_thread_match=True는 제공된 thread_id와 정확히 일치합니다. thread_id=None인 경우 스레드 차원에서 범위가 지정되지 않은 레코드만 일치합니다.
  • user_id str | None – 선택적 사용자 및 에이전트 범위 식별자입니다. 해당 exact_*_match=False 플래그는 해당 차원을 제약 없는 상태로 유지합니다. exact_*_match=True는 제공된 ID와 정확히 일치합니다. ID가 None인 경우 해당 차원에서 범위가 지정되지 않은 레코드만 일치합니다.
  • agent_id str | None – 선택적 사용자 및 에이전트 범위 식별자입니다. 해당 exact_*_match=False 플래그는 해당 차원을 제약 없는 상태로 유지합니다. exact_*_match=True는 제공된 ID와 정확히 일치합니다. ID가 None인 경우 해당 차원에서 범위가 지정되지 않은 레코드만 일치합니다.
  • exact_user_match bool – 각 범위 식별자가 정확히 일치해야 하는지 여부입니다. False는 해당 차원을 제약 없는 상태로 둡니다. True는 제공된 값과 정확히 일치합니다. 해당 값이 None인 경우 해당 차원의 범위가 지정되지 않은 레코드만 일치합니다.
  • exact_agent_match bool – 각 범위 식별자가 정확히 일치해야 하는지 여부입니다. False는 해당 차원을 제약 없는 상태로 둡니다. True는 제공된 값과 정확히 일치합니다. 해당 값이 None인 경우 해당 차원의 범위가 지정되지 않은 레코드만 일치합니다.
  • exact_thread_match bool – 각 범위 식별자가 정확히 일치해야 하는지 여부입니다. False는 해당 차원을 제약 없는 상태로 둡니다. True는 제공된 값과 정확히 일치합니다. 해당 값이 None인 경우 해당 차원의 범위가 지정되지 않은 레코드만 일치합니다.
  • record_types set[str] | None – 포함할 검색 가능한 레코드 유형의 선택적 세트입니다. 생략할 경우 DB 검색에는 메시지, 메모리 테이블 행 및 작업자 프로파일이 포함됩니다. Actor 프로파일은 information 페이로드를 제공하는 반면 메시지 및 메모리 행은 content 페이로드를 제공합니다. 검색 중 프로파일 레코드 유형은 적용 가능한 범위 차원에 대한 작업자 식별자를 사용하고 나머지 범위 차원은 None로 작동합니다.
  • metadata_filter dict[str, Any] | None – 선택적 부분 메타데이터 매핑입니다. 레코드는 저장된 메타데이터에 요청된 모든 키와 값이 포함된 경우에만 일치합니다. 중첩된 딕셔너리는 반복적으로 일치됩니다. 목록 값은 반복적인 부분 집합 일치가 아닌 정확한 동등으로 일치되므로 목록 순서와 길이도 일치해야 합니다.
• 반환: 거리 증가에 따라 정렬된 (record, distance) 쌍입니다.
• 반환 유형: list[tuple[Record, float]]
• 라이즈: ValueError – k가 1보다 작은 경우

예제

store.add(
    ["pizza preference"],
    record_type="memory",
    record_ids="mem-search-docs",
    thread_ids="c-search-docs",
)
['mem-search-docs']
results = store.search(
    "pizza",
    1,
    thread_id="c-search-docs",
    exact_thread_match=True,
    record_types={"memory"},
)
results[0][0].id
'mem-search-docs'

스칼라 메타데이터 값을 필터링합니다.

store.add(
    ["pizza release"],
    record_type="memory",
    record_ids="mem-search-meta-source-docs",
    metadata={"source": "slack"},
)
['mem-search-meta-source-docs']
any(
    record.id == "mem-search-meta-source-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"source": "slack"},
    )
)
True

중첩 메타데이터에 대한 필터:

store.add(
    ["pizza review"],
    record_type="memory",
    record_ids="mem-search-meta-review-docs",
    metadata={"review": {"status": "open"}},
)
['mem-search-meta-review-docs']
any(
    record.id == "mem-search-meta-review-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"review": {"status": "open"}},
    )
)
True

순서를 포함하여 목록 값과 정확히 일치:

store.add(
    ["pizza tags"],
    record_type="memory",
    record_ids="mem-search-meta-tags-docs",
    metadata={"tags": ["prod", "urgent"]},
)
['mem-search-meta-tags-docs']
any(
    record.id == "mem-search-meta-tags-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"tags": ["prod", "urgent"]},
    )
)
True

method search_async(비동기)

비동기적으로 벡터 유사성으로 레코드를 검색합니다.

• 매개변수:
  • query str | None – search에서 허용된 동일한 질의 텍스트입니다.
  • k int – search에서 수락된 최대 결과 수와 동일합니다. 명시적 값은 1 이상이어야 합니다.
  • query_vector list[float] | None – search에서 허용되는 사전 계산된 질의 포함(선택 사항)과 동일합니다.
  • thread_id str | None – search에서 허용되는 동일한 선택적 범위 필터입니다.
  • user_id str | None – search에 허용된 것과 동일한 선택적 범위 필터입니다.
  • agent_id str | None – search에서 허용된 동일한 선택적 범위 필터입니다.
  • exact_user_match bool – search에서 수락된 것과 동일한 일치 플래그입니다.
  • exact_agent_match bool – search에서 수락된 것과 동일한 일치 플래그입니다.
  • exact_thread_match bool – search에서 수락한 것과 동일한 일치 플래그입니다.
  • record_types set[str] | None – search에서 허용되는 동일한 선택적 레코드 유형 필터입니다.
• 반환: 기본 search 호출에서 반환된 (record, distance) 쌍입니다.
• 반환 유형: 목록[튜플[레코드, 부동]]
• 라이즈: ValueError – k가 1보다 작은 경우

방법 update

저장된 레코드 콘텐츠, 조각 임베딩 및 메타데이터 값을 업데이트합니다.

• 매개변수:
  • record_type str – 수정 중인 행의 레코드 유형 레이블(예: "message", "memory", "guideline", "fact", "preference", "user_profile" 또는 "agent_profile")
  • record_id str – 업데이트할 저장된 행의 식별자입니다.
  • text str | None – content 열에 유지되는 선택적 대체 텍스트입니다. None를 전달하여 저장된 텍스트를 지우고 저장된 임베딩을 지웁니다. 동일한 호출에서 None 또는 생략된 의미 인수만 전달합니다. 해당 레코드에 대한 조각 임베딩을 지우는 동안 명시적 빈 콘텐츠를 보존하려면 ""를 전달합니다. 생략할 경우 기존 콘텐츠는 변경되지 않은 상태로 유지됩니다.
  • index_text str | None – 선택적 포함 전용 페이로드입니다. 생략할 경우 text가 포함됩니다.
  • embedding list[float] | ndarray | None – 사전 계산된 임베딩 벡터(선택 사항)입니다. 제공된 경우 직접 사용되며 임베더 호출이 수행되지 않습니다. None를 전달하여 저장된 임베딩을 지웁니다.
  • 메타데이터 dict[str, Any] | None – JSON으로 직렬화되고 metadata에 저장된 선택적 메타데이터 매핑입니다.
• 반환: 업데이트된 행 수(0 또는 1)입니다. record_type 및 record_id와 일치하는 논리적 레코드가 없는 경우 0를 반환합니다.
• 반품 유형: int
• 발생: ValueError – record_type가 지원되지 않는 경우, 업데이트 페이로드가 제공되지 않은 경우 또는 의미 업데이트 인수가 호환되지 않는 경우입니다.

예제

store.add(["Original note"], record_type="memory", record_ids="mem-update-docs")
['mem-update-docs']
store.update("memory", "mem-update-docs", text="Updated note")
1
store.get("memory", "mem-update-docs").content
'Updated note'

스키마 정책

클래스 oracleagentmemory.core.SchemaPolicy

기준: str, Enum

Oracle DB 저장소에 대한 스키마 생성 정책입니다.

필수_기존

전체 관리 스키마가 존재하고 최신 상태인지 검증합니다. DB 객체를 생성하거나 수정하지 마십시오.

비어 있는 경우 생성_IF_EMPT

관리되는 객체가 없으면 부트스트랩 스키마입니다. 객체가 존재하는 경우 완전한 최신 관리 스키마가 필요합니다.

CREATE_IF_NE REQUIRED

메타데이터를 포함하여 누락된 관리 객체만 생성합니다.

재생성

관리되는 모든 스키마 객체를 삭제하고 재생성합니다. 이것은 파괴적입니다.