自定义上下文卡内容

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

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

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

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

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

按记录类型请求最小结果

默认情况下，上下文卡检索会一次搜索所有类似内存的记录类型。例如，如果事实或一般记忆排除了首选项或准则，请通过 min_relevant_results_by_type 请求特定记录类型的最小计数。

import oracledb

from oracleagentmemory.core import MemoryExtractionConfig
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="YOUR DB CONNECT STRING",
)

memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)

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,
    },
)

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"。省略 min_relevant_results_by_type 以保留缺省的 all-memory-type 检索行为。

如果省略 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,
    },
)

小结

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

在了解如何自定义上下文卡检索后，您现在可以继续将代理内存短期 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
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="YOUR DB CONNECT STRING",
)

memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)

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,
    },
)

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,
    },
)