自動メモリー抽出のカスタマイズ

自動メモリー抽出では、追加の構成なしで有用な詳細を取得できます。カスタム指示により、アプリケーションは、特定のユース・ケースに対してデフォルトの動作を調整する必要がある場合に、抽出プロセスにガイダンスを追加できます。

このガイドでは、Oracle AI Agent Memoryの自動メモリー抽出をカスタム手順でガイドする方法について説明します。

カスタム手順を使用すると、永続メモリーとして保持する価値のある詳細に関するドメイン固有のガイダンスを提供できます。これらは、記憶に残る可能性のあるすべての詳細を同じように処理するのではなく、アプリケーションの抽出で専門家の判断、製品ポリシーまたはワークフロー固有の優先度を反映する必要がある場合に役立ちます。

ノート:メモリー抽出がアプリケーション固有のガイダンスに従う必要がある場合は、カスタム手順を使用してください。追加のガイダンスが不要な場合は、デフォルトの抽出が適切です。

ヒント: oracleagentmemoryのインストール方法については、エージェント・メモリーのスタート・ガイドを参照してください。この例にローカルのOracle AI Databaseが必要な場合は、「Oracle AI Databaseをローカルで実行」に従います。

クライアントレベルの抽出手順の構成

Oracle DB接続またはプール、埋込み、LLMおよびサポートに焦点を当てた抽出手順を使用して、Oracle Agent Memoryコンポーネントを作成します。これらの命令は、スレッドが独自の抽出命令を提供しないかぎり、このクライアントを介して作成またはロードされたスレッドに適用されます。

import oracledb

from oracleagentmemory.core import MemoryExtractionConfig, MemoryLinkExtractionMode, 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="YOUR_MEMORY_LLM")
db_pool = oracledb.SessionPool(
    user="YOUR DB USER",
    password="YOUR DB PASSWORD",
    dsn="localhost:1521/...",
)
memory_store_id = "T_MEM_EXTRACTION"

support_extraction_instructions = """
Only extract customer support facts:
- order ids
- return requests
- delivery problems
Ignore greetings, small talk, and one-off troubleshooting text.
""".strip()

memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
    memory_extraction_config=MemoryExtractionConfig(
        memory_extraction_custom_instructions=support_extraction_instructions
    ),
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_store_id=memory_store_id,
)

APIリファレンス: OracleAgentMemory

OracleThread

スレッド・メッセージからのサポート・メモリーの抽出

サポート・スレッドを作成し、ユーザーおよびアシスタントのメッセージを追加します。この例では、memory_extraction_config=MemoryExtractionConfig(memory_extraction_frequency=1)を設定して、add_messages()が挿入されたターンに対して自動抽出を即時に実行します。カスタム命令により、抽出されたメモリーは注文ID、返品要求および配送の問題に集中します。

support_thread = memory.create_thread(
    thread_id="support_ticket_7421",
    user_id="customer_123",
    memory_extraction_config=MemoryExtractionConfig(memory_extraction_frequency=1),
)

#add_messages persists the turn and runs automated memory extraction because
#MemoryExtractionConfig(memory_extraction_frequency=1) is set for this thread.
support_thread.add_messages(
    [
        {
            "role": "user",
            "content": (
                "Hi, order 7421 arrived damaged. I need a return request "
                "and a replacement delivery."
            ),
        },
        {
            "role": "assistant",
            "content": "I can help start the return request for order 7421.",
        },
    ]
)

results = support_thread.search(
    "return request order 7421",
    max_results=5,
    record_types=["fact"],
)
for result in results:
    print(f"- [{result.record.record_type}] {result.content}")
#- [fact] Customer reported damaged order 7421 and requested a return and replacement delivery.

前述の出力は例示です。正確なメモリー・テキストは、構成された抽出LLMに依存しますが、抽出されたメモリーはクライアントに提供されるカスタム指示に従う必要があります。

この違いは、エクストラクタが保持するように求められるメモリーの種類を比較することによって最も簡単に確認できます。

カスタム指示あり

抽出器は耐久の顧客サポートの事実を保ち、挨拶および会話の表現を無視します。

- [fact] Customer reported damaged order 7421 and requested a return and replacement delivery.

カスタム指示なし

デフォルトの抽出プロンプトは操作をサポートするようにスコープ指定されていないため、エクストラクタはより広範な会話メモリーを保持できます。

- [memory] The user contacted support about order 7421 and discussed a damaged delivery.

APIリファレンス: OracleThread

OracleSearch結果

自動メモリー・リンクの構成

自動メモリー・リンクは、新しく抽出されたメモリーを関連する既存のメモリーに接続します。SDKは、一連の候補メモリーを取得し、抽出LLMに、型付きリンクを作成するかどうかを尋ねます。デフォルトでは、POST_EXTRACTIONは、メモリーの抽出後に1つの追加リクエストでその決定を行います。

リンク・タイプは、新しいメモリーから既存の候補への関係を示します。supersedes、refinesおよびduplicatesは、古いメモリーを履歴として保持し、無効としてマークします。supportsおよびcontradictsは、両方のメモリーを有効のままにします。自動リンクは、取得された候補に限定されます。関係を常に記録する必要がある場合は、明示的リンクAPIを使用します。

MemoryExtractionConfigを使用して、自動リンクをカスタマイズします。

• memory_link_extraction_modeは、リンクを解決するタイミングを制御します。個別のリンク解決リクエストにはPOST_EXTRACTION、抽出リクエスト内のリンクを解決するにはDURING_EXTRACTION、自動リンクを作成しない場合はDISABLEDを使用します。
• memory_link_extraction_custom_instructionsは、ドメインに適した関係タイプなど、リンク解決プロンプトにガイダンスを追加します。
• memory_link_extraction_token_limitは、抽出後のリンク解決のための入力トークンの合計予算を設定します。1未満の値は、この制限を無効にします。

前述の抽出設定と同様に、これらのフィールドをクライアント・レベルで指定するか、特定のスレッドでオーバーライドします。次の例では、サポート・スレッドを更新して、サポート・ファクト内の意味のある変更のみをリンクします。

memory.update_thread(
    "support_ticket_7421",
    memory_extraction_config=MemoryExtractionConfig(
        memory_link_extraction_mode=MemoryLinkExtractionMode.POST_EXTRACTION,
        memory_link_extraction_custom_instructions=(
            "Only link a new support fact when it supersedes or refines "
            "an existing support fact. Do not create supports or contradicts links."
        ),
        memory_link_extraction_token_limit=8_000,
    ),
)

同じ設定をcreate_thread()に渡すか、クライアントのMemoryExtractionConfigに含めることができます。リンクの手動作成およびリンクされたコンテキストの取得の詳細は、リンクされたメモリー・グラフの作成および検索を参照してください。

APIリファレンス: MemoryExtractionConfig

OracleThread

1つのスレッドのオーバーライド指示

1つのスレッドでクライアントのデフォルトより狭い抽出ポリシーが必要な場合は、memory_extraction_config=MemoryExtractionConfig(memory_extraction_custom_instructions=...)をcreate_thread()に渡します。スレッド・レベルの値は、そのスレッドに対して優先され、スレッド構成によって維持されます。

billing_thread = memory.create_thread(
    thread_id="billing_ticket_9310",
    user_id="customer_123",
    memory_extraction_config=MemoryExtractionConfig(
        memory_extraction_frequency=1,
        memory_extraction_custom_instructions=(
            "Only extract billing facts, invoice identifiers, and payment issues."
        ),
    ),
)

billing_thread.add_messages(
    [
        {
            "role": "user",
            "content": "Invoice INV-9310 was paid twice and needs a refund.",
        }
    ]
)

APIリファレンス: OracleAgentMemory

OracleThread

スレッド指示の更新またはクリア

update_thread()を使用して、既存のスレッドの永続抽出命令を変更します。Noneを渡してスレッド・レベルの命令をクリアし、将来のスレッド・ハンドルがクライアント・レベルの命令を使用するか、何も構成されていない場合はSDKの通常の抽出動作を使用するようにします。

memory.update_thread(
    "support_ticket_7421",
    memory_extraction_config=MemoryExtractionConfig(
        memory_extraction_custom_instructions=(
            "Only extract product defects and replacement requests."
        )
    ),
)

memory.update_thread(
    "support_ticket_7421",
    memory_extraction_config=MemoryExtractionConfig(
        memory_extraction_custom_instructions=None
    ),
)

ノート: get_thread(..., memory_extraction_config=MemoryExtractionConfig(memory_extraction_custom_instructions=...))では、永続スレッド構成を更新せずに、戻されたライブ・スレッド・ハンドルに指示を適用できます。

APIリファレンス: OracleAgentMemory

OracleThread

まとめ

このガイドでは、クライアント・レベルのカスタム抽出手順の構成、自動メモリー・リンクの構成、特定のスレッドの抽出手順の上書き、およびスレッド・レベルの抽出手順の更新またはクリア方法を学習しました。

→ 自動抽出をカスタマイズする方法を学習した後、「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 Automatic Memory Extraction
#------------------------------------------------------------------------

##Configure custom memory extraction instructions

import oracledb

from oracleagentmemory.core import MemoryExtractionConfig, MemoryLinkExtractionMode, 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="YOUR_MEMORY_LLM")
db_pool = oracledb.SessionPool(
    user="YOUR DB USER",
    password="YOUR DB PASSWORD",
    dsn="localhost:1521/...",
)
memory_store_id = "T_MEM_EXTRACTION"

support_extraction_instructions = """
Only extract customer support facts:
- order ids
- return requests
- delivery problems
Ignore greetings, small talk, and one-off troubleshooting text.
""".strip()

memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
    memory_extraction_config=MemoryExtractionConfig(
        memory_extraction_custom_instructions=support_extraction_instructions
    ),
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_store_id=memory_store_id,
)

##Extract support memories from thread messages

support_thread = memory.create_thread(
    thread_id="support_ticket_7421",
    user_id="customer_123",
    memory_extraction_config=MemoryExtractionConfig(memory_extraction_frequency=1),
)

#add_messages persists the turn and runs automated memory extraction because
#MemoryExtractionConfig(memory_extraction_frequency=1) is set for this thread.
support_thread.add_messages(
    [
        {
            "role": "user",
            "content": (
                "Hi, order 7421 arrived damaged. I need a return request "
                "and a replacement delivery."
            ),
        },
        {
            "role": "assistant",
            "content": "I can help start the return request for order 7421.",
        },
    ]
)

results = support_thread.search(
    "return request order 7421",
    max_results=5,
    record_types=["fact"],
)
for result in results:
    print(f"- [{result.record.record_type}] {result.content}")
#- [fact] Customer reported damaged order 7421 and requested a return and replacement delivery.

##Configure automatic memory linking

memory.update_thread(
    "support_ticket_7421",
    memory_extraction_config=MemoryExtractionConfig(
        memory_link_extraction_mode=MemoryLinkExtractionMode.POST_EXTRACTION,
        memory_link_extraction_custom_instructions=(
            "Only link a new support fact when it supersedes or refines "
            "an existing support fact. Do not create supports or contradicts links."
        ),
        memory_link_extraction_token_limit=8_000,
    ),
)

##Override custom instructions for one thread

billing_thread = memory.create_thread(
    thread_id="billing_ticket_9310",
    user_id="customer_123",
    memory_extraction_config=MemoryExtractionConfig(
        memory_extraction_frequency=1,
        memory_extraction_custom_instructions=(
            "Only extract billing facts, invoice identifiers, and payment issues."
        ),
    ),
)

billing_thread.add_messages(
    [
        {
            "role": "user",
            "content": "Invoice INV-9310 was paid twice and needs a refund.",
        }
    ]
)

##Update or clear thread custom instructions

memory.update_thread(
    "support_ticket_7421",
    memory_extraction_config=MemoryExtractionConfig(
        memory_extraction_custom_instructions=(
            "Only extract product defects and replacement requests."
        )
    ),
)

memory.update_thread(
    "support_ticket_7421",
    memory_extraction_config=MemoryExtractionConfig(
        memory_extraction_custom_instructions=None
    ),
)