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

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

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

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

LangGraphを使用した完全なプロンプト圧縮ワークフローについては、エージェント・メモリーのLangGraphでの短期APIの使用を参照してください。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を省略すると、デフォルトの全メモリー・タイプの取得動作が維持されます。

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

まとめ

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

コンテキスト・カード取得をカスタマイズする方法を学習した後、「LangGraphでのエージェント・メモリー短期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
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,
    },
)