コンテキスト・カード・コンテンツのカスタマイズ

コンテキスト・カードは、エージェントがレスポンスの生成時に使用できる会話に関するコンパクトなコンテキストを提供します。これには、会話スレッド・サマリー、関連する格納済メッセージおよび関連するメモリーを含めることができます。

このガイドでは、Oracle AI Agent Memoryコンテキスト・カードで返されるコンテンツをカスタマイズする方法について説明します。

get_context_card()によって返されるコンテキスト・カードには、取得トピックおよび関連するレコードを含めることもできます。エージェントが長い会話にわたって継続性を必要とするが、完全なトランスクリプトをモデルに戻す必要がない場合は、コンテキスト・カードを使用します。これにより、プロンプト・コンテキストに適切なメモリーを前面に配置することで、入力トークンの使用を削減し、エージェントに焦点を合わせ、エージェント・レベルのツール・コールの必要性を低減できます。

LangGraphを使用したプロンプト圧縮ワークフローの詳細は、「LangGraphでのOracle Agent Memory Short-Term APIの使用」を参照してください。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 Agent Memoryは、現在のスレッド内のメッセージとは別にメモリーに似たレコードを検索します。再ランキングまたはプルーニングを構成すると、セットが結合される前に、各結果セットに個別に適用されます。min_relevant_results_by_typeを指定すると、リクエストされた各レコード・タイプが個別に検索されます。再ランキングまたはプルーニング(構成されている場合)も、各検索の結果に個別に適用されます。メモリーに類似したすべてのレコード・タイプにわたる別の検索では、残っているすべての結果スロットを使用できます。

比較すると、複数のrecord_typesをリクエストする通常の検索に対して再ランキングまたはプルーニングが構成されている場合は、結合された検索結果に1回適用されます。

max_relevant_resultsを省略すると、Oracle Agent Memoryは、要求された最小合計が大きい場合を除き、デフォルトの関連結果予算を使用します。その場合、有効予算は要求された最小合計に合わせて拡張されます。

チューニング・タイプ検索同時実行

コンテキストカードを構築すると、要求されたレコードタイプごとに1つの検索を実行できるほか、すべてのメモリに似たレコードタイプで1つの検索を実行して、残っている結果スロットを使用できます。デフォルトでは、これらの検索のうち最大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,
    },
)

まとめ

このガイドでは、特定のメモリーに似たレコード・タイプについて、コンテキスト・カードの最小結果数をリクエストする方法と、タイプごとの取得で使用されるパラレル検索ファンアウトをチューニングする方法を学習しました。

→ コンテキスト・カード取得をカスタマイズする方法を学習した後、「LangGraphでOracle Agent Memory Short-Term APIを使用」に進むことができます。

完全コード

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