컨텍스트 카드 콘텐츠 사용자정의

컨텍스트 카드는 에이전트가 응답을 생성할 때 사용할 수 있는 대화에 대한 간단한 컨텍스트를 제공합니다. 대화 스레드 요약, 관련 저장된 메시지 및 관련 메모리를 포함할 수 있습니다.

이 설명서에서는 Oracle AI Agent Memory 컨텍스트 카드에 반환된 콘텐츠를 사용자정의하는 방법에 대해 설명합니다.

get_context_card()에서 반환된 컨텍스트 카드에는 검색 항목 및 관련 레코드도 포함될 수 있습니다. 상담원이 긴 대화에서 연속성이 필요하지만 모델로 다시 전송된 전체 성적 증명서가 필요하지 않은 경우 컨텍스트 카드를 사용합니다. 이렇게 하면 입력 토큰 사용량을 줄이고 에이전트에 초점을 맞추고 프롬프트 컨텍스트의 관련 메모리를 맨 앞에 배치하여 일부 에이전트 레벨 도구 호출의 필요성을 줄일 수 있습니다.

LangGraph를 사용한 전체 프롬프트 압축 워크플로우는 Oracle Agent Memory Short-Term APIs with LangGraph를 참조하십시오. API 세부정보는 OracleThread 및 컨텍스트 카드를 참조하십시오.

참고: 기본 검색 결과에 레코드 유형의 올바른 조합이 포함되지 않은 경우 컨텍스트 카드 사용자정의를 사용합니다. 예를 들어, 일반 팩트가 결과를 지배하는 경우 응용 프로그램은 사용자 기본 설정 또는 응답 지침에 대한 공간을 예약할 수 있습니다.

검색 및 컨텍스트 카드에 대한 결과 제한, 순위 재지정, 제거 또는 토큰 예산을 구성하려면 검색 결과 관련성 향상을 참조하십시오.

레코드 유형별 요청 최소 결과

기본적으로 컨텍스트 카드 검색은 모든 메모리 유사 레코드 유형을 한 번에 검색합니다. 예를 들어 팩트 또는 일반 메모리가 기본 설정이나 지침을 혼잡하게 만드는 경우 min_relevant_results_by_type를 전달하여 특정 레코드 유형에 대한 최소 개수를 요청합니다.

import oracledb

from oracleagentmemory.core import MemoryExtractionConfig, SchemaPolicy
from oracleagentmemory.core.embedders.embedder import Embedder
from oracleagentmemory.core.llms.llm import Llm
from oracleagentmemory.core.oracleagentmemory import OracleAgentMemory

embedder = Embedder(model="YOUR_EMBEDDING_MODEL")
llm = Llm(model="provider/model_id")
db_pool = oracledb.SessionPool(
    user="YOUR DB USER",
    password="YOUR DB PASSWORD",
    dsn="localhost:1521/...",
)
memory_store_id = "T_CARD_CONTENT"

memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_store_id=memory_store_id
)

thread = memory.create_thread(
    thread_id="context_card_customization_demo",
    user_id="user_123",
    agent_id="assistant_456",
    memory_extraction_config=MemoryExtractionConfig(
        memory_extraction_custom_instructions=(
            "Extract restaurant preferences as preference records and assistant "
            "response-style instructions as guideline records."
        )
    ),
)
thread.add_messages(
    [
        {
            "role": "user",
            "content": "I need vegetarian dinner recommendations for Friday.",
        },
        {
            "role": "assistant",
            "content": "I can compare concise options and tradeoffs.",
        },
    ]
)

card = thread.get_context_card(
    max_relevant_results=6,
    min_relevant_results_by_type={
        "preference": 1,
        "guideline": 1,
        "message": 1,
    },
)

prompt_context = card.content
print(prompt_context)

렌더링된 카드는 XML과 유사한 프롬프트 텍스트입니다. 정확한 레코드는 저장된 데이터에 따라 다르지만 <relevant_information> 섹션에는 all-memory-types 검색의 나머지 결과보다 먼저 요청된 유형이 포함될 수 있습니다.

<context_card>
  <summary>
    User is planning dinner recommendations.
  </summary>
  <topics>
    <topic>pizza planning</topic>
    <topic>dinner</topic>
  </topics>
  <relevant_information>
    <preference>
      <content>User prefers vegetarian restaurants.</content>
    </preference>
    <guideline>
      <content>Offer concise recommendations with clear tradeoffs.</content>
    </guideline>
    <memory>
      <content>User is comparing pizza places for Friday.</content>
    </memory>
  </relevant_information>
  <recent_messages>
    ...
  </recent_messages>
</context_card>

최소값은 최선의 노력이다. 요청된 유형에 일치하는 레코드가 충분하지 않으면 통화가 계속 성공합니다. 지원되는 메모리 유사 레코드 유형의 일치 항목은 남아 있는 결과 슬롯을 사용할 수 있습니다. 최종 관련 레코드는 항상 max_relevant_results로 제한됩니다.

지원되는 키는 "memory", "fact", "guideline", "preference" 및 "message"입니다. 메시지 결과는 현재 스레드에서만 검색되며 다른 레코드 유형은 일반 사용자/에이전트 검색 범위를 유지합니다. 기본 검색 동작을 유지하려면 min_relevant_results_by_type를 생략합니다.

컨텍스트 카드를 작성할 때 Oracle Agent Memory는 현재 스레드의 메시지와 별도로 메모리 유사 레코드를 검색합니다. 순위 재지정 또는 제거가 구성된 경우 세트를 결합하기 전에 각 결과 세트에 개별적으로 적용됩니다. min_relevant_results_by_type가 제공되면 요청된 각 레코드 유형이 별도로 검색됩니다. 순위 재지정 또는 제거(구성된 경우)도 각 검색 결과에 별도로 적용됩니다. 그러면 모든 메모리 유사 레코드 유형에 대한 다른 검색에서 남아 있는 결과 슬롯을 사용할 수 있습니다.

반면, 여러 record_types를 요청하는 일반 검색에 대해 순위 재지정 또는 제거가 구성된 경우 결합된 검색 결과에 한 번 적용됩니다.

max_relevant_results를 생략하면 요청된 최소 합계가 더 큰 경우가 아니면 Oracle Agent Memory가 기본 관련 결과 예산을 사용합니다. 이 경우 유효 예산이 요청된 최소 합계에 맞게 확장됩니다.

유형 검색 동시실행 조정

컨텍스트 카드를 빌드하면 요청된 각 레코드 유형에 대해 하나의 검색과 모든 메모리 유사 레코드 유형에 대해 하나의 검색이 실행되어 남아 있는 결과 슬롯을 사용할 수 있습니다. 기본적으로 이러한 검색 중 최대 5개가 동시에 실행될 수 있습니다. 라이브 스레드 핸들에 대한 동시 검색 횟수를 줄이려면 스레드를 만들거나 다시 열 때 context_card_type_search_concurrency를 전달합니다. 이 값은 스레드 행에서 지속되지 않습니다.

thread = memory.get_thread(
    "context_card_customization_demo",
    context_card_type_search_concurrency=2,
)

card = thread.get_context_card(
    max_relevant_results=6,
    min_relevant_results_by_type={
        "preference": 1,
        "guideline": 1,
        "message": 1,
    },
)

결론

이 설명서에서는 특정 메모리와 유사한 레코드 유형에 대해 최소 컨텍스트 카드 결과 수를 요청하는 방법과 유형별 검색에 사용되는 병렬 검색 팬아웃을 조정하는 방법을 배웠습니다.

→ 컨텍스트 카드 검색을 사용자정의하는 방법을 배웠으면 이제 Use Oracle Agent Memory Short-Term APIs with LangGraph로 이동할 수 있습니다.

전체 코드

#Copyright © 2026 Oracle and/or its affiliates.
#This software is under the Apache License 2.0
#(LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0) or Universal Permissive License
#(UPL) 1.0 (LICENSE-UPL or https://oss.oracle.com/licenses/upl), at your option.

#Oracle Agent Memory Code Example - Customize Context Card Content
#-----------------------------------------------------------------

##Reserve relevant results by record type

import oracledb

from oracleagentmemory.core import MemoryExtractionConfig, SchemaPolicy
from oracleagentmemory.core.embedders.embedder import Embedder
from oracleagentmemory.core.llms.llm import Llm
from oracleagentmemory.core.oracleagentmemory import OracleAgentMemory

embedder = Embedder(model="YOUR_EMBEDDING_MODEL")
llm = Llm(model="provider/model_id")
db_pool = oracledb.SessionPool(
    user="YOUR DB USER",
    password="YOUR DB PASSWORD",
    dsn="localhost:1521/...",
)
memory_store_id = "T_CARD_CONTENT"

memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_store_id=memory_store_id
)

thread = memory.create_thread(
    thread_id="context_card_customization_demo",
    user_id="user_123",
    agent_id="assistant_456",
    memory_extraction_config=MemoryExtractionConfig(
        memory_extraction_custom_instructions=(
            "Extract restaurant preferences as preference records and assistant "
            "response-style instructions as guideline records."
        )
    ),
)
thread.add_messages(
    [
        {
            "role": "user",
            "content": "I need vegetarian dinner recommendations for Friday.",
        },
        {
            "role": "assistant",
            "content": "I can compare concise options and tradeoffs.",
        },
    ]
)

card = thread.get_context_card(
    max_relevant_results=6,
    min_relevant_results_by_type={
        "preference": 1,
        "guideline": 1,
        "message": 1,
    },
)

prompt_context = card.content
print(prompt_context)

##Tune type search concurrency

thread = memory.get_thread(
    "context_card_customization_demo",
    context_card_type_search_concurrency=2,
)

card = thread.get_context_card(
    max_relevant_results=6,
    min_relevant_results_by_type={
        "preference": 1,
        "guideline": 1,
        "message": 1,
    },
)