自定义上下文卡内容

上下文卡提供有关座席在生成响应时可以使用的对话的紧凑上下文。它可以包括对话线程摘要、相关存储消息和相关记忆。

本指南介绍了如何自定义 Oracle AI Agent Memory 上下文卡中返回的内容。

get_context_card() 返回的上下文卡还可以包括检索主题和相关记录。当座席需要长时间对话的连续性，但不需要将完整记录发送回模型时，请使用上下文卡。这可以减少输入令牌的使用，使代理保持焦点，并通过将相关内存放在提示上下文的前面来减少对某些代理级工具调用的需求。

有关使用 LangGraph 的完整提示压缩工作流，请参见 Use Oracle Agent Memory Short-Term APIs with LangGraph 。有关 API 详细信息，请参阅 OracleThread 和 Context Cards 。

注：当默认检索结果不包括正确的记录类型组合时，使用上下文卡定制。例如，当一般事实主导结果时，应用程序可以为用户首选项或响应指南保留空间。

要为搜索和上下文卡配置结果限制、重新排序、删除或标记预算，请参阅改进搜索结果相关性。

按记录类型请求最小结果

默认情况下，上下文卡检索会一次搜索所有类似内存的记录类型。例如，如果事实或一般记忆排除了首选项或准则，请通过 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> 部分可以包括所请求的类型，然后再包含所有内存类型搜索的其余结果：

<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 代理内存将独立于当前线程中的消息搜索类似内存的记录。配置重新排序或修剪时，在组合这些集合之前，会分别将其应用于每组结果。提供 min_relevant_results_by_type 时，将单独搜索每个请求的记录类型。配置后，重新排序或修剪也会单独应用于每个搜索的结果。然后，对所有类似内存的记录类型进行其他搜索，即可使用保留的任何结果插槽。

相比之下，如果为请求多个 record_types 的常规搜索配置了重新排序或修剪，则会对组合的搜索结果应用一次。

如果省略 max_relevant_results，则 Oracle Agent Memory 将使用默认的相关结果预算，除非请求的最小总和更大。在这种情况下，有效预算将扩大到符合所要求的最低总额。

优化类型搜索并发

构建上下文卡可以为每个请求的记录类型运行一个搜索，并在所有类似内存的记录类型中运行一个搜索，以使用剩余的任何结果插槽。默认情况下，最多可以同时运行五个搜索。要减少实时线程句柄的同时搜索次数，请在创建或重新打开线程时传递 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,
    },
)

结论

在本指南中，我们了解了如何为特定类似内存的记录类型请求最小上下文卡结果计数，以及如何优化每类型检索所使用的并行搜索扇出。

→在了解如何自定义上下文卡检索后，现在可以继续将 Oracle Agent Memory Short-Term API 与 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,
    },
)