自訂自動記憶體擷取

自動擷取記憶體可擷取有用的詳細資訊，無需進行其他配置。自訂指示可讓應用程式在需要針對特定使用案例量身打造預設行為時，為擷取處理新增指引。

本指南說明如何使用自訂指示，引導 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

繁體中文

從執行緒訊息擷取支援記憶

建立支援討論串並新增使用者和助理訊息。此範例會設定 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 會在擷取記憶體之後，以一個額外的要求來決定。

連結類型描述新記憶體與現有候選人的關係。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

繁體中文

修訂一個執行緒的指示

當一個繫線需要比從屬端預設值更窄的擷取原則時，請將 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

繁體中文

更新或清除執行緒指示

使用 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

繁體中文

結論

在本指南中，我們學習如何設定用戶端層級的自訂擷取指示、設定自動記憶體連結、覆寫特定執行緒的擷取指示，以及更新或清除執行緒層級的擷取指示。

→ 瞭解如何自訂自動擷取之後，您現在可以繼續使用 Oracle 代理程式記憶體短期 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 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
    ),
)